Carvel Logo

Automation Workflow


When using an automated CI tool you might want to promote a given Bundle between steps of the pipeline


To complete this workflow you will need access to an OCI registry like Docker Hub.

Step 1: Creating the Bundle

  1. Prepare bundle contents

    The examples/basic-step-1/ directory has a config.yml file, which contains a very simple Kubernetes application. Your application may have as many configuration files as necessary in various formats such as plain YAML, ytt templates, Helm templates, etc.

    In our example config.yml includes an image reference to This reference does not point to an exact image (via digest) meaning that it may change over time. To ensure we get precisely the bits we expect, we will lock it down to an exact image next.

  2. Add .imgpkg/ directory

    examples/basic-step-2 shows what a .imgpkg/ directory may look like. It contains:

    • optional bundle.yml: a file which records informational metadata
    • required images.yml: a file which records image references used by the configuration
    ├── .imgpkg
    │   ├── bundle.yml
    │   └── images.yml
    └── config.yml

    Note that .imgpkg/images.yml contains a list of images, each with fully resolved digest reference ( e.g and a some additional metadata ( e.g. annotations section). See ImagesLock configuration for details.

    kind: ImagesLock
    - image:

Step 2: Creating the Bundle

  1. Authenticate with a registry where we will push our bundle

  2. Push the bundle to the registry

    You can push the bundle with our specified contents to an OCI registry using the following command:

    $ imgpkg push -b -f examples/basic-step-2 --lock-output /tmp/bundle-lock.yml
    dir: .
    dir: .imgpkg
    file: .imgpkg/bundle.yml
    file: .imgpkg/images.yml
    file: config.yml
    Pushed ''

    Flags used in the command:

    • -b (--bundle) refers to a location for a bundle within an OCI registry
    • -f (--file) indicates directory contents to include
    • --lock-output indicates the destination of the BundleLock file

Step 3: Promoting the BundleLock file

Since in the previous step we generated a BundleLock we can promote this file and in the next steps of the pipeline we can reference it.

Examples of usage:

  1. Promote the Bundle to a different registry

    $ imgpkg copy --lock /tmp/bundle-lock.yml --to-repo
    copy | exporting 2 images...
    copy | will export
    copy | will export
    copy | exported 2 images
    copy | importing 2 images...
    3.56 MiB / 3.57 MiB [========================================================================================================================================================================]  99.68% 8.80 MiB/s 0s
    copy | done uploading images

    Flags used in the command:

    • --lock refers to a location for a BundleLock file
    • --to-repo indicates the destination Repository where the Bundle is copied to
  2. Download the Bundle contents to disk

    $ imgpkg pull --lock /tmp/bundle-lock.yml -o  /tmp/simple-app-bundle
    Pulling image ''
      Extracting layer 'sha256:7906b9650be657359ead106e354f2728e16c8f317e1d87f72b05b5c5ec3d89cc' (1/1)
    Locating image lock file images...
    The bundle repo ( is hosting every image specified in the bundle's Images Lock file (.imgpkg/images.yml)

    Flags used in the command:

    • --locke`) refers to a location for a BundleLock file
    • -o (--output) indicates the destination directory on your local machine where the bundle contents will be placed

    Bundle contents will be extracted into /tmp/simple-app-bundle directory:

    ├── .imgpkg
    │   ├── bundle.yml
    │   └── images.yml
    └── config.yml

(Help improve our docs: edit this page on GitHub)