Resources

Image ¶

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

Bundle ¶

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.

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.

Example:

apiVersion: imgpkg.carvel.dev/v1alpha1
kind: Bundle
metadata:
  name: my-bundle
authors:
- name: Full Name
  email: name@example.com
websites:
- url: example.com

• 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

Example:

apiVersion: imgpkg.carvel.dev/v1alpha1
kind: ImagesLock
images:
- image: docker.io/user1/my-app@sha256:42462d0cb227497976754bb67348bdd7471c7bd159819d6bd63fdf479eb7eb19
  annotations:
    kbld.carvel.dev/id: "my-app:v1"
- image: gcr.io/projectX/controller@sha256:6ecba6f14373a449f8d54fa4286f57fb8ef37c4ffa637969551f2fda52672206

• 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

apiVersion: imgpkg.carvel.dev/v1alpha1
kind: BundleLock
bundle:
  image: docker.io/my-app@sha256:b12026c7a0a6a1756a82a2a74ac759e9a7036523faca0e33dbddebc214e097df
  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.

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.

Bundles can be nested repeatedly without limits on depth or breadth. Imgpkg optimizes both network requests and storage on the destination, so we would not expect any issues short of hard storage limits at the destination repository.

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

apiVersion: imgpkg.carvel.dev/v1alpha1
kind: ImageLocations
images:
- image: some.image.io/test@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0
  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