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.
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
.imgpkgdirectory is allowed across all directories provided via
pushcommand. This restriction ensures there is a single source of bundle metadata and referenced images.
.imgpkgdirectory must be a direct child of one of the input directories. This prevents any confusion around the scope of the
Bundle configuration ¶
Used by bundle creators to store general information about the bundle. Stored in
apiVersion: imgpkg.carvel.dev/v1alpha1 kind: Bundle metadata: name: my-bundle authors: - name: Full Name email: email@example.com websites: - url: example.com
authors(array of structs; optional)
name(string) Author name
websites(array of structs; optional)
url(string) Related website URL
ImagesLock configuration ¶
An ImagesLock configuration is used to track a collection of image references.
.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
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
$ 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
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
(Help improve our docs: edit this page on GitHub)