Carvel Logo



An OCI image is an artifact that lives within an OCI registry (such as DockerHub). It can contain an arbitrary number of files.


A bundle is an OCI image that holds 0+ arbitrary files and 0+ references to dependent OCI images (which may also be bundles). By tracking dependent images, imgpkg can copy bundles across registries.

Referenced images are stored within the .imgpkg directory at the root level of the bundle image.

Bundle diagram

Implementation note: A bundle OCI image has the dev.carvel.imgpkg.bundle label set.

.imgpkg directory

.imgpkg directory contains metadata files describing bundle:

  • images.yml (required) contains ImagesLock configuration that describes 0+ dependent OCI images. Consumers of bundles can rely on this file being always present.

  • bundle.yml (optional) file contains Bundle configuration that contains details about bundle authors, associated websites, etc.

Restrictions for location of .imgpkg directory:

  • Only one .imgpkg directory is allowed across all directories provided via -f to the push command. This restriction ensures there is a single source of bundle metadata and referenced images.

  • The .imgpkg directory must be a direct child of one of the input directories. This prevents any confusion around the scope of the .imgpkg metadata.

Bundle configuration

Used by bundle creators to store general information about the bundle. Stored in .imgpkg/bundle.yml.


kind: Bundle
  name: my-bundle
- name: Full Name
- url:
  • authors (array of structs; optional)
    • name (string) Author name
    • email (string) Author email
  • websites (array of structs; optional)
    • url (string) Related website URL

ImagesLock configuration

An ImagesLock configuration is used to track a collection of image references.

Bundle’s .imgpkg/images.yml contains ImagesLock configuration. That’s how bundle knows which OCI images it references. When copying a bundle imgpkg uses this configuration to know which images to copy.

It can be conveniently generated with kbld:

$ kbld -f config.yml --imgpkg-lock-output .imgpkg/images.yml


kind: ImagesLock
- image:
  annotations: "my-app:v1"
- image:
  • images (array of images): 0+ images
    • image (string; required) digest reference to OCI image (tag references are not allowed)
    • annotations (map[string]string; optional) arbitrary additional data about image reference. Expected to be used by tools that create or read ImagesLock configuration. Example: kbld uses annotations to store an identifier that can later tell it which location(s) within a Kubernetes configuration to update with the digest reference.

Advanced non-bundle use: See copying via lock files.

BundleLock configuration

Stores a digest reference to a bundle (as well as the tag it was pushed with).

This configuration is generated by the --lock-output flag during a push command.

$ imgpkg push -b ... --lock-output /tmp/lock.yml

$ cat /tmp/lock.yml

kind: BundleLock
  tag: v1.0

Nested Bundle

A nested bundle is a bundle referenced from a ‘parent’ bundle in its ImagesLock configuration.

Having a bundle ‘reference’ another bundle is no different from referencing any other OCI image. The copy and pull commands work the same as dealing with any OCI image.

Nested Bundle diagram

One key difference between nested bundles and other OCI images, is the directory structure when imgpkg pull writes the nested bundle’s content to disk.

For further details refer to pulling a nested bundle.

Locations OCI Image

imgpkg when copying Bundles and Images now creates a new OCI Images that will act as a Cache that contain information about the Images that were copied and if these Images are a Bundle or not. This OCI Image will contain a single layer with a single file image-locations.yml at the root of the image. This is the file structure

kind: ImageLocations
- image:
  isBundle: true

The OCI Image will be pushed into the same repository as the Bundle and will have the tag sha256-{Bundle SHA}.image-locations.imgpkg