Copy Images into an Airgapped Environment

This topic explains how to copy the container images required to deploy Tanzu Kubernetes Grid on vSphere or AWS to a private registry in a physically-airgapped, offline environment. This procedure uses the scripts,, and to:

  • Copy the images from the Tanzu Kubernetes Grid public registry and save them locally in tar format.
  • Extract the images from tar files and copy them to a private registry.

Note: To deploy Tanzu Kubernetes Grid in an environment with limited Internet access, such as a proxied environment, see Prepare an Internet-Restricted Environment. The procedure below is equivalent to Step 2: Generate the images-copy-list File and Step 3: Run the download-images Script in that topic.


To copy the Tanzu Kubernetes Grid images into the airgapped registry, you need:

  • An Internet-connected Linux machine outside the airgapped environment, with the following installed:

  • A Linux machine inside the airgapped environment, with the following installed:

    • imgpkg
    • A private Docker-compatible container registry such as Harbor, Docker, or Artifactory as follows.
      • The registry must not implement user authentication. For example, if you use a Harbor registry, the project must be public, and not private.
      • This registry runs outside of Tanzu Kubernetes Grid and is separate from any registry deployed to shared service or workload clusters.
  • A USB thumb drive or other portable offline storage device.

Please follow Steps 1-4 on your internet-connected Linux machine.

Step 1: Set Environment Variables

On your internet-connected Linux machine:

  1. Set environment variables for:

    • The repository from which to fetch Bill of Materials (BoM) YAML files
    • The IP address or FQDN of your offline private registry
    • The Tanzu Kubernetes Grid version tag

    For example:

    export TKG_IMAGE_REPO=""
    export TKG_BOM_IMAGE_TAG="v1.6.0"

    Where PRIVATE-REGISTRY-IP and PRIVATE-REGISTRY-HOSTNAME are the IP address and name of your private Docker registry, for example,

  2. (Optional) Define the Tanzu Kubernetes releases (TKrs) to download. By default, the download script retrieves container images used in TKG versions v1.3.0 and later. To save download time, set an environment variable DOWNLOAD_TKRS to a space-separated string that lists only the TKr versions that you need for the management cluster and hosted workloads:

    1. List all TKrs and their associations with a TKG releases.
      imgpkg pull -i ${TKG_IMAGE_REPO}/tkr-compatibility:v$(imgpkg tag list -i ${TKG_IMAGE_REPO}/tkr-compatibility |sed 's/v//' |sort -rn |head -1) --output "tkr-tmp"; cat tkr-tmp/tkr-compatibility.yaml; rm -rf tkr-tmp;
    2. For your TKG version, note the supported Kubernetes versions. The one with the latest minor version is used by the management cluster. For example the TKG v1.6.0 management cluster uses TKr v1.23.8_vmware.1-tkg.1.
    3. Export as DOWNLOAD_TKRS a space-separated string of the TKrs required for your management cluster and workloads. For example, to download the images for Kubernetes v1.22 and v1.23 versions supported by TKG v1.6.0:
    export DOWNLOAD_TKRS="v1.23.8_vmware.2-tkg.1 v1.21.14_vmware.2-tkg.1 v1.22.11_vmware.2-tkg.1"

Step 2: Generate the images-to-tar-list File

  1. Download the script named

  2. Make the script executable.

    chmod +x
  3. Generate an images-to-tar-list file that lists images with the address of your private Docker registry.

    ./ > images-to-tar-list
  4. Verify that the generated script contains the correct registry address.

    cat images-to-tar-list

Step 3: Run the Script

  1. Create the script.

    set -euo pipefail
    if [ ! -f $images_script ]; then
      echo "You may add your images list filename as an argument."
      echo "E.g ./ image-copy-list"
    commands="$(cat ${images_script} |grep imgpkg |sort |uniq)"
    while IFS= read -r cmd; do
      echo -e "\nrunning $cmd\n"
      until $cmd; do
         echo -e "\nDownload failed. Retrying....\n"
         sleep 1
    done <<< "$commands"
  2. Make the script executable.

    chmod +x
  3. Run the script on the images-to-tar-list file to pull the required images from the public Tanzu Kubernetes Grid registry and save them as a tar file.

    ./ images-to-tar-list

Step 4: Generate the Script

  1. Download the script named

  2. Make the script executable.

    chmod +x
  3. Generate a shell script that is populated with the address of your private Docker registry.

    ./ >
  4. Verify that the generated script contains the correct registry address.


Step 5: Copy Files to Airgapped Environment

Use a USB thumb drive or other storage medium to copy the tar files and script to the Linux machine in the airgapped environment that hosts or can access your private registry.

Step 6: Run the Script

On your airgapped Linux machine:

  1. Make the script executable.

    chmod +x
  2. Run the script to extract the required images from the tar files and push them to your private registry.

check-circle-line exclamation-circle-line close-line
Scroll to top icon