crane-validate

Validate an image

$ crane validate

$ crane validate --fast

$ crane validate --remote [image_name]

$ crane validate --tarball [path/to/tarball]

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

crane validate image_reference [flags]

image_reference
    The full OCI image or manifest list reference (e.g., registry/repo:tag or registry/repo@sha256:digest) to be validated.

-f, --full
    Performs a full validation, including all referenced layers and blobs, in addition to the image manifest. By default, only the manifest is validated.

--platform string
    Specifies the target platform (e.g., linux/amd64, windows/arm64) when validating a manifest list. This ensures validation for a specific architecture.

-r, --recursive
    When validating a manifest list, this flag ensures that all individual images referenced within the list are also recursively validated.

The crane-validate command is a subcommand of the crane utility, a powerful Go-based command-line tool developed by Google's go-containerregistry project. It is specifically designed to interact with remote Docker and OCI registries without requiring a local Docker daemon.

The primary function of crane-validate is to verify that a specified OCI (Open Container Initiative) image or manifest list adheres strictly to the OCI Distribution Specification. This ensures the integrity and correctness of container artifacts, making it an invaluable tool for CI/CD pipelines, conformance testing, and maintaining robust image supply chains.

By default, it primarily validates the image manifest. However, with the --full flag, it extends its validation to include all referenced layers and blobs, providing a comprehensive check. It also supports validating specific platforms within a multi-platform manifest list and recursively validating all images pointed to by a manifest list, ensuring broad applicability across various container image architectures.

crane-validate requires network connectivity to access the remote container registry where the image is stored. The validation performed is strictly against the OCI Distribution Specification, not necessarily for compatibility with specific container runtimes or Docker daemon versions.

The crane tool itself is an external utility and may need to be installed separately, as it is not typically part of standard Linux distribution packages.

Here are some common usage patterns for crane-validate:

Validate a basic image manifest:
crane validate myregistry.com/myimage:latest

Perform a full validation, including all layers:
crane validate --full myregistry.com/myimage:v1.0

Validate a specific platform within a multi-arch manifest:
crane validate --platform linux/arm64 myregistry.com/multilayout:rc

Recursively validate all images referenced in a manifest list:
crane validate --recursive myregistry.com/app:latest

The crane-validate command exits with a status of 0 if the image or manifest list passes all validation checks. A non-zero exit status indicates that validation failed due to non-compliance with the OCI specification or an operational error.

The crane CLI tool emerged from Google's go-containerregistry project, which aimed to provide a robust Go library for interacting with OCI and Docker registries programmatically. The development of crane, and subsequently its validate subcommand, was driven by the need for a stateless, daemon-less tool to manage and inspect container images, crucial for serverless environments and CI/CD pipelines. The validate subcommand specifically addresses the critical requirement of ensuring image integrity and compliance with the evolving OCI specifications.

crane(1), skopeo(1), podman(1), docker(1)