This topic explains how to install and initialize the Tanzu command line interface (CLI) on a bootstrap machine. The bootstrap machine is the laptop, host, or server that you deploy management and workload clusters from, and that keeps the Tanzu and Kubernetes configuration files for your deployments. The bootstrap machine is typically local, but it can also be a physical machine or VM that you access remotely.

Once the Tanzu CLI is installed, the second and last step to deploying Tanzu Kubernetes Grid is using the Tanzu CLI to create or designate a management cluster on each cloud provider that you use.

Tanzu Kubernetes Grid installation process

The Tanzu CLI then communicates with the management cluster to create and manage workload clusters on the cloud provider.

Prerequisites

VMware provides Tanzu CLI binaries for Linux, macOS, and Windows systems.

Tanzu Kubernetes Grid installation prerequisites

The bootstrap machine on which you run the Tanzu CLI must meet the following requirements:

  • A browser, if you intend to use the Tanzu Kubernetes Grid installer interface. You can use the Tanzu CLI without a browser, but for first deployments, it is strongly recommended to use the installer interface.
  • A Linux, Windows, or macOS operating system with a minimum system configuration of 6 GB of RAM and a 2-core CPU.
  • A Docker client installed and running on your bootstrap machine:
  • For Windows and macOS Docker clients, you must allocate at least 6 GB of memory in Docker Desktop to accommodate the kind container. See Settings for Docker Desktop in the kind documentation.
  • System time is synchronized with a Network Time Protocol (NTP) server.
  • On VMware Cloud on AWS and Azure VMware Solution, the bootstrap machine must be a cloud VM, not a local physical machine. See Prepare a vSphere Management as a Service Infrastructure for setup instructions.
  • If your bootstrap machine runs Linux:

    • Add your non-root user account to the docker user group. Create the group if it does not already exist. This lets the Tanzu CLI access the Docker socket, which is owned by the root user. For more information, see the Docker documentation.
    • Ensure your bootstrap machine is using cgroups v1. You can check this by running the following command:

      docker info | grep -i cgroup
      

      You should see the following:

      Cgroup Driver: cgroupfs
      Cgroup Version: 1
      

    If your Linux distribution is configured to use cgroups v2, you will need to set system.unified_cgroup_hierarchy=0 kernel parameter to restore cgroups v1. See the instructions for setting kernel parameters for your Linux distribution, including:

  • If your bootstrap machine runs Linux or Windows Subsystem for Linux, and it has a Linux kernel built after the May 2021 Linux security patch, for example Linux 5.11 and 5.12 with Fedora, run the following:

    sudo sysctl net/netfilter/nf_conntrack_max=131072
    

    This lets kind, which the tanzu CLI uses to create the local bootstrap cluster, write to a control file that recent Linux versions made read-only by default.
    If you are troubleshooting as described in Use an Existing Bootstrap Cluster to Deploy and Delete Management Clusters, you must use kind v0.11 or later to create the pre-existing and persistent bootstrap cluster.

Download and Unpack the Tanzu CLI and kubectl

The tanzu CLI ships alongside a compatible version of the kubectl CLI.

Download the Tanzu Kubernetes Grid binaries

