Install the Tanzu CLI and Kubernetes CLI for Use with a vSphere with Tanzu Supervisor

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.0.x documentation.

If you are using the vSphere with Tanzu Supervisor on vSphere 8 as a management cluster, after you install the Tanzu CLI, you can connect it to the Supervisor.

Note

The instructions in this topic are specific to installing the Tanzu CLI for use with a vSphere with Tanzu Supervisor on vSphere 8. If you are installing the Tanzu CLI in order to deploy standalone management clusters on vSphere without a Supervisor, on AWS, or on Azure, see the corresponding topic in Deploying and Managing Tanzu Kubernetes Grid 2.4 Standalone Management Clusters, Install the Tanzu CLI and Kubernetes CLI for Use with Standalone Management Clusters.

The Tanzu CLI communicates with the Supervisor to create and manage workload clusters in vSphere with Tanzu.

Tanzu Kubernetes Grid v2.x and vSphere with Tanzu Supervisor in vSphere 8

Important

The vSphere with Tanzu Supervisor in vSphere 8.0.1c and later runs TKG v2.2. Earlier versions of vSphere 8 run TKG v2.0, which was not released independently of Supervisor. Due to the earlier TKG version that is embedded in Supervisor, some of the features that are available if you are using a standalone TKG 2.4 management cluster are not available if you are using a vSphere with Tanzu Supervisor to create workload clusters. Later TKG releases will be embedded in Supervisor in future vSphere update releases. Consequently, the version of TKG that is embedded in the latest vSphere with Tanzu version at a given time might not be as recent as the latest standalone version of TKG. However, the versions of the Tanzu CLI that are compatible with all TKG v2.x releases are fully supported for use with Supervisor in all releases of vSphere 8. For example, Tanzu CLI v0.90.1 is fully backwards compatible with the TKG 2.2 plugins that Supervisor provides.

Tanzu Kubernetes Grid v2.x and vSphere with Tanzu in vSphere 7

Caution

The versions of the Tanzu CLI that are compatible with TKG 2.x and with the vSphere with Tanzu Supervisor in vSphere 8 are not compatible with the Supervisor Cluster in vSphere 7. To use the Tanzu CLI with a vSphere with Tanzu Supervisor Cluster on vSphere 7, use the Tanzu CLI version from TKG v1.6. To use the versions of the Tanzu CLI that are compatible with TKG 2.x with Supervisor, upgrade to vSphere 8. You can deploy a standalone TKG 2.x management cluster to vSphere 7 if a vSphere with Tanzu Supervisor Cluster is not present. For information about compatibility between the Tanzu CLI and VMware products, see the Tanzu CLI Documentation.

Prerequisites

The bootstrap machine on which you install and run the Tanzu CLI for use with Tanzu Kubernetes Grid 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, deploy standalone management clusters, or both.

To run the Tanzu CLI with Tanzu Kubernetes Grid v2.4, 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 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.

To use a Supervisor cluster as the management cluster, you also need:

Install the Tanzu CLI

To install the Tanzu CLI for use with Tanzu Kubernetes Grid v2.4, you install a compatible version of the Tanzu Core CLI and the Tanzu CLI plugins for Tanzu Kubernetes Grid v2.4. 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.4.

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):

      • If the version that you want to install is the latest available version of the Tanzu CLI, for example, v1.0.0, run:

        sudo apt update
        sudo apt install -y ca-certificates curl gpg
        sudo mkdir -p /etc/apt/keyrings
        curl -fsSL https://packages.vmware.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 -y tanzu-cli
        
      • If you want to install an earlier version of the Tanzu CLI, for example, v0.90.1, run:

        sudo apt update
        sudo apt install -y ca-certificates curl gpg
        sudo mkdir -p /etc/apt/keyrings
        curl -fsSL https://packages.vmware.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=0.90.1
        
    • Chocolatey (Windows):

      • If the version that you want to install is the latest available version of the Tanzu CLI, for example, v1.0.0, run:

        choco install tanzu-cli
        
      • If you want to install an earlier version of the Tanzu CLI, for example, v0.90.1, run:

        choco install tanzu-cli --version 0.90.1
        
    • Homebrew (MacOS):

      • If the version that you want to install is the latest available version of the Tanzu CLI, for example, v1.0.0, run:

        brew update
        brew install vmware-tanzu/tanzu/tanzu-cli
        
      • If you want to install an earlier version of the Tanzu CLI, for example, v0.90.1, run:

        brew update
        brew tap-new local/tap
        brew extract --version=0.90.1 vmware-tanzu/tanzu/tanzu-cli local/tap
        brew install tanzu-cli@0.90.1
        
    • YUM or DNF (RHEL):

      • If the version that you want to install is the latest available version of the Tanzu CLI, for example, v1.0.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.vmware.com/tools/keys/VMWARE-PACKAGING-GPG-RSA-KEY.pub
        EOF
        
        sudo yum install -y tanzu-cli # If you are using DNF, run sudo dnf install -y tanzu-cli.
        
      • If you want to install an earlier version of the Tanzu CLI, for example, v0.90.1, 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.vmware.com/tools/keys/VMWARE-PACKAGING-GPG-RSA-KEY.pub
        EOF
        
        sudo yum install tanzu-cli-0.90.1 # If you are using DNF, run sudo dnf install tanzu-cli-0.90.1.
        
  3. Check that the correct version of the CLI is properly installed. For example:

    tanzu version
    version: v1.0.0
    ...
    
