check-circle-line exclamation-circle-line close-line


Before you can use the Tanzu Kubernetes Grid CLI or installer interface to deploy the management cluster, you must prepare the machine on which you run the Tanzu Kubernetes Grid CLI and your Amazon EC2 account.

General Requirements

  • Perform the steps described in Set Up Tanzu Kubernetes Grid .
  • You have the access key and access key secret for an active Amazon Web Services account.
  • Your AWS account must have Administrator privileges.
  • Your AWS account has a sufficient quota of Virtual Private Cloud (VPC) instances. Each management cluster that you deploy creates one VPC. The default VPC quota is 5 instances. For more information, see Amazon VPC Quotas in the AWS documentation.
  • Install the AWS CLI.
  • Install jq.

    The AWS CLI uses jq to process JSON when creating SSH key pairs. It is also used to prepare the environment or configuration variables when you deploy Tanzu Kubernetes Grid by using the CLI.

Resource Usage in Your Amazon Web Services Account

For each cluster that you create, Tanzu Kubernetes Grid provisions a set of resources in your Amazon Web Services account.

For development clusters that are not configured for high availability, Tanzu Kubernetes Grid provisions the following resources:

  • 3 VMs

    The VMs include a control plane node, a worker node (to run the cluster agent extensions), and a bastion host. If you specify additional VMs in your node pool, those are provisioned as well.

  • 4 security groups (one for the load balancer and one for each of the initial VMs)

  • 1 private subnet and 1 public subnet in the specified availability zone
  • 1 public and 1 private route table in the specified availability zone
  • 1 classic load balancer
  • 1 internet gateway
  • 1 NAT gateway in the specified availability zone
  • 2 VPC Elastic IPs, one for the NAT gateway, and one for the Elastic Load Balancer

For production clusters that are configured for high availability, Tanzu Kubernetes Grid provisions the resources listed above and the following additional resources to support replication in two additional availability zones:

  • 2 additional control plane VMs
  • 2 additional private and public subnets
  • 2 additional private and public route tables
  • 2 additional NAT gateways
  • 2 additional VPC elastic IPs

Amazon Web Services implements a set of default limits or quotas on these types of resources, and allows you to modify the limits. Typically the default limits are sufficient to get started creating clusters from Tanzu Kubernetes Grid. However, as you increase the number of clusters you are running or the workloads on your clusters, you will encroach on these limits. When you reach the limits imposed by Amazon Web Services, any attempts to provision that type of resource fail. As a result, Tanzu Kubernetes Grid will be unable to create a new cluster, or you might be unable to create additional deployments on your existing clusters.

For example, if your quota on internet gateways is set to 5 and you already have five in use, then Tanzu Kubernetes Grid is unable to provision the necessary resources when you attempt to create a new cluster.

Therefore regularly assess the limits you have specified in Amazon Web Services account, and adjust them as necessary to fit your business needs.

Install the clusterawsadm Utility and Set Up a CloudFormation Stack

Tanzu Kubernetes Grid uses Cluster API Provider AWS to deploy clusters to Amazon EC2. Cluster API Provider AWS requires the clusterawsadm command line utility to be present on your system.

The clusterawsadm command line utility assists with identity and access management (IAM) for Cluster API Provider AWS. Tanzu Kubernetes Grid uses Cluster API Provider AWS to deploy clusters to Amazon EC2.

The clusterawsadm utility takes the credentials that you set as environment variables and uses them to create a CloudFormation stack in your AWS account with the correct IAM resources. Tanzu Kubernetes Grid uses the resources of the CloudFormation stack to create management and Tanzu Kubernetes clusters. The IAM resources are added to the control plane and node roles when they are created during cluster deployment. For more information about CloudFormation stacks, see Working with Stacks in the AWS documentation.

  1. Create the following environment variables for your AWS account.

    • Your AWS access key:

      export AWS_ACCESS_KEY_ID=aws_access_key

    • Your AWS access key secret:

      export AWS_SECRET_ACCESS_KEY=aws_access_key_secret

    • If you use multi-factor authentication, your AWS session token.

      export AWS_SESSION_TOKEN=aws_session_token

    • The AWS region in which to deploy the cluster.

      For example, set the region to us-west-2.

      export AWS_REGION=us-west-2

      For the full list of AWS regions, see AWS Service Endpoints.

  2. Go to and log in with your My VMware credentials.
  3. Download the executable for clusterawsadm for your platform.

    • Linux platforms: clusterawsadm-linux-amd64-v0.5.2_vmware.1.gz
    • Mac OS platforms: clusterawsadm-darwin-amd64-v0.5.2_vmware.1.gz
  4. Use either the gunzip command or the extraction tool of your choice to unpack the binary that corresponds to the OS of your bootstrap environment:

    gunzip clusterawsadm-linux-amd64-v0.5.2_vmware.1.gz
    gunzip clusterawsadm-darwin-amd64-v0.5.2_vmware.1.gz

    The resulting files are clusterawsadm-linux or clusterawsadm-darwin.

  5. Rename the binary for your platform to clusterawsadm, make sure that it is executable, and add it to your Path.

    1. Move the binary into the /usr/local/bin folder and rename it to clusterawsadm.
      • Linux:
        mv ./clusterawsadm-linux /usr/local/bin/clusterawsadm
      • Mac OS:
        mv ./clusterawsadm-darwin /usr/local/bin/clusterawsadm
    2. Make the file executable.
      chmod +x /usr/local/bin/clusterawsadm
  6. Run the following clusterawsadm command to create a CloudFoundation stack.

    clusterawsadm alpha bootstrap create-stack

    You only need to run clusterawsadm once per account. The CloudFormation stack that is created is not specific to any region.

Register an SSH Public Key with Your AWS Account

In order for Tanzu Kubernetes Grid VMs to launch on Amazon EC2, you must provide the public key part of an SSH key pair to Amazon EC2 for every region you would like to deploy a management cluster.

NOTE: AWS only supports RSA keys. The keys required by AWS are of a different format to those required by vSphere. You cannot use the same key pair for both vSphere and AWS deployments.

If you do not already have an SSH key pair, you can use the AWS CLI to create one, by performing the steps below.

  1. Create a key pair named default and save it as default.pem.

    aws ec2 create-key-pair --key-name default --output json | jq .KeyMaterial -r > default.pem
  2. Log in to your Amazon EC2 dashboard, and go to Network & Security > Key Pairs to verify that the created key pair is registered with your account.

Set Your AWS Credentials as Environment Variables for Use by Cluster API

After you have created the CloudFoundation stack, you must set your AWS credentials as environment variables. Cluster API Provider AWS needs these variables so that it can write the credentials into cluster manifests when it creates clusters. You must perform the steps in Install the clusterawsadm Utility and Set Up a CloudFormation Stack before you perform these steps.

  1. Set a new environment variable for your AWS credentials.
    export AWS_CREDENTIALS=$(aws iam create-access-key --user-name --output json)
  2. Replace the environment variable that you created for your AWS access key ID.
    export AWS_ACCESS_KEY_ID=$(echo $AWS_CREDENTIALS | jq .AccessKey.AccessKeyId -r)
  3. Replace the environment variable that you created for your secret access key.
    export AWS_SECRET_ACCESS_KEY=$(echo $AWS_CREDENTIALS | jq .AccessKey.SecretAccessKey -r)
  4. Set a new environment variable to encode your AWS credentials.
    export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm alpha bootstrap encode-aws-credentials)

Identify the Tanzu Kubernetes Grid Amazon Machine Image for Your Region

Tanzu Kubernetes Grid creates the management cluster and Tanzu Kubernetes cluster node VMs from standard Amazon Linux 2 Amazon Machine Images (AMI). A Tanzu Kubernetes Grid AMI is publicly available in every AWS region, to all Amazon EC2 users.

To direct Tanzu Kubernetes Grid to the correct AMI, you must create an environment variable with the AMI ID of the AMI for your designated region. For example, the AMI ID for the us-west-2 region is ami-074a82cfc610da035.

export AWS_AMI_ID=ami-074a82cfc610da035

For the full list of AMI IDs for each AWS region in this release of Tanzu Kubernetes Grid, see the Tanzu Kubernetes Grid 1.0 Release Notes.
If you have Tanzu Kubernetes Grid Plus support, you can engage with Tanzu Kubernetes Grid Plus Customer Reliability Engineers, who can help you to build custom Amazon images.

What to Do Next

Your environment is now ready for you to deploy the Tanzu Kubernetes Grid management cluster to Amazon EC2.