Skip to content

Commit 523a119

Browse files
committed
feat: Update image name documentation
1 parent e42b500 commit 523a119

File tree

1 file changed

+24
-6
lines changed

1 file changed

+24
-6
lines changed

content/en/docs/concepts/containers/images.md

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33,17 +33,35 @@ Container images are usually given a name such as `pause`, `example/mycontainer`
3333
Images can also include a registry hostname; for example: `fictional.registry.example/imagename`,
3434
and possibly a port number as well; for example: `fictional.registry.example:10443/imagename`.
3535

36-
If you don't specify a registry hostname, Kubernetes assumes that you mean the Docker public registry.
36+
If you don't specify a registry hostname, Kubernetes assumes that you mean the [Docker public registry](https://hub.docker.com/).
37+
You can change this behaviour by setting default image registry in [container runtime](/docs/setup/production-environment/container-runtimes/) configuration.
3738

38-
After the image name part you can add a _tag_ (in the same way you would when using with commands
39-
like `docker` or `podman`). Tags let you identify different versions of the same series of images.
39+
After the image name part you can add a _tag_ or _digest_ (in the same way you would when using with commands
40+
like `docker` or `podman`). Tags let you identify different versions of the same series of images.
41+
Digests are a unique identifier for a specific version of an image. Digests are hashes of the image's content,
42+
and are immutable. Tags can be moved to point to different images, but digests are fixed.
4043

4144
Image tags consist of lowercase and uppercase letters, digits, underscores (`_`),
42-
periods (`.`), and dashes (`-`).
43-
There are additional rules about where you can place the separator
44-
characters (`_`, `-`, and `.`) inside an image tag.
45+
periods (`.`), and dashes (`-`). It can be up to 128 characters long. And must follow the
46+
next regex pattern: `[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}`
47+
You can read more about and find validation regex in the
48+
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#workflow-categories).
4549
If you don't specify a tag, Kubernetes assumes you mean the tag `latest`.
4650

51+
Image digests consists of a hash algorithm (such as `sha256`) and a hash value. For example:
52+
`sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07`
53+
You can find more information about digests format in the
54+
[OCI Image Specification](https://github.com/opencontainers/image-spec/blob/v1.1.0/descriptor.md#digests).
55+
56+
Some image name examples that Kubernetes can use are:
57+
58+
- `busybox` - Image name only, no tag or digest. Kubernetes will use Docker public registry and latest tag. (Same as `docker.io/library/busybox:latest`)
59+
- `busybox:1.32.0` - Image name with tag. Kubernetes will use Docker public registry. (Same as `docker.io/library/busybox:1.32.0`)
60+
- `registry.k8s.io/pause:latest` - Image name with a custom registry and latest tag.
61+
- `registry.k8s.io/pause:3.5` - Image name with a custom registry and non-latest tag.
62+
- `registry.k8s.io/pause@sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07` - Image name with digest.
63+
- `registry.k8s.io/pause:3.5@sha256:1ff6c18fbef2045af6b9c16bf034cc421a29027b800e4f9b68ae9b1cb3e9ae07` - Image name with tag and digest. Only digest will be used for pulling.
64+
4765
## Updating images
4866

4967
When you first create a {{< glossary_tooltip text="Deployment" term_id="deployment" >}},

0 commit comments

Comments
 (0)