To download and unpack both CLIs:

  1. Go to https://my.vmware.com and log in with your My VMware credentials.

  2. Visit the Tanzu Kubernetes Grid downloads page

  3. In the VMware Tanzu Kubernetes Grid row, click Go to Downloads.

  4. In the Select Version drop-down, select 1.4.0.

  5. Under Product Downloads, scroll to the section labeled VMware Tanzu CLI 1.4.0 CLI.

    • For macOS, locate VMware Tanzu CLI for Mac and click Download Now.
    • For Linux, locate VMware Tanzu CLI for Linux and click Download Now.
    • For Windows, locate VMware Tanzu CLI for Windows and click Download Now.
  6. Navigate to the Kubectl 1.21.2 for VMware Tanzu Kubernetes Grid 1.4.0 section of the download page.

    • For macOS, locate kubectl cluster cli v1.21.2 for Mac and click Download Now.
    • For Linux, locate kubectl cluster cli v1.21.2 for Linux and click Download Now.
    • For Windows, locate kubectl cluster cli v1.21.2 for Windows and click Download Now.
  7. (Optional) Verify that your downloaded files are unaltered from the original. VMware provides a SHA-1, a SHA-256, and an MD5 checksum for each download. To obtain these checksums, click Read More under the entry that you want to download. For more information, see Using Cryptographic Hashes.

  8. On your system, create a new directory named tanzu. If you previously unpacked artifacts for previous releases to this folder, delete the folder's existing contents.

  9. In the tanzu folder, unpack the Tanzu CLI bundle file for your operating system. To unpack the bundle file, use the extraction tool of your choice. For example, the tar -xvf command.

    • For macOS, unpack tanzu-cli-bundle-v1.4.0-darwin-amd64.tar.
    • For Linux, unpack tanzu-cli-bundle-v1.4.0-linux-amd64.tar.
    • For Windows, unpack tanzu-cli-bundle-v1.4.0-windows-amd64.tar.

    After you unpack the bundle file, in your tanzu folder, you will see a cli folder with multiple subfolders and files.

  10. Unpack the kubectl binary for your operating system:

    • For macOS, unpack kubectl-mac-v1.21.2+vmware.1.gz.
    • For Linux, unpack kubectl-linux-v1.21.2+vmware.1.gz.
    • For Windows, unpack kubectl-windows-v1.21.2+vmware.1.exe.gz.

Install the Tanzu CLI

After you have downloaded and unpacked the Tanzu CLI on your bootstrap machine, you must make it available to the system.

Install the Tanzu Kubernetes Grid CLI and tools

  1. Navigate to the tanzu/cli folder that you unpacked in the previous section.

  2. Make the CLI available to the system:

    • For macOS:

      1. Install the binary to /usr/local/bin:

        sudo install core/v1.4.0/tanzu-core-darwin_amd64 /usr/local/bin/tanzu
        
      2. Confirm that the binary is executable by running the ls command.

    • For Linux:

      1. Install the binary to /usr/local/bin:

        sudo install core/v1.4.0/tanzu-core-linux_amd64 /usr/local/bin/tanzu
        
      2. Confirm that the binary is executable by running the ls command.

    • For Windows:

      1. Create a new Program Files\tanzu folder.
      2. In the unpacked cli folder, locate and copy the core\v1.4.0\tanzu-core-windows_amd64.exe into the new Program Files\tanzu folder.
      3. Rename tanzu-core-windows_amd64.exe to tanzu.exe.
      4. Right-click the tanzu folder, select Properties > Security, and make sure that your user account has the Full Control permission.
      5. Use Windows Search to search for env.
      6. Select Edit the system environment variables and click the Environment Variables button.
      7. Select the Path row under System variables, and click Edit.
      8. Click New to add a new row and enter the path to the tanzu CLI.
  3. At the command line in a new terminal, run tanzu version to check that the correct version of the CLI is properly installed.

    If you are running on macOS, you might encounter the following error:

    "tanzu" cannot be opened because the developer cannot be verified.
    

    If this happens, you need to create a security exception for the tanzu executable. Locate the tanzu app in Finder, control-click the app, and select Open.

Install the Tanzu CLI Plugins

After you have installed the tanzu core executable, you must install the CLI plugins related to Tanzu Kubernetes cluster management and feature operations.

  1. (Optional) Remove existing plugins from any previous CLI installations.

    tanzu plugin clean
    
  2. Navigate to the tanzu folder that contains the cli folder.

  3. Run the following command from the tanzu directory to install all the plugins for this release.

    tanzu plugin install --local cli all
    
  4. Check plugin installation status.

    tanzu plugin list
    

    If successful, you should see a list of all installed plugins. For example:

    NAME                LATEST VERSION  DESCRIPTION                                                        REPOSITORY  VERSION  STATUS
    cluster             v1.4.0          Kubernetes cluster operations                                      core        v1.4.0   installed
    login               v1.4.0          Login to the platform                                              core        v1.4.0   installed
    pinniped-auth       v1.4.0          Pinniped authentication operations (usually not directly invoked)  core        v1.4.0   installed
    kubernetes-release  v1.4.0          Kubernetes release operations                                      core        v1.4.0   installed
    management-cluster  v1.4.0          Kubernetes management cluster operations                           core        v1.4.0   installed
    

Tanzu CLI Help

Run tanzu --help to see the list of commands that the Tanzu CLI provides.

You can view help text for any command group with the --help option to see information about that specific command or command group. For example, tanzu login --help, tanzu management-cluster --help, or tanzu management-cluster create --help.

For more information about the Tanzu CLI, see the Tanzu CLI Command Reference.

Install kubectl

After you have downloaded and unpacked kubectl on your bootstrap machine, you must make it available to the system.

  1. Navigate to the kubectl binary that you unpacked in Download and Unpack the Tanzu CLI and kubectl above.

  2. Make the CLI available to the system:

    • For macOS:

      1. Install the binary to /usr/local/bin:

        sudo install kubectl-mac-v1.21.2+vmware.1 /usr/local/bin/kubectl
        
      2. Confirm that the binary is executable by running the ls command.

    • For Linux:

      1. Install the binary to /usr/local/bin:

        sudo install kubectl-linux-v1.21.2+vmware.1 /usr/local/bin/kubectl
        
      2. Confirm that the binary is executable by running the ls command.

    • For Windows:

      1. Create a new Program Files\kubectl folder.
      2. Locate and copy the kubectl-windows-v1.21.2+vmware.1.exe file into the new Program Files\kubectl folder.
      3. Rename kubectl-windows-v1.21.2+vmware.1.exe to kubectl.exe.
      4. Right-click the kubectl folder, select Properties > Security, and make sure that your user account has the Full Control permission.
      5. Use Windows Search to search for env.
      6. Select Edit the system environment variables and click the Environment Variables button.
      7. Select the Path row under System variables and click Edit.
      8. Click New to add a new row and enter the path to the kubectl CLI.
  3. Run kubectl version to check that the correct version of the CLI is properly installed.

What to Do Next

With the Tanzu CLI and kubectl installed, you can set up and use your bootstrap machine to deploy management clusters clusters to vSphere, Amazon EC2, and Microsoft Azure.

Tanzu Kubernetes Grid CLI installation complete

  • For information about how to deploy management clusters to your chosen platform, see Deploy Management Clusters.
  • If you have vSphere 7 and the vSphere with Tanzu feature is enabled, you can directly use the Tanzu CLI to deploy Tanzu Kubernetes clusters to vSphere with Tanzu, without deploying a management cluster. For information about how to connect the Tanzu CLI to a vSphere with Tanzu Supervisor Cluster, see Add a vSphere7 Supervisor Cluster as a Management Cluster.

The Tanzu Kubernetes Grid download bundle also includes the Carvel tools, that you might need for troubleshooting or customization purposes.

Install the Carvel Tools

Carvel provides a set of reliable, single-purpose, composable tools that aid in application building, configuration, and deployment to Kubernetes.

Tanzu Kubernetes Grid uses the following tools from the Carvel open-source project:

  • ytt - a command-line tool for templating and patching YAML files. You can also use ytt to collect fragments and piles of YAML into modular chunks for easy re-use.
  • kapp - the applications deployment CLI for Kubernetes. It allows you to install, upgrade, and delete multiple Kubernetes resources as one application.
  • kbld - an image-building and resolution tool.
  • imgpkg - a tool that enables Kubernetes to store configurations and the associated container images as OCI images, and to transfer these images.

Tanzu Kubernetes Grid provides signed binaries for ytt, kapp, kbld, imgpkg, and vendir that are bundled with the Tanzu CLI. The bundle also includes vendir, a Kubernetes directory structure tool, that is not currently required by end users, but is provided for convenience.

  1. Navigate to the location on your bootstrap environment machine where you unpacked the Tanzu CLI bundle tar file for your OS.

    For example, the tanzu folder, that you created in the previous procedure.

  2. Open the cli folder.

    cd cli
    

Install ytt

Tanzu Kubernetes Grid uses ytt to support overlay-based customization for clusters and cluster plans. You might need ytt to use customization overlays.

MacOS and Linux:

  1. Unpack the ytt binary and make it executable.

    Linux:

    gunzip ytt-linux-amd64-v0.34.0+vmware.1.gz
    chmod ugo+x ytt-linux-amd64-v0.34.0+vmware.1
    

    Mac OS:

    gunzip ytt-darwin-amd64-v0.34.0+vmware.1.gz
    chmod ugo+x ytt-darwin-amd64-v0.34.0+vmware.1
    
  2. Move the binary to /usr/local/bin and rename it to ytt:

    Linux:

    mv ./ytt-linux-amd64-v0.34.0+vmware.1 /usr/local/bin/ytt
    

    Mac OS:

    mv ./ytt-darwin-amd64-v0.34.0+vmware.1 /usr/local/bin/ytt
    
  3. Confirm that the binary is executable by running the ls command.

Windows:

  1. Unpack the the ytt binary.

    gunzip ytt-windows-amd64-v0.34.0+vmware.1.gz
    
  2. Rename ytt-windows-amd64-v0.34.0+vmware.1 to ytt.exe

  3. Create a new Program Files\ytt folder and copy the ytt.exe file into it.
  4. Right-click the ytt folder, select Properties > Security, and make sure that your user account has the Full Control permission.
  5. Use Windows Search to search for env.
  6. Select Edit the system environment variables and click the Environment Variables button.
  7. Select the Path row under System variables, and click Edit.
  8. Click New to add a new row and enter the path to the ytt tool.

At the command line in a new terminal, run ytt version to check that the correct version of ytt is properly installed.

Install kapp

To install kapp:

MacOS and Linux:

  1. Unpack the kapp binary and make it executable.

    Linux:

    gunzip kapp-linux-amd64-v0.37.0+vmware.1.gz
    chmod ugo+x kapp-linux-amd64-v0.37.0+vmware.1
    

    Mac OS:

    gunzip kapp-darwin-amd64-v0.37.0+vmware.1.gz
    chmod ugo+x kapp-darwin-amd64-v0.37.0+vmware.1
    
  2. Move the binary to /usr/local/bin and rename it to kapp:

    Linux:

    mv ./kapp-linux-amd64-v0.37.0+vmware.1 /usr/local/bin/kapp
    

    Mac OS:

    mv ./kapp-darwin-amd64-v0.37.0+vmware.1 /usr/local/bin/kapp
    
  3. Confirm that the binary is executable by running the ls command.

Windows:

  1. Unpack the the kapp binary.

    gunzip kapp-windows-amd64-v0.37.0+vmware.1.gz
    
  2. Rename kapp-windows-amd64-v0.37.0+vmware.1 to kapp.exe

  3. Create a new Program Files\kapp folder and copy the kapp.exe file into it.
  4. Right-click the kapp folder, select Properties > Security, and make sure that your user account has the Full Control permission.
  5. Use Windows Search to search for env.
  6. Select Edit the system environment variables and click the Environment Variables button.
  7. Select the Path row under System variables, and click Edit.
  8. Click New to add a new row and enter the path to the kapp tool.

At the command line in a new terminal, run kapp version to check that the correct version of kapp is properly installed.

Install kbld

To install kbld:

MacOS and Linux:

  1. Unpack the kbld binary and make it executable.

    Linux:

    gunzip kbld-linux-amd64-v0.30.0+vmware.1.gz
    chmod ugo+x kbld-linux-amd64-v0.30.0+vmware.1
    

    Mac OS:

    gunzip kbld-darwin-amd64-v0.30.0+vmware.1.gz
    chmod ugo+x kbld-darwin-amd64-v0.30.0+vmware.1
    
  2. Move the binary to /usr/local/bin and rename it to kbld:

    Linux:

    mv ./kbld-linux-amd64-v0.30.0+vmware.1 /usr/local/bin/kbld
    

    Mac OS:

    mv ./kbld-darwin-amd64-v0.30.0+vmware.1 /usr/local/bin/kbld
    
  3. Confirm that the binary is executable by running the ls command.

Windows:

  1. Unpack the the kbld binary.

    gunzip kbld-windows-amd64-v0.30.0+vmware.1.gz
    
  2. Rename kbld-windows-amd64-v0.30.0+vmware.1 to kbld.exe

  3. Create a new Program Files\kbld folder and copy the kbld.exe file into it.
  4. Right-click the kbld folder, select Properties > Security, and make sure that your user account has the Full Control permission.
  5. Use Windows Search to search for env.
  6. Select Edit the system environment variables and click the Environment Variables button.
  7. Select the Path row under System variables, and click Edit.
  8. Click New to add a new row and enter the path to the kbld tool.

At the command line in a new terminal, run kbld version to check that the correct version of kbld is properly installed.

Install imgpkg

imgpkg is required for deploying Tanzu Kubernetes Grid in Internet-restricted environments and when building your own machine images. It is also required when configuring the Harbor package.

MacOS and Linux:

  1. Unpack the imgpkg binary and make it executable.

    Linux:

    gunzip imgpkg-linux-amd64-v0.10.0+vmware.1.gz
    chmod ugo+x imgpkg-linux-amd64-v0.10.0+vmware.1
    

    Mac OS:

    gunzip imgpkg-darwin-amd64-v0.10.0+vmware.1.gz
    chmod ugo+x imgpkg-darwin-amd64-v0.10.0+vmware.1
    
  2. Move the binary to /usr/local/bin and rename it to imgpkg:

    Linux:

    mv ./imgpkg-linux-amd64-v0.10.0+vmware.1 /usr/local/bin/imgpkg
    

    Mac OS:

    mv ./imgpkg-darwin-amd64-v0.10.0+vmware.1 /usr/local/bin/imgpkg
    
  3. Confirm that the binary is executable by running the ls command.

Windows:

  1. Unpack the the imgpkg binary.

    gunzip imgpkg-windows-amd64-v0.10.0+vmware.1.gz
    
  2. Rename imgpkg-windows-amd64-v0.10.0+vmware.1 to imgpkg.exe

  3. Create a new Program Files\imgpkg folder and copy the imgpkg.exe file into it.
  4. Right-click the imgpkg folder, select Properties > Security, and make sure that your user account has the Full Control permission.
  5. Use Windows Search to search for env.
  6. Select Edit the system environment variables and click the Environment Variables button.
  7. Select the Path row under System variables, and click Edit.
  8. Click New to add a new row and enter the path to the imgpkg tool.

At the command line in a new terminal, run imgpkg version to check that the correct version of imgpkg is properly installed.

Renew CLI Certificate

On the bootstrap machine, the CLI uses a certificate that is stored locally to authenticate with the management cluster. If the certificate expires, you will see failed error messages when running tkg or tanzu CLI commands.

Therefore, when the certificate nears expiration, follow these steps to renew the certificate. The following steps use tanzu CLI commands.

  1. Get the name of the management cluster.

    tanzu management-cluster get

  2. Get the cluster configuration data. You will copy the data to populate the ~/.kube-tkg/config file.

    kubectl -n tkg-system get secrets <cluster name>-kubeconfig -o 'go-template={{ index .data "value"}}' | base64 -d > mc_kubeconfig.yaml

    Where, <cluster name> is the name of the management cluster.

    apiVersion: v1
    clusters:
    - cluster:
    	certificate-authority-data: LS0tLS1CRUdJTiBD<redacted>
    	server: https://192.168.100.90:6443
      name: tkg-mgmt
    contexts:
    - context:
    	cluster: tkg-mgmt
    	user: tkg-mgmt-admin
      name: tkg-mgmt-admin@tkg-mgmt
    current-context: tkg-mgmt-admin@tkg-mgmt
    kind: Config
    preferences: {}
    users:
    - name: tkg-mgmt-admin
      user:
    	client-certificate-data: LS0tLS1CRUdJTiBDRVJUSUZ<redacted>
    	client-key-data: LS0tLS1CRUdJTiBSU<redacted>`	
    
  3. Delete the existing management cluster entry from Tanzu managed servers.

    tanzu config server delete <cluster-name>

  4. Use tanzu login command to add the management-cluster entry with the new updated kubeconfig.

    tanzu login --kubeconfig mc_kubeconfig.yaml --name <cluster-name> --context <cluster-name>-admin@<cluster-name>

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