Automation Workflow

Scenario ¶

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

Prerequisites ¶

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 docker.io/dkalinin/k8s-simple-app. 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

   examples/basic-step-2
   ├── .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 index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4...) and a some additional metadata ( e.g. annotations section). See ImagesLock configuration for details.

   apiVersion: imgpkg.carvel.dev/v1alpha1
   kind: ImagesLock
   images:
   - image: index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0
     annotations:
       kbld.carvel.dev/id: docker.io/dkalinin/k8s-simple-app
   

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 index.docker.io/user1/simple-app-bundle:v1.0.0 -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 'index.docker.io/user1/simple-app-bundle@sha256:5c2dafe3c70c13990190d643c91e9f67b8129b179257674888178868474f6511'
   
   Succeeded
   

   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 production.registry.io/simple-app-bundle
   copy | exporting 2 images...
   copy | will export index.docker.io/dkalinin/k8s-simple-app@sha256:4c8b96d4fffdfae29258d94a22ae4ad1fe36139d47288b8960d9958d1e63a9d0
   copy | will export production.registry.io/simple-app-bundle@sha256:5c2dafe3c70c13990190d643c91e9f67b8129b179257674888178868474f6511
   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
   
   Succeeded
   

   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 'index.docker.io/user1/simple-app-bundle@sha256:ec3f870e958e404476b9ec67f28c598fa8f00f819b8ae05ee80d51bac9f35f5d'
     Extracting layer 'sha256:7906b9650be657359ead106e354f2728e16c8f317e1d87f72b05b5c5ec3d89cc' (1/1)
   
   Locating image lock file images...
   The bundle repo (index.docker.io/user1/simple-app-bundle@sha256:5c2dafe3c70c13990190d643c91e9f67b8129b179257674888178868474f6511) is hosting every image specified in the bundle's Images Lock file (.imgpkg/images.yml)
   
   Succeeded
   

   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:

   /tmp/simple-app-bundle
   ├── .imgpkg
   │   ├── bundle.yml
   │   └── images.yml
   └── config.yml