Install from a binary release
You can download the Tanzu CLI binary from VMware Customer Connect or GitHub. For a list of all compatible CLI versions, see Product Interoperability Matrix.

To download a binary release of the Tanzu CLI from Customer Connect and then install it:

  1. Download and unpack the Tanzu CLI binary:

    1. Go to the VMware Tanzu CLI page on VMware Customer Connect and under Product Downloads for Tanzu CLI v1.0.0, locate and download the Tanzu CLI binary for your operating system (OS).
    2. 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. 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.
  3. Check that the correct version of the CLI is properly installed. For example:

    tanzu version
    version: v1.0.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.4

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

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

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

    The output looks similar to the following:

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

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

    tanzu plugin install --group vmware-tkg/default:v2.4.1
    
  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.4.1 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:

  1. Go to VMware Customer Connect and log in with your VMware Customer Connect credentials.

  2. Browse to Tanzu Kubernetes Grid v2.4.1 Product Downloads.

  3. Scroll to the section labeled Kubectl 1.27.5 for VMware Tanzu Kubernetes Grid 2.4.1.

    macOS
    Locate kubectl cli v1.27.5 for Mac and click Download Now.
    Linux
    Locate kubectl cli v1.27.5 for Linux and click Download Now.
    Windows
    Locate kubectl cli v1.27.5 for Windows and click Download Now.
  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
    gunzip kubectl-mac-v1.27.5+vmware.1.gz
    
    Linux
    gunzip kubectl-linux-v1.27.5+vmware.1.gz
    
    Windows
    Use the Windows extractor tool to unzip kubectl-windows-v1.27.5+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.27.5+vmware.1
      
    2. Install the binary to /usr/local/bin:

      sudo install kubectl-mac-v1.27.5+vmware.1 /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.27.5+vmware.1
      
    2. Install the binary to /usr/local/bin:

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

      kubectl version
      

What to Do Next

Before you can use the Tanzu CLI and kubectl to deploy workload clusters and service packages to Tanzu Kubernetes Grid, Connect the Tanzu CLI to the Supervisor as described below.

Connect the Tanzu CLI to the Supervisor

