Install the Tanzu Kubernetes Grid CLI

To install Tanzu Kubernetes Grid, you download the Tanzu Kubernetes Grid command line interface (CLI) on bootstrap machine. The bootstrap machine is the laptop, host, or server on which the initial bootstrapping of a management cluster is performed. The bootstrap machine is typically local, but it can also be a physical machine or VM that you access remotely.

The bootstrap machine is where you run Tanzu Kubernetes Grid CLI commands. Tanzu Kubernetes Grid creates a temporary management cluster using a Kubernetes in Docker (kind) cluster on the bootstrap machine. After creating the temporary management cluster locally, Tanzu Kubernetes Grid uses it to provision the final management cluster in the platform of your choice.

Prerequisites

Tanzu Kubernetes Grid provides CLI binaries for Linux, Mac OS, and Windows systems.

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

• If you intend to use the Tanzu Kubernetes Grid installer interface, a browser is available. You can use the Tanzu Kubernetes Grid CLI without a browser, but for first deployments it is strongly recommended to use the installer interface.
• One of the following Docker clients installed and running on your bootstrap machine:
  • Linux machine: Docker
  • Windows machine: Docker Desktop
  • Mac OS machine: Docker Desktop with at least 6.00 GB allocated to Memory, 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.

NOTE: Tanzu Kubernetes Grid uses Cluster API. If you have previously used Cluster API on the machine that you are using as your bootstrap machine, you must delete the ~/.cluster-api folder from that machine. This folder contains Cluster API configuration files that might interfere with the correct operation of Tanzu Kubernetes Grid.

Download and Unpack the Tanzu Kubernetes Grid CLI and kubectl

The tkg CLI ships with a compatible version of the kubectl CLI. To download and unpack both:

1. Go to https://www.vmware.com/go/get-tkg and log in with your My VMware credentials.
2. Under Product Downloads, click Go to Downloads.

3. Scroll down to the VMware Tanzu Kubernetes Grid 1.2.1 CLI and kubectl entries and click the Download Now button:

   • For Linux, download VMware Tanzu Kubernetes Grid CLI for Linux and kubectl cluster cli v1.19.3 for Linux.
   • For Mac OS, download VMware Tanzu Kubernetes Grid CLI for Mac and kubectl cluster cli v1.19.3 for Mac.
   • For Windows, download VMware Tanzu Kubernetes Grid CLI for Windows and kubectl cluster cli v1.19.3 for Windows.

4. (Optional) Verify that your downloaded files are unaltered from the original. Tanzu Kubernetes Grid 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. Unpack the Tanzu Kubernetes Grid CLI binary for your operating system. To unpack the binary, use the extraction tool of your choice. For example, the tar -xzvf command.

   • For Linux, unpack tkg-linux-amd64-v1.2.1-vmware.1.tar.gz.
   • For Mac OS, unpack tkg-darwin-amd64-v1.2.1-vmware.1.tar.gz.
   • For Windows, unpack tkg-windows-amd64-v1.2.1-vmware.1.tar.gz.

   In the tkg folder, the unpacked CLI file is tkg-linux-amd64-v1.2.1+vmware.1, tkg-darwin-amd64-v1.2.1+vmware.1, or tkg-windows-amd64-v1.2.1+vmware.1. The other files in the tkg folder, such as ytt, kapp, and kbld, are required by the Tanzu Kubernetes Grid extensions. You will need them later when you install the extensions.

6. Unpack the kubectl binary. The unpacked kubectl binary files are kubectl-linux-v1.19.3-vmware.1,kubectl-mac-v1.19.3-vmware.1, or kubectl-windows-v1.19.3-vmware.1.exe.

Install the Tanzu Kubernetes Grid CLI

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

1. Navigate to the Tanzu Kubernetes Grid CLI binary that you downloaded and unpacked in the previous section.

2. Rename the CLI binary for your platform to tkg and make it available to the system:

   • For Mac OS and Linux platforms:

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

        mv ./tkg-linux-amd64-v1.2.1+vmware.1 /usr/local/bin/tkg

        mv ./tkg-darwin-amd64-v1.2.1+vmware.1 /usr/local/bin/tkg

     2. Confirm that the binary is executable by running the ls command.

   • For Windows platforms:

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

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

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

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

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

Install kubectl

To install the version of kubectl compatible with the Tanzu Kubernetes Grid CLI, use the same process as in Install the Tanzu Kubernetes Grid CLI above, but with the following substitutions:

• Navigate to the executable you downloaded for kubectl.
• Rename the kubectl-PLATFORM-VERSION executable to kubectl (Linux, Mac) or kubectl.exe (Windows).
• Run kubectl version to check the correct version, and create a security exception if needed.

Initialize the Tanzu Kubernetes Grid CLI

1. Run tkg --help to see the list of commands that the Tanzu Kubernetes Grid CLI provides.

   You can run any command with the --help option to see information about that specific command or sub-command. For example, tkg init --help or tkg create cluster --help.

2. Run the tkg get management-cluster command.

   tkg get management-cluster
   

   Running a tkg command for the first time creates the ~/.tkg folder in your home directory, that contains the Tanzu Kubernetes Grid configuration files.

   • The cluster configuration file ~/.tkg/config.yaml, from which management clusters and Tanzu Kubernetes clusters are created.
   • The ~/.tkg/bom folder, containing bom-*.yaml files that provide references to the correct versions of all of the packages that Tanzu Kubernetes Grid requires when creating clusters for all of the versions of Kubernetes that it supports.

CLI Short Names and Aliases

Most of the Tanzu Kubernetes Grid CLI commands and options have short names or aliases, so that you do not have to type the full command and option names each time you run tkg. For example, -h for --help, and mc for management-cluster. For increased clarity, this documentation always uses the full command and option names. To see the shortnames and aliases for commands and options, run CLI commands with the --help option.

Common Tanzu Kubernetes Grid CLI Options

The Tanzu Kubernetes Grid CLI provides common options that can be used with all of the CLI commands.

Option	Description
--config	The path to the cluster configuration file, if it is not stored in the default location with the default name, ~/.tkg/config.yaml. For example, tkg init --ui --config /path/my-cluster-config.yaml.
--help	Show help for the current command. For example, tkg create cluster --help.
--kubeconfig	The path to the shared kubeconfig file for management clusters and Tanzu Kubernetes clusters, if it is not stored in the default location, ~/.kube-tkg/config. For example, tkg init --ui --kubeconfig /path/my-cluster-kubeconfig.
--log_file	Specify a file in which to save the logs for the current command. For example, tkg scale cluster my-cluster --worker-machine-count=9 --log_file=my-cluster-scale-logs.
--timeout	Amount of time that the current command allows for each internal operation to complete. This option is not a timeout for overall cluster creation. Specify the timeout interval in hours (h), minutes (m), and seconds (s) or a combination of these units. For example, --timeout 2h, --timeout 30m, or --timeout 2h30m10s.
--quiet	Mute all output for the current command.
--v	Set the logging verbosity level for the command.

What to Do Next

The Tanzu Kubernetes Grid CLI is ready. You can set up your bootstrap machine to deploy management clusters to vSphere, Amazon EC2, and Microsoft Azure.

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