Install the Tanzu CLI and Kubernetes CLI for Use with Standalone Management Clusters

This topic explains how to install 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. For more information about the Tanzu CLI, including a command reference, see the VMware Tanzu CLI v1.3.x documentation.

To deploy Tanzu Kubernetes Grid, you use the Tanzu CLI to create a standalone management cluster. 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. If you are using the Supervisor and want to use the Tanzu CLI to create workload clusters, see Workflow for Provisioning TKG Clusters Using the Tanzu CLI in the vSphere IaaS control plane docs.

Prerequisites

The bootstrap machine on which you install and run the Tanzu CLI for use with Tanzu Kubernetes Grid must meet certain requirements.

To run the Tanzu CLI with Tanzu Kubernetes Grid v2.5, 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 50 GB 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 22.04.03 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

  Requirements

  • Docker Desktop or Docker Engine installed and running on your bootstrap machine. Use apt instead of snap to install Docker from a package manager. 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.
    • To address a known issue, change your Docker cgroup driver default to systemd if it is currently set to cgroupfs:
      1. Create a config file /etc/docker/daemon.json that sets the Docker Docker cgroup driver to systemd:

         {
             "exec-opts": ["native.cgroupdriver=systemd"]
         }
         

      2. Load the configuration:

         sudo systemctl daemon-reload
         

      3. Restart Docker:

         sudo systemctl restart docker
         

  • 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
    

  • Linux kernel must be v4.6 or above, to support cgroup namespaces.

  • 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

  Requirements

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

Install the Tanzu CLI

To install the Tanzu CLI for use with Tanzu Kubernetes Grid v2.5.2, you install a compatible version of the Tanzu Core CLI and the Tanzu CLI plugins for Tanzu Kubernetes Grid v2.5.2. Commands provided by these plugins enable cluster and package operations. For a list of compatible CLI versions, see Product Interoperability Matrix.

Install the Tanzu Core CLI

To install Tanzu Core CLI, follow the steps below; to see the steps, click the Install using a package manager or Install from a binary release tab.

After you install the Tanzu Core CLI, proceed to Install the Tanzu CLI Plugins for TKG v2.5.

Note

If you want to retain an existing installation of the Tanzu CLI, move the CLI binary from /usr/local/bin/tanzu to a different location before following the steps below.

Install using a package manager

To install the Tanzu CLI using a package manager:

1. Choose a compatible version of the Tanzu CLI. For a list of CLI versions that are compatible with this release of Tanzu Kubernetes Grid, see Product Interoperability Matrix.

2. Follow the instructions for your package manager below.

   • APT (Debian or Ubuntu):

     • To install a version of the Tanzu CLI that is compatible with TKG v2.5.2, for example, v1.3.0, run:

       sudo apt update
       sudo apt install -y ca-certificates curl gpg
       sudo mkdir -p /etc/apt/keyrings
       curl -fsSL https://packages-prod.broadcom.com/tools/keys/VMWARE-PACKAGING-GPG-RSA-KEY.pub | sudo gpg --dearmor -o /etc/apt/keyrings/tanzu-archive-keyring.gpg
       echo "deb [signed-by=/etc/apt/keyrings/tanzu-archive-keyring.gpg] https://storage.googleapis.com/tanzu-cli-os-packages/apt tanzu-cli-jessie main" | sudo tee /etc/apt/sources.list.d/tanzu.list
       sudo apt update
       sudo apt install tanzu-cli=1.3.0
       

   • Chocolatey (Windows):

     • To install a version of the Tanzu CLI that is compatible with TKG v2.5.2, for example, v1.3.0, run:

       choco install tanzu-cli --version 1.3.0
       

   • Homebrew (MacOS):

     • To install a version of the Tanzu CLI that is compatible with TKG v2.5.2, for example, v1.3.0, run:

       brew update
       brew tap-new local/tap
       brew extract --version=1.3.0 vmware-tanzu/tanzu/tanzu-cli local/tap
       brew install [email protected]
       

   • YUM or DNF (RHEL):

     • To install a version of the Tanzu CLI that is compatible with TKG v2.5.2, for example, v1.3.0, run:

       cat << EOF | sudo tee /etc/yum.repos.d/tanzu-cli.repo
       [tanzu-cli]
       name=Tanzu CLI
       baseurl=https://storage.googleapis.com/tanzu-cli-os-packages/rpm/tanzu-cli
       enabled=1
       gpgcheck=1
       repo_gpgcheck=1
       gpgkey=https://packages-prod.broadcom.com/tools/keys/VMWARE-PACKAGING-GPG-RSA-KEY.pub
       EOF
       
       sudo yum install tanzu-cli-1.3.0 # If you are using DNF, run sudo dnf install tanzu-cli-1.3.0.
       

3. Check that the correct version of the CLI is properly installed. For example:

   tanzu version
   version: v1.3.0
   ...
   

Install from a binary release

You can download the Tanzu CLI binary from the Broadcom Support Portal or GitHub. For a list of all compatible CLI versions, see Product Interoperability Matrix.

To download a binary release of the Tanzu CLI from the Broadcom Support Portal and then install it:

