crane-index-append

Append manifest to a remote index

$ crane index append

$ crane index append [[-m|--manifest]] [manifest_name1 manifest_name2 ...]

$ crane index append [[-t|--tag]] [tag_name]

$ crane index append --docker-empty-base

$ crane index append --flatten

$ crane index append [[-h|--help]]

crane index append [flags] TARGET_INDEX_REF IMAGE_TO_APPEND_REF...

TARGET_INDEX_REF
    The reference (e.g., registry/repo:tag or registry/repo@sha256:digest) of the OCI image index to which manifests will be appended. If this index does not exist, crane will initialize it as a new OCI image index.

IMAGE_TO_APPEND_REF
    One or more references (e.g., registry/repo:tag or registry/repo@sha256:digest) of the image manifests or other OCI image indexes to append to the TARGET_INDEX_REF.

--platform string
    Specifies the platform (e.g., os/arch[/variant], like linux/amd64 or windows/arm64/v7) for the IMAGE_TO_APPEND_REF being added. This is crucial for properly describing entries within a multi-architecture index.

--json
    Outputs the resulting OCI index manifest to standard output in JSON format after the append operation is complete.

--pretty
    Used in conjunction with --json to pretty-print the JSON output, making it more human-readable.

--sort
    Sorts the appended manifests within the OCI index by their platform descriptors. This helps maintain a consistent order in the manifest list.

--help
    Displays help information for the crane index append command.

--username string
    Username for authenticating with the image registry.

--password string
    Password for authenticating with the image registry.

--insecure
    Allow connecting to insecure registries (those not using HTTPS or with self-signed certificates). Use with caution.

--config path
    Path to a config.json file containing registry credentials, typically ~/.docker/config.json.

The crane index append command is a sub-command of the crane tool, which is a powerful, Go-based command-line utility developed by GoogleContainerTools for interacting with OCI (Open Container Initiative) compatible image registries. It provides low-level access to OCI manifests and blobs, making it ideal for automation and scripting where direct registry manipulation is required.

Specifically, crane index append is used to add one or more image manifests or other OCI index manifests to an existing OCI image index. An OCI image index is a list of image manifests, often used to create multi-architecture images (e.g., a single tag pointing to different images for Linux/amd64, Linux/arm64, Windows, etc.). If the specified target index does not exist, crane will typically create a new OCI image index and then append the provided manifests to it.

This command is invaluable in CI/CD pipelines for managing container images, especially when building and publishing multi-platform images from separate builds. It allows for the incremental construction or modification of complex image indexes directly on the registry without requiring a local Docker daemon or extensive image pulling.

Network connectivity to the target image registries is required for this command to function. Proper authentication credentials (username/password or config file) may be necessary to pull or push manifests, especially to private registries. When appending to an existing index, ensure that the TARGET_INDEX_REF truly refers to an OCI image index, as appending to a regular image manifest might lead to unexpected behavior or errors.

An OCI Image Index (also known as a manifest list) is a standard OCI artifact that references multiple image manifests. It allows a single tag (e.g., my-app:latest) to resolve to different image manifests based on characteristics like operating system and architecture. This is fundamental for distributing multi-platform images, where users can pull the same tag and automatically get the correct image for their environment.

crane index append is frequently used for:
1. Multi-Architecture Image Creation: After building distinct images for different architectures (e.g., my-app:linux-amd64, my-app:linux-arm64), these can be combined into a single multi-arch index (my-app:latest).
2. Bundling Related Images: Grouping different versions or variants of an application under one index for easier management.
3. CI/CD Pipelines: Automating the process of updating or creating new image indexes as part of a continuous integration and delivery workflow.

crane was developed by the GoogleContainerTools team to provide a lightweight, Go-based alternative to the docker CLI for interacting directly with OCI (Open Container Initiative) image registries. It emerged from the need for simpler, scriptable tooling for registry operations without requiring a full Docker daemon. crane index append is a core part of its functionality, enabling advanced manipulation of OCI image indexes, especially critical for multi-architecture image workflows in modern container ecosystems. Its development is open-source and actively maintained on GitHub.

crane(1), crane index create(1), crane index delete(1), crane index modify(1), crane push(1), docker(1), oras(1)