This topic describes how to set up your environment so that you can deploy Tanzu Kubernetes Grid management clusters and Tanzu Kubernetes clusters in Internet-restricted environments, namely environments that are not connected to the Internet. The procedures described here only apply to deployments to vSphere.

If you are using Tanzu Kubernetes Grid to deploy clusters in a connected environment that can pull images over an external internet connection, you do not need to perform this procedure.


Before you can deploy management clusters and Tanzu Kubernetes clusters in an Internet-restricted environment, you must perform the following actions.

  • Within your firewall, install and configure a private Docker Registry. For example, install Harbor, which is the registry against which this procedure has been tested. For information about how to install Harbor, see Harbor Installation and Configuration.
  • Obtain a valid SSL certificate for the Docker Registry, signed by a trusted CA. For information about how to obtain the Harbor registry certificate, see the Harbor documentation.
  • Make sure that the internet-connected machine has Docker installed and running.
  • Make sure that you can connect to the private registry from the internet-connected machine.
  • Obtain a system with an external internet connection, and follow the instructions in Download and Install the Tanzu Kubernetes Grid CLI to download, unpack, and install the Tanzu Kubernetes Grid CLI binary on your internet-connected system.
  • Follow the instructions in Prepare to Deploy Management Clusters to vSphere to create SSH keys and to import into vSphere the OVAs from which node and loadbalancer VMs are created.

Tanzu Kubernetes Grid 1.1.2 and Later

The procedure to set up an internet-restricted environment so that you can deploy management clusters and Tanzu Kubernetes clusters has been simplified in Tanzu Kubernetes Grid 1.1.2 and subsequent releases.

This procedure also applies if you are upgrading an existing internet-restricted Tanzu Kubernetes Grid 1.1.2 or later deployment.

  1. On the machine with an internet connection on which you have performed the initial setup tasks and installed the Tanzu Kubernetes Grid CLI, install yq and jq.
  2. Run the tkg get management-cluster command.

    Running a tkg command for the first time installs the necessary Tanzu Kubernetes Grid configuration files in the ~/.tkg folder on your system. The script that you create and run in subsequent steps requires the YAML files in the ~/.tkg/bom folder to be present on your machine. The scripts in this procedure use the YAML files in ~/.tkg/bom to identify the correct versions of the different Tanzu Kubernetes Grid component images to pull.

  3. Set the IP address or FQDN of your local registry as an environment variable.

    In the following command example, replace with the address of your private Docker registry.

    On Windows platforms, use the SET command instead of export. Include the name of the project in the value:

  4. Copy and paste the following script in a text editor, and save it as

    #!/usr/bin/env bash
    # Copyright 2020 The TKG Contributors.
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    if [ -z "$TKG_CUSTOM_IMAGE_REPOSITORY" ]; then
        echo "TKG_CUSTOM_IMAGE_REPOSITORY variable is not defined"
        exit 1
    for TKG_BOM_FILE in "$BOM_DIR"/*.yaml; do
        # Get actual image repository from BoM file
        actualImageRepository=$(yq r "$TKG_BOM_FILE" imageConfig.imageRepository | tr -d '"')
        # Iterate through BoM file to create the complete Image name
        # and then pull, retag and push image to custom registry
        yq r --tojson "$TKG_BOM_FILE" images | jq -c '.[]' | while read -r i; do
            # Get imagePath and imageTag
            imagePath=$(jq .imagePath <<<"$i" | tr -d '"')
            imageTag=$(jq .tag <<<"$i" | tr -d '"')
            # create complete image names
            echo "docker pull $actualImage"
            echo "docker tag  $actualImage $customImage"
            echo "docker push $customImage"
            echo ""
  5. Make the script executable.

    chmod +x
  6. Generate a new version of the script that is populated with the address of your private Docker registry.

    ./ >
  7. Verify that the generated version of the script contains the correct registry address.

  8. Make the script executable.

    chmod +x
  9. Log in to your local private registry.
  10. Run the script to pull the required images from the public Tanzu Kubernetes Grid registry, retag them, and push them to your private registry.

  11. When the script finishes, turn off your internet connection.
  12. Run any Tanzu Kubernetes Grid CLI command, for example tkg init --ui.

    The Tanzu Kubernetes Grid installer interface should open.

Tanzu Kubernetes Grid 1.1.0

The procedure to set up an internet-restricted environment was manual in Tanzu Kubernetes Grid 1.1.0 and prone to error. For new deployments to internet-restricted environments, use Tanzu Kubernetes Grid 1.1.2 or a later release.

What to Do Next

As long as the TKG_CUSTOM_IMAGE_REPOSITORY variable remains set, when you deploy clusters, Tanzu Kubernetes Grid will pull images from your local private registry rather than from the external public registry. To make sure that Tanzu Kubernetes Grid always pulls images from the local private registry, add TKG_CUSTOM_IMAGE_REPOSITORY to the ~/.tkg/config.yaml file.


Your Internet-restricted environment is now ready for you to deploy or upgrade Tanzu Kubernetes Grid management clusters and Tanzu Kubernetes clusters to vSphere.

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