1. Download and unpack the Tanzu CLI binary:

   1. Go to the Broadcom Support Portal and log in with your VMware customer credentials.
   2. Go to the Tanzu CLI download page, expand Product Downloads, select 1.3.0, and download the Tanzu CLI binary for your operating system (OS).

   3. Unpack the Tanzu CLI file for your OS. To unpack the 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-darwin-amd64.tar.gz
        

      • Linux:

        tar -xvf tanzu-cli-linux-amd64.tar.gz
        

      • Windows:

        Use the Windows extractor tool to unzip tanzu-cli-windows-amd64.zip.

2. cd into the unpacked directory, which contains the CLI executable.

3. Make the CLI available to the system:

   • macOS:

     Install the binary to /usr/local/bin:

     install tanzu-cli-darwin_amd64 /usr/local/bin/tanzu
     

   • Linux:

     Install the binary to /usr/local/bin:

     sudo install tanzu-cli-linux_amd64 /usr/local/bin/tanzu
     

   • Windows:

     1. Create a new Program Files\tanzu folder.
     2. Copy the tanzu-cli-windows_amd64.exe file into the new Program Files\tanzu folder.
     3. Rename tanzu-cli-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. The path value must not include the .exe extension. For example, C:\Program Files\tanzu.

4. Check that the correct version of the CLI is properly installed. For example:

   tanzu version
   version: v1.3.0
   ...
   

To download and install the Tanzu CLI from a binary release on GitHub, follow the instructions in the From Binary Releases in the GitHub Project section of Installing the Tanzu CLI.

Install the Tanzu CLI Plugins for TKG v2.5.2

To install the standalone Tanzu CLI plugins for Tanzu Kubernetes Grid v2.5.2:

1. List the standalone Tanzu CLI plugins for Tanzu Kubernetes Grid v2.5.2:

   tanzu plugin group get vmware-tkg/default:v2.5.2
   

   The output looks similar to the following:

   Plugins in Group:  vmware-tkg/default:v2.5.2
     NAME                TARGET      VERSION
     isolated-cluster    global      v0.32.3
     management-cluster  kubernetes  v0.32.3
     package             kubernetes  v0.32.1
     pinniped-auth       global      v0.32.3
     secret              kubernetes  v0.32.0
     telemetry           kubernetes  v0.32.3
   

   To list all available versions for the vmware-tkg/default plugin group, run:

   tanzu plugin group search -n vmware-tkg/default --show-details
   

2. Install the standalone plugins for Tanzu Kubernetes Grid v2.5.2:

   tanzu plugin install --group vmware-tkg/default:v2.5.2
   

3. Verify that the plugins installed successfully:

   tanzu plugin list
   

   Each plugin name and plugin version returned by tanzu plugin group get vmware-tkg/default:v2.5.2 must be included in the output of tanzu plugin list.

   Note

   After you have installed the Tanzu CLI and standalone plugins for Tanzu Kubernetes Grid but before you have used it to connect 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. The Tanzu CLI installs context-scoped plugins automatically when you connect to a management cluster. For more information about Tanzu CLI plugins and how to install them, see Install Tanzu CLI Plugins.

Install the Kubernetes CLI

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

Important

Previous versions of TKG provided a kubectl download that matched the Kubernetes version of the management cluster for that release. From TKG v2.5.2 onwards, TKG supports running Kubernetes versions on workload clusters that are more recent than the version of Kubernetes that is running on management clusters. The Kubernetes version skew policy supports the use of a given minor version of kubectl with Kubernetes API Server minor versions N-1, N and N+1. So, for example, if you are using kubectl v1.28, this version is officially supported for use with clusters running Kubernetes API Server v1.29, v1.28 and v1.27. Using a version of kubectl that is more than N-1 or N+1 minor versions adrift of the Kubernetes API version in a cluster might lead to unpredictable results. From v2.5.2 onwards, TKG provides a version of kubectl for each supported Kubernetes version.

1. Go to the Broadcom Support Portal and log in with your VMware customer credentials.

2. Visit the Tanzu Kubernetes Grid downloads page and select 2.5.2.

3. Scroll to the download for your OS, locate an version version of kubectl, for example kubectl cli v1.28.11 for Mac/Linux/Windows, and click the download button.

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

5. To unpack the kubectl binary for your operating system, use the extraction tool of your choice. For example, the gunzip command.

   macOS

   Run gunzip kubectl-mac-v1.28.11+vmware.2.gz

   Linux

   Run gunzip kubectl-linux-v1.28.11+vmware.2.gz

   Windows

   Use the Windows extractor tool to unzip kubectl-windows-v1.28.11+vmware.2.exe.gz

6. Make the CLI available to the system:

   macOS

   1. Make the downloaded file executable:

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

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

      sudo install kubectl-mac-v1.28.11+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.28.11+vmware.2
      

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

      sudo install kubectl-linux-v1.28.11+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.28.11+vmware.2.exe file into the new Program Files\kubectl folder.
   3. Rename kubectl-windows-v1.28.11+vmware.2.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.

      kubectl version
      

What to Do Next

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