diff --git a/content/en/docs/concepts/containers/images.md b/content/en/docs/concepts/containers/images.md index 8602d6c98d..2eab2c8aa4 100644 --- a/content/en/docs/concepts/containers/images.md +++ b/content/en/docs/concepts/containers/images.md @@ -33,17 +33,35 @@ Container images are usually given a name such as `pause`, `example/mycontainer` Images can also include a registry hostname; for example: `fictional.registry.example/imagename`, and possibly a port number as well; for example: `fictional.registry.example:10443/imagename`. -If you don't specify a registry hostname, Kubernetes assumes that you mean the Docker public registry. +If you don't specify a registry hostname, Kubernetes assumes that you mean the [Docker public registry](https://hub.docker.com/). +You can change this behaviour by setting default image registry in [container runtime](/docs/setup/production-environment/container-runtimes/) configuration. -After the image name part you can add a _tag_ (in the same way you would when using with commands -like `docker` or `podman`). Tags let you identify different versions of the same series of images. +After the image name part you can add a _tag_ or _digest_ (in the same way you would when using with commands +like `docker` or `podman`). Tags let you identify different versions of the same series of images. +Digests are a unique identifier for a specific version of an image. Digests are hashes of the image's content, +and are immutable. Tags can be moved to point to different images, but digests are fixed. Image tags consist of lowercase and uppercase letters, digits, underscores (`_`), -periods (`.`), and dashes (`-`). -There are additional rules about where you can place the separator -characters (`_`, `-`, and `.`) inside an image tag. +periods (`.`), and dashes (`-`). It can be up to 128 characters long. And must follow the +next regex pattern: `[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}` +You can read more about and find validation regex in the +[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#workflow-categories). If you don't specify a tag, Kubernetes assumes you mean the tag `latest`. +Image digests consists of a hash algorithm (such as `sha256`) and a hash value. For example: +`sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07` +You can find more information about digests format in the +[OCI Image Specification](https://github.com/opencontainers/image-spec/blob/v1.1.0/descriptor.md#digests). + +Some image name examples that Kubernetes can use are: + +- `busybox` - Image name only, no tag or digest. Kubernetes will use Docker public registry and latest tag. (Same as `docker.io/library/busybox:latest`) +- `busybox:1.32.0` - Image name with tag. Kubernetes will use Docker public registry. (Same as `docker.io/library/busybox:1.32.0`) +- `registry.k8s.io/pause:latest` - Image name with a custom registry and latest tag. +- `registry.k8s.io/pause:3.5` - Image name with a custom registry and non-latest tag. +- `registry.k8s.io/pause@sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07` - Image name with digest. +- `registry.k8s.io/pause:3.5@sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07` - Image name with tag and digest. Only digest will be used for pulling. + ## Updating images When you first create a {{< glossary_tooltip text="Deployment" term_id="deployment" >}},