crane-index-filter

Modify remote index

$ crane index filter

$ crane index filter --platform [platform1 platform2 ...]

$ crane index filter [[-t|--tags]] [tag_name]

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

crane index filter SOURCE_INDEX [--output PATH] [--os OS] [--arch ARCH] [--variant VARIANT] [--platform PLATFORM] [--features FEATURES] [--os-version VERSION] [--os-features OS_FEATURES]

SOURCE_INDEX
    The reference to the source OCI image index (e.g., gcr.io/my-repo/my-image:latest) to be filtered.

--output, -o PATH
    Specifies the path where the filtered OCI image index should be written. If not provided, the output is typically written to standard output.

--os OS
    Filters manifests by the specified operating system (e.g., linux, windows).

--arch ARCH
    Filters manifests by the specified architecture (e.g., amd64, arm64, ppc64le).

--variant VARIANT
    Filters manifests by the specified architecture variant (e.g., v7, v8 for ARM architectures).

--platform PLATFORM
    Filters manifests by a combined platform string (e.g., linux/arm64/v8 or windows/amd64). This flag can be used multiple times to include multiple platforms.

--features FEATURES
    Filters manifests by additional image features.

--os-version VERSION
    Filters manifests by the operating system version.

--os-features OS_FEATURES
    Filters manifests by specific operating system features.

--help
    Displays help information for the `index filter` subcommand.

The `crane-index-filter` command is a subcommand of the `crane` utility, specifically invoked as crane index filter. It is a powerful tool designed for manipulating OCI (Open Container Initiative) image indexes, also known as manifest lists. An OCI image index is a collection of references to image manifests, often used for multi-platform images (e.g., images supporting different CPU architectures like amd64, arm64, or operating systems like linux, windows).

This command allows users to create a new, filtered image index from an existing one, by specifying criteria such as operating system, architecture, or architecture variant. This is particularly useful in scenarios where you need to extract a specific platform's image from a fat manifest for deployment, testing, or optimized distribution, without pulling the entire multi-platform artifact. The filtered index will only contain references to the manifests that match the specified criteria, making it easier to manage and deploy container images for specific environments.

The command `crane-index-filter` is not a standalone executable found in typical Linux distributions. It is part of the `crane` utility, which must be installed separately. The correct invocation is crane index filter. Users must be familiar with OCI image specifications, especially concerning manifest lists, to effectively use this command.

The filtering operation creates a new index; it does not modify the original source index in place. For pushing the filtered index to a registry, additional crane commands (like crane push) are required.

An OCI Image Index (often referred to as a 'manifest list' or 'fat manifest') is a standard way to group multiple image manifests, typically for different platforms (OS/architecture combinations), under a single tag. This allows tools like Docker or Kubernetes to automatically select the correct image for the host platform. crane index filter provides a mechanism to manipulate these indexes, enabling precise control over which platform variants are included or excluded from a new index.

This command is invaluable in CI/CD pipelines for:
1. Optimized Image Distribution: Creating a smaller, platform-specific image index to serve to a specific environment, reducing unnecessary downloads.
2. Testing Specific Platforms: Isolating a particular platform's image for focused testing.
3. Image Curating: Removing unwanted or unsupported platform variants from a publicly distributed multi-platform image.

The `crane` utility is part of the `go-containerregistry` project (github.com/google/go-containerregistry), initially developed by Google and later open-sourced. It provides a set of libraries and CLIs for working with OCI images and registries. The `index filter` subcommand was introduced as OCI image indexes gained prominence for distributing multi-platform container images, enabling users to efficiently select or curate specific platform variants without manual parsing of manifest lists. Its development reflects the growing need for robust, programmatic control over container image lifecycle management.

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