To connect the Tanzu CLI to the supervisor, do the following:

  1. Obtain the IP address of the Supervisor from vCenter:

    1. In the Hosts and Clusters view, select the datacenter that hosts the Supervisor.
    2. Under Namespaces, select the namespace containing or adjacent to the three SupervisorControlPlaneVM instances.
    3. In the main pane, under Summary > Status > Link to CLI Tools, click Copy link and record the URL, for example, https://192.168.123.3.
  2. No IDP: If you are not using an external identity provider:

    1. (Optional) Configure the kubectl vsphere plugin with a trusted certificate as described in Configure Secure Login for vSphere with Tanzu Clusters.

    2. Run kubectl vsphere login to log in to vSphere. For more information about this step, see Connect to Supervisor as a vCenter Single Sign-On User with Kubectl.

      kubectl vsphere login --vsphere-username VSPHERE-USERNAME --server=SUPERVISOR-IP
      

      Where VSPHERE-USERNAME is your vCenter single sign-on (SSO) account username, for example administrator@vsphere.local, and SUPERVISOR-IP is the Supervisor IP address obtained above.

      If you did not configure the kubectl vsphere plugin with a trusted certificate, you can log in insecurely by appending --insecure-skip-tls-verify=true to the command above.

      Caution

      Only use insecure login in a development environment.

    3. Enter the password that you use to log in to vCenter.

      When you successfully log in, the kubectl vsphere login command:

      • Creates or modifies your local kubeconfig file to add a token that authenticates with the Kubernetes API
      • Lists all of the Kubernetes contexts to which you have access. This list should include the Supervisor IP address.
    4. Set the context of kubectl to the Supervisor.

      kubectl config use-context SUPERVISOR-IP
      

      Where SUPERVISOR-IP is the context of the Supervisor; see Get and Use the Supervisor Context in vSphere with Tanzu Services and Workloads.

  3. Collect information to run the tanzu context create command, which connects to the Supervisor:

    • Decide on a name for the Tanzu CLI to use for the Supervisor.
    • The path to the local kubeconfig file, which defaults to ~/.kube/config and is set by the KUBECONFIG environment variable.
  4. Run the tanzu context create command, passing in the values above, for example:

    No IDP:

    tanzu context create my-supervisor --kubeconfig ~/.kube/config --kubecontext 192.168.123.3
    

    This registers the Supervisor context with the Tanzu CLI and downloads the the plugins that are specific to Supervisor.

    [ok] successfully logged in to management cluster using the kubeconfig my-supervisor
    [i] Checking for required plugins...
    [i] Installing plugin 'cluster:v0.29' with target 'kubernetes'
    [i] Plugin binary for 'cluster:v0.29' found in cache
    [i] Installing plugin 'feature:v0.29' with target 'kubernetes'
    [i] Plugin binary for 'feature:v0.29' found in cache
    [i] Installing plugin 'kubernetes-release:v0.29' with target 'kubernetes'
    [i] Plugin binary for 'kubernetes-release:v0.29' found in cache
    [i] Installing plugin 'namespaces:v1.0.0' with target 'kubernetes'
    [i] Plugin binary for 'namespaces:v1.0.0' found in cache
    [i] Successfully installed all required plugins
    

    With an IDP:

    tanzu context create --endpoint https://10.73.27.32 --name oidc-user
    
    tanzu context use https://10.73.27.32 oidc-user
    
    Detected a vSphere Supervisor being used
    Log in by visiting this link:
    ...
    https://10.27.62.33/wcp/pinniped/oauth2/authorize?..
    ...
    Optionally, paste your authorization code: G2TcS145Q4e6A1YKf743n3BJlfQAQ_UdjXy38TtEEIo.ju4QV3PTsUvOigVUtQllZ7AJFU0YnjuLHTRVoNxvdZc
    ...
    ??? successfully logged in to management cluster using the kubeconfig oidc-user
    Checking for required plugins...
    All required plugins are already installed and up-to-date
    

    In the example above, https://10.73.27.32 is the Supervisor control plane IP address. For more information about this step, see Connect to Supervisor Using the Tanzu CLI and an External IDP.

  5. Check that the Supervisor was added by running tanzu context list, for example:

    tanzu context list
    
    NAME            ISACTIVE  ENDPOINT                      KUBECONFIGPATH                KUBECONTEXT
    my-supervisor   true      https://192.168.123.3:443     /home/vmware/.kube/config     192.168.123.3
    

    tanzu context use should now list the Supervisor by the name that you provided:

    tanzu context use
    
    ? Select a server  [Use arrows to move, type to filter]
    > my-supervisor  ()
     + new server
    
  6. Run tanzu plugin list to see the list of Supervisor specific plugins as well as the standalone CLI plugins.

    tanzu plugin list
    
    Standalone Plugins
      NAME                DESCRIPTION                                                        TARGET      VERSION  STATUS
      isolated-cluster    Prepopulating images/bundle for internet-restricted environments   global      v0.31.1  installed
      pinniped-auth       Pinniped authentication operations (usually not directly invoked)  global      v0.31.1  installed
      management-cluster  Kubernetes management cluster operations                           kubernetes  v0.31.1  installed
      package             Tanzu package management                                           kubernetes  v0.31.1  installed
      secret              Tanzu secret management                                            kubernetes  v0.31.1  installed
      telemetry           Configure cluster-wide settings for vmware tanzu telemetry         kubernetes  v0.31.1  installed
    
    Plugins from Context:  my-supervisor
      NAME                DESCRIPTION                                                TARGET      VERSION  STATUS
      cluster             Kubernetes cluster operations                              kubernetes  v0.29.0  installed
      feature             Operate on features and featuregates                       kubernetes  v0.29.0  installed
      kubernetes-release  Kubernetes release operations                              kubernetes  v0.29.0  installed
      namespaces          Discover vSphere Supervisor namespaces you have access to  kubernetes  v1.0.0   installed
    
    Note

    With vSphere 8.0.1c, plugins for Supervisor context have version v0.29.0.

  7. (Optional) Proceed to Creating Workload Clusters.
check-circle-line exclamation-circle-line close-line
Scroll to top icon