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.
clusterawsadmUtility and Set Up a CloudFormation Stack
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.
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:
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)
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:
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.
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.
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.
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.
Create the following environment variables for your AWS account.
Your AWS access key:
Your AWS access key secret:
If you use multi-factor authentication, your AWS session token.
The AWS region in which to deploy the cluster.
For example, set the region to
For the full list of AWS regions, see AWS Service Endpoints.
Download the executable for
clusterawsadm for your platform.
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:
The resulting files are
Rename the binary for your platform to
clusterawsadm, make sure that it is executable, and add it to your
/usr/local/binfolder and rename it to
mv ./clusterawsadm-linux /usr/local/bin/clusterawsadm
mv ./clusterawsadm-darwin /usr/local/bin/clusterawsadm
chmod +x /usr/local/bin/clusterawsadm
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.
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.
Create a key pair named
default and save it as
aws ec2 create-key-pair --key-name default --output json | jq .KeyMaterial -r > default.pem
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.
export AWS_CREDENTIALS=$(aws iam create-access-key --user-name bootstrapper.cluster-api-provider-aws.sigs.k8s.io --output json)
export AWS_ACCESS_KEY_ID=$(echo $AWS_CREDENTIALS | jq .AccessKey.AccessKeyId -r)
export AWS_SECRET_ACCESS_KEY=$(echo $AWS_CREDENTIALS | jq .AccessKey.SecretAccessKey -r)
export AWS_B64ENCODED_CREDENTIALS=$(clusterawsadm alpha bootstrap encode-aws-credentials)
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
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.
Your environment is now ready for you to deploy the Tanzu Kubernetes Grid management cluster to Amazon EC2.