crane-tag

Tag remote image

$ crane tag [image_name] [tag_name]

$ crane tag [[-h|--help]]

crane tag [flags] <SOURCE_IMAGE> <TARGET_TAG>

<SOURCE_IMAGE>
    The reference to the source image to be tagged. This can be in the format of `registry/repository:oldtag` or `registry/repository@sha256:...`.

<TARGET_TAG>
    The new tag reference to be applied. This is typically in the format of `registry/repository:newtag`.

--allow-nondistributable-artifacts
    Allow copying of nondistributable artifacts. Use with caution as these layers may not be supported by all registries.

--daemon-host string
    Specify the host of the daemon, if connecting to a daemon socket (e.g., for pulling from or pushing to a local Docker daemon). Default is `unix:///var/run/docker.sock`.

--platform string
    Specify the target platform for the image (e.g., `linux/amd64`, `linux/arm64`, or `all` to tag all platforms in a multi-platform image). Only relevant if the source is a multi-platform image and you want to tag a specific platform.

-h, --help
    Display help information for the `tag` command.

--insecure
    Allow connections to registries over HTTP or skip TLS verification. Use with extreme caution in production environments.

--preserve-digests
    Do not remove the digest from the target tag. Defaults to `true`.

--repository string
    Specify the target repository for the new tag, if different from the source image's repository. Rarely used with `crane tag` as the target tag typically implies the repository.

--skip-tls-verify
    Skip TLS verification. Functionally similar to `--insecure` regarding TLS. Use with extreme caution.

--user-agent string
    Specify a custom User-Agent string to use in registry requests.

The `crane tag` command is a subcommand of the crane utility, designed for direct interaction with container registries. It allows users to apply a new tag to an existing image manifest within a remote registry without needing to pull the image locally. This command works by creating a new reference (tag) that points to the same underlying image manifest (identified by a digest or an existing tag).

This functionality is crucial for various container workflows, especially in CI/CD pipelines, where images need to be promoted through different environments (e.g., from `dev` to `staging` to `production`) or aliased for easier reference. Unlike `docker tag` which often involves local image manipulation and a subsequent push, `crane tag` operates entirely remotely, making it efficient for registry-to-registry operations or for updating tags on a remote image directly. It supports various registry authentication methods, typically leveraging `~/.docker/config.json` or environment variables.

crane tag requires network connectivity to the remote registry.
Appropriate authentication credentials and permissions for the target registry are mandatory for a successful operation.
Using `--insecure` or `--skip-tls-verify` flag should be avoided in production environments as it compromises security.
This command only manipulates tags and image manifests; it does not copy or alter the underlying image layers. It simply creates a new pointer to an existing image content.

crane primarily uses the Docker configuration file (`~/.docker/config.json`) for authenticating with registries. It can also pick up credentials from environment variables such as `DOCKER_USERNAME` and `DOCKER_PASSWORD`.

It is important to understand that crane tag does not change the actual image content. Instead, it creates a new tag that points to an existing image manifest (identified by its digest). This means if you tag `myrepo/myimage@sha256:abcd` with `myrepo/myimage:newversion`, both references point to the exact same immutable image layers. The image content remains unchanged.

Common use cases include:
Promoting Images: Tagging an image from a `dev` tag to a `staging` or `production` tag after successful testing.
Creating Release Tags: Applying version-specific tags (e.g., `v1.2.3`) to an image that was previously tagged with `latest` or a build-specific identifier.
Aliasing: Creating multiple convenient tags that all refer to the same immutable image.

The `crane` utility is part of the `go-containerregistry` project, developed by Google, aimed at providing a set of Go libraries and CLIs for working with OCI (Open Container Initiative) image registries. `crane tag` is a fundamental subcommand that has been available since the early versions of `crane`. Its development was driven by the need for a lightweight, efficient tool to manage container images directly on remote registries without requiring a local Docker daemon or image pull/push operations. This makes it particularly valuable for automated build and release pipelines where direct registry manipulation is preferred for speed and simplicity.

crane(1), docker tag(1), skopeo(1), regctl(1)