RSS
 

Install the Tanzu CLI and Other Tools for Use with Standalone Management Clusters

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 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.

If you intend to use Tanzu Kubernetes Grid on vSphere without a Supervisor, or on AWS or Azure, you use the Tanzu CLI to create a standalone management cluster on each cloud provider that you use. The Tanzu CLI communicates with this management cluster to create and manage workload clusters on your target cloud infrastructure.

Note

The instructions in this topic are specific to installing the Tanzu CLI in order to deploy standalone management clusters on vSphere without a Supervisor, or on AWS or Azure. If you are installing the Tanzu CLI for use with a vSphere with Tanzu Supervisor on vSphere 8, see the corresponding topic in Creating and Managing TKG 2.2 Workload Clusters with the Tanzu CLI, Install the Tanzu CLI and Other Tools for Use with a vSphere with Tanzu Supervisor.

For more information about the Tanzu CLI, including a command reference, see the VMware Tanzu CLI documentation.

Prerequisites

The bootstrap machine on which you install and run the Tanzu CLI must meet certain requirements. There are further requirements depending on whether you intend to use the Tanzu CLI with a vSphere with Tanzu Supervisor as the management cluster, or deploy standalone management clusters, or both.

To run the Tanzu CLI with Tanzu Kubernetes Grid v2.2, you need a bootstrap machine on which to install and run the Tanzu CLI that has:

  • A Linux, Windows, or macOS operating system running on a physical or virtual machine that has the following hardware:
    • At least 8 GB of RAM. VMware recommends 16 GB of RAM.
    • A disk with 50GB of available storage.
    • 2 or 4 2-core CPUs.
  • A browser or remote access from a machine with a browser, if you intend to use the Tanzu Kubernetes Grid installer interface to deploy standalone management clusters. You can use the Tanzu CLI without a browser, but for first deployments, it is strongly recommended to use the installer interface.
  • System time is synchronized with a Network Time Protocol (NTP) server.

  • If your bootstrap machine runs Windows, VMware recommends installing Windows Subsystem for Linux (WSL) with Ubuntu 20.04.4 LTS, which enables you to run Linux commands on Windows. For more information about WSL, see Install WSL in the Microsoft documentation.

  • On VMware Cloud on AWS and Azure VMware Solution, the bootstrap machine must be a cloud VM, not a local physical machine. See Prepare to Deploy Management Clusters to a VMware Cloud Environment for setup instructions.

  • To deploy standalone management clusters, there are additional requirements depending on which operating system the bootstrap machine is running:

    macOS
    • Docker Desktop installed and running on your bootstrap machine.
    • Allocate at least 6 GB of memory in Docker Desktop to accommodate the kind container. See Settings for Docker Desktop in the kind documentation.
    Linux
    • Docker installed and running on your bootstrap machine. Use apt instead of snap to install Docker from a CLI. For instructions on installing the Docker client app in an internet-restricted environment, see Prepare an Internet-Restricted Environment.
    • 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 Manage Docker as a non-root user in the Docker documentation.

    • If your bootstrap machine runs Ubuntu 22.04, ensure that reverse path filtering is deactivated. To deactivate reverse path filtering, add the following override:

      # New file /etc/sysctl.d/90-override.conf
ipv4.conf.all.rp_filter = 0

    • If your bootstrap machine has a Linux kernel built after the May 2021 Linux security patch, you must enable kind, which the Tanzu CLI uses to create the local bootstrap cluster, to write to a control file that recent Linux versions made read-only by default.

      How you change this file permission depends on your Linux distribution. For example, with a Fedora distribution of Linux 5.11 and 5.12, run:

      sudo sysctl net/netfilter/nf_conntrack_max=131072

      With a Debian distribution, add nf_conntrack_max=131072 to the sysctl.conf file and run:

      sudo modprobe nf_conntrack

      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.

    Windows
    • Docker Desktop installed and running on your bootstrap machine.
    • Allocate at least 6 GB of memory in Docker Desktop to accommodate the kind container. See Settings for Docker Desktop in the kind documentation.

    • If your bootstrap machine runs 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

Download the files for the compatible version of the Tanzu CLI from the Tanzu Kubernetes Grid downloads page.

  1. Go to VMware Customer Connect and log in with your VMware Customer Connect 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 2.2.0.

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

    macOS
    Locate VMware Tanzu CLI for Mac and click Download Now.
    Linux
    Locate VMware Tanzu CLI for Linux and click Download Now.
    Windows
    Locate VMware Tanzu CLI for Windows and click Download Now.

  6. (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.

  7. 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.

  8. 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, on Linux or macOS, you can use the tar command.

    macOS 
    tar -xvf tanzu-cli-bundle-darwin-amd64.tar.gz
    Linux 
    tar -xvf tanzu-cli-bundle-linux-amd64.tar.gz
    Windows
    Use the Windows extractor tool to unzip tanzu-cli-bundle-windows-amd64.zip.

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

Initialize the Tanzu CLI

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

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

    cd cli

  2. Make the CLI available to the system:

    macOS
    Install the binary to /usr/local/bin: 
    sudo install core/v0.29.0/tanzu-core-darwin_amd64 /usr/local/bin/tanzu
    Linux
    Install the binary to /usr/local/bin: 
    sudo install core/v0.29.0/tanzu-core-linux_amd64 /usr/local/bin/tanzu
    Windows
    1. Create a new Program Files\tanzu folder.
    2. In the unpacked cli folder, locate and copy the core\v0.29.0\tanzu-core-windows_amd64.exe file 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, initialize the Tanzu CLI:

    tanzu init

  4. Check that the correct version of the CLI is properly installed. The CLI version is the same as the current version of Tanzu Framework, which is included in the Tanzu CLI. Tanzu Kubernetes Grid 2.2 uses Tanzu CLI v0.29.0, which is in Tanzu Framework v0.29.0:

    tanzu version

    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.

  5. If you have existing Tanzu CLI plugins installed on your machine from a previous CLI installation, update the plugins to the current CLI version:

    1. Uninstall the existing plugins:

      tanzu plugin clean

    2. Install all the plugins for this release:

      tanzu plugin sync

    3. Check plugin installation status and version:

      tanzu plugin list
Note

After you have installed the Tanzu CLI but before you have used it to log in to a management cluster, all context-specific CLI command groups, such as tanzu cluster and tanzu kubernetes-release, are unavailable and not included in Tanzu CLI --help output.

Install the Kubernetes CLI

Download and unpack the Kubernetes CLI, kubectl, on your bootstrap machine, then make it available to your system.

  1. Go to VMware Customer Connect and log in with your VMware Customer Connect 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 2.2.0.

  5. Under Product Downloads, scroll to the section labeled Kubectl 1.25.7 for VMware Tanzu Kubernetes Grid 2.2.0.

    macOS
    Locate kubectl cli v1.25.7 for Mac and click Download Now.
    Linux
    Locate kubectl cli v1.25.7 for Linux and click Download Now.
    Windows
    Locate kubectl cli v1.25.7 for Windows and click Download Now.

  6. (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.

  7. Navigate to the tanzu directory you created in Download and Unpack the Tanzu CLI above and unpack the kubectl binary for your operating system. To unpack the bundle file, use the extraction tool of your choice. For example, the gunzip command.

    macOS 
    gunzip kubectl-mac-v1.25.7+vmware.2.gz
    Linux 
    gunzip kubectl-linux-v1.25.7+vmware.2.gz
    Windows
    Use the Windows extractor tool to unzip kubectl-windows-v1.25.7+vmware.2.exe.gz.

  8. Make the CLI available to the system:

    macOS

    1. Make the downloaded file executable:

      chmod ugo+x kubectl-mac-v1.25.7+vmware.2

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

      sudo install kubectl-mac-v1.25.7+vmware.2 /usr/local/bin/kubectl

    3. Run kubectl version to check that the correct version of kubectl is installed and executable.

      kubectl version
    Linux

    1. Make the downloaded file executable:

      chmod ugo+x kubectl-linux-v1.25.7+vmware.2

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

      sudo install kubectl-linux-v1.25.7+vmware.2 /usr/local/bin/kubectl

    3. Run kubectl version to check that the correct version of kubectl is installed and executable.

      kubectl version
    Windows
    1. Create a new Program Files\kubectl folder.
    2. Locate and copy the kubectl-windows-v1.25.7+vmware.2.exe file into the new Program Files\kubectl folder.
    3. Rename kubectl-windows-v1.25.7+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.

  9. Run kubectl version to check that the correct version of the CLI is properly 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 the Carvel Tools

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

Tanzu Kubernetes Grid provides signed binaries for ytt, kapp, kbld, and imgpkg, 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.

Locate the Carvel Tools

  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

ytt is 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. Tanzu Kubernetes Grid uses ytt to support overlay-based customization for clusters and cluster plans. You might need ytt to use customization overlays.

macOS

  1. Unpack the ytt binary and make it executable.

    gunzip ytt-darwin-amd64-v0.43.1+vmware.1.gz

    chmod ugo+x ytt-darwin-amd64-v0.43.1+vmware.1

  2. Move the binary to /usr/local/bin and rename it to ytt:

    sudo mv ./ytt-darwin-amd64-v0.43.1+vmware.1 /usr/local/bin/ytt

  3. Run ytt --version to check that the correct version of ytt is installed and executable.

    ytt --version
Linux

  1. Unpack the ytt binary and make it executable.

    gunzip ytt-linux-amd64-v0.43.1+vmware.1.gz

    chmod ugo+x ytt-linux-amd64-v0.43.1+vmware.1

  2. Move the binary to /usr/local/bin and rename it to ytt:

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

  3. Run ytt --version to check that the correct version of ytt is installed and executable.

    ytt --version
Windows

  1. Unpack the the ytt binary.

    gunzip ytt-windows-amd64-v0.43.1+vmware.1.gz

  2. Rename ytt-windows-amd64-v0.43.1+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.
  9. At the command line in a new terminal, run ytt version to check that the correct version of ytt is properly installed.


Install kapp

kapp is the applications deployment CLI for Kubernetes. It allows you to install, upgrade, and delete multiple Kubernetes resources as one application.

macOS

  1. Unpack the kapp binary and make it executable.

    gunzip kapp-darwin-amd64-v0.53.2+vmware.1.gz

    chmod ugo+x kapp-darwin-amd64-v0.53.2+vmware.1

  2. Move the binary to /usr/local/bin and rename it to kapp:

    sudo mv ./kapp-darwin-amd64-v0.53.2+vmware.1 /usr/local/bin/kapp

  3. Run kapp --version to check that the correct version of kapp is installed and executable.

    kapp --version
Linux

  1. Unpack the kapp binary and make it executable.

    gunzip kapp-linux-amd64-v0.53.2+vmware.1.gz

    chmod ugo+x kapp-linux-amd64-v0.53.2+vmware.1

  2. Move the binary to /usr/local/bin and rename it to kapp:

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

  3. Run kapp --version to check that the correct version of kapp is installed and executable.

    kapp --version
Windows

  1. Unpack the the kapp binary.

    gunzip kapp-windows-amd64-v0.53.2+vmware.1.gz

  2. Rename kapp-windows-amd64-v0.53.2+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.
  9. At the command line in a new terminal, run kapp version to check that the correct version of kapp is properly installed.


Install kbld

kbld is an image-building and resolution tool.

macOS

  1. Unpack the kbld binary and make it executable.

    gunzip kbld-darwin-amd64-v0.35.1+vmware.1.gz

    chmod ugo+x kbld-darwin-amd64-v0.35.1+vmware.1

  2. Move the binary to /usr/local/bin and rename it to kbld:

    sudo mv ./kbld-darwin-amd64-v0.35.1+vmware.1 /usr/local/bin/kbld

  3. Run kbld --version to check that the correct version of kbld is installed and executable.

Linux

  1. Unpack the kbld binary and make it executable.

    gunzip kbld-linux-amd64-v0.35.1+vmware.1.gz

    chmod ugo+x kbld-linux-amd64-v0.35.1+vmware.1

  2. Move the binary to /usr/local/bin and rename it to kbld:

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

  3. Run kbld --version to check that the correct version of kbld is installed and executable.

    kbld --version
Windows

  1. Unpack the the kbld binary.

    gunzip kbld-windows-amd64-v0.35.1+vmware.1.gz

  2. Rename kbld-windows-amd64-v0.35.1+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.
  9. 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 a tool that enables Kubernetes to store configurations and the associated container images as OCI images, and to transfer these images. 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

  1. Unpack the imgpkg binary and make it executable.

    gunzip imgpkg-darwin-amd64-v0.31.1+vmware.1.gz

    chmod ugo+x imgpkg-darwin-amd64-v0.31.1+vmware.1

  2. Move the binary to /usr/local/bin and rename it to imgpkg:

    sudo mv ./imgpkg-darwin-amd64-v0.31.1+vmware.1 /usr/local/bin/imgpkg

  3. Run imgpkg --version to check that the correct version of imgpkg is installed and executable.

    imgpkg --version
Linux

  1. Unpack the imgpkg binary and make it executable.

    gunzip imgpkg-linux-amd64-v0.31.1+vmware.1.gz

    chmod ugo+x imgpkg-linux-amd64-v0.31.1+vmware.1

  2. Move the binary to /usr/local/bin and rename it to imgpkg:

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

  3. Run imgpkg --version to check that the correct version of imgpkg is installed and executable.

    imgpkg --version
Windows

  1. Unpack the the imgpkg binary.

    gunzip imgpkg-windows-amd64-v0.31.1+vmware.1.gz

  2. Rename imgpkg-windows-amd64-v0.31.1+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.
  9. At the command line in a new terminal, run imgpkg version to check that the correct version of imgpkg is properly installed.


What to Do Next

To deploy standalone management clusters to your cloud provider, follow the instructions in Deploying Standalone Management Clusters.

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