Carvel Logo

Bundle your bits with guaranteed immutability

Package, distribute, and relocate your Kubernetes configuration and dependent OCI images as one OCI artifact: a bundle. Consume bundles with confidence that their contents are unchanged after relocation.

Unified distribution

A bundle captures your configuration files and a list of references to images on which they depend. Copying your bundle will copy your configuration files along with the referenced images to your destination registry. imgpkg treats the whole thing as one.

OCI Registry-compliant

imgpkg packages your files into OCI images per OCI image specification, allowing the image to be pushed to any registry (e.g. DockerHub, Harbor, ECR, GCR, etc.).

Immutable references

Bundles are identified with a unique sha256 digest based on the file contents. imgpkg uses that digest to ensure that the copied contents are identical to those originally pushed.

Features

Content agnostic

imgpkg makes no assumptions about the contents of bundles. It can manage all kinds of container+configuration files: Kubernetes deployments, Machine Learning models, etc.

Air-gapped environments

Copy a bundle directly to another registry or into a compressed tarball for offline relocation, then push to a private registry for true air-gapped file transfers.

Lock file input/output

Produces a lock file that can later ensure exactly the same image versions (with digests) are used.

Basic Usage

# Create a bundle in a registry with configuration and image references
$ imgpkg push -b index.docker.io/username/my-bundle:v1.0.0 -f config/

# Pull bundle from registry and interact with its content
$ imgpkg pull -b index.docker.io/username/my-bundle:v1.0.0 -o /tmp/my-bundle

# Copy a bundle (w/ dependent images) to another registry directly
$ imgpkg copy -b index.docker.io/username/my-bundle:v1.0.0 --to-repo=registry.corp.com/apps/my-bundle

# Copy a bundle (w/ dependent images) to local tarball and then to another registry
$ imgpkg copy -b index.docker.io/username/my-bundle:v1.0.0 --to-tar=/tmp/my-bundle.tar
$ imgpkg copy --tar /tmp/my-bundle.tar --to-repo=registry.corp.com/apps/my-bundle

Getting started

To help you get started, see the documentation.