mirror of https://github.com/docker/cli.git
docs: update prose about image tag/name format
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
parent
6ed137f7dd
commit
2c6b80491b
|
@ -12,38 +12,50 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
|
||||||
|
|
||||||
## Description
|
## Description
|
||||||
|
|
||||||
A full image name has the following format and components:
|
A Docker image reference consists of several components that describe where the
|
||||||
|
image is stored and its identity. These components are:
|
||||||
|
|
||||||
`[HOST[:PORT_NUMBER]/]PATH`
|
```text
|
||||||
|
[HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]
|
||||||
|
```
|
||||||
|
|
||||||
- `HOST`: The optional registry hostname specifies where the image is located.
|
`HOST`
|
||||||
The hostname must comply with standard DNS rules, but may not contain
|
: Specifies the registry location where the image resides. If omitted, Docker
|
||||||
underscores. If you don't specify a hostname, the command uses Docker's public
|
defaults to Docker Hub (`docker.io`).
|
||||||
registry at `registry-1.docker.io` by default. Note that `docker.io` is the
|
|
||||||
canonical reference for Docker's public registry.
|
|
||||||
- `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a
|
|
||||||
registry port number in the format `:8080`.
|
|
||||||
- `PATH`: The path consists of slash-separated components. Each
|
|
||||||
component may contain lowercase letters, digits and separators. A separator is
|
|
||||||
defined as a period, one or two underscores, or one or more hyphens. A component
|
|
||||||
may not start or end with a separator. While the
|
|
||||||
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)
|
|
||||||
supports more than two slash-separated components, most registries only support
|
|
||||||
two slash-separated components. For Docker's public registry, the path format is
|
|
||||||
as follows:
|
|
||||||
- `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a
|
|
||||||
user's or an organization's namespace. The second, mandatory component is the
|
|
||||||
repository name. When the namespace is not present, Docker uses `library`
|
|
||||||
as the default namespace.
|
|
||||||
|
|
||||||
After the image name, the optional `TAG` is a custom, human-readable manifest
|
`PORT`
|
||||||
identifier that's typically a specific version or variant of an image. The tag
|
: An optional port number for the registry, if necessary (for example, `:5000`).
|
||||||
must be valid ASCII and can contain lowercase and uppercase letters, digits,
|
|
||||||
underscores, periods, and hyphens. It can't start with a period or hyphen and
|
|
||||||
must be no longer than 128 characters. If you don't specify a tag, the command uses `latest` by default.
|
|
||||||
|
|
||||||
You can group your images together using names and tags, and then
|
`NAMESPACE/REPOSITORY`
|
||||||
[push](image_push.md) them to a registry.
|
: The namespace (optional) usually represents a user or organization. The
|
||||||
|
repository is required and identifies the specific image. If the namespace is
|
||||||
|
omitted, Docker defaults to `library`, the namespace reserved for Docker
|
||||||
|
Official Images.
|
||||||
|
|
||||||
|
`TAG`
|
||||||
|
: An optional identifier used to specify a particular version or variant of the
|
||||||
|
image. If no tag is provided, Docker defaults to `latest`.
|
||||||
|
|
||||||
|
### Example image references
|
||||||
|
|
||||||
|
`example.com:5000/team/my-app:2.0`
|
||||||
|
|
||||||
|
- Host: `example.com`
|
||||||
|
- Port: `5000`
|
||||||
|
- Namespace: `team`
|
||||||
|
- Repository: `my-app`
|
||||||
|
- Tag: `2.0`
|
||||||
|
|
||||||
|
`alpine`
|
||||||
|
|
||||||
|
- Host: `docker.io` (default)
|
||||||
|
- Namespace: `library` (default)
|
||||||
|
- Repository: `alpine`
|
||||||
|
- Tag: `latest` (default)
|
||||||
|
|
||||||
|
For more information on the structure and rules of image naming, refer to the
|
||||||
|
[Distribution reference](https://pkg.go.dev/github.com/distribution/reference#pkg-overview)
|
||||||
|
as the canonical definition of the format.
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue