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

<

This topic describes how to use the Tanzu Kubernetes Grid CLI to deploy a management cluster to Amazon Elastic Compute Cloud (Amazon EC2).

Prerequisites

  • Make sure that you have met the all of the requirements listed in Set Up Tanzu Kubernetes Grid and Prepare to Deploy Management Clusters to Amazon EC2.
  • For information about the configurations of the different sizes of node instances, for example t3.large, or t3.xlarge, see Amazon EC2 Instance Types.
  • For information about when to create a Virtual Private Cloud (VPC) and when to reuse an existing VPC, see Resource Usage in Your Amazon Web Services Account.
  • It is strongly recommended to use the Tanzu Kubernetes Grid installer interface rather than the CLI to deploy your first management cluster to Amazon EC2. When you deploy a management cluster by using the installer interface, it populates the config.yaml file for the management cluster with the required parameters. You can use the created config.yaml as a model for future deployments from the CLI.

    If this is the first time that you are running Tanzu Kubernetes Grid commands on this machine, and you have not already deployed a management cluster to Amazon EC2 by using the Tanzu Kubernetes Grid installer interface, open a terminal and run the tkg get management-cluster command.

    tkg get management-cluster
    

    Running a tkg command for the first time creates the $HOME/.tkg folder, that contains the management cluster configuration file config.yaml and other configuration files.

Procedure

IMPORTANT:

Do not run multiple management cluster deployments on the same bootstrap environment machine at the same time. Do not change context or edit the .kube-tkg/config file while Tanzu Kubernetes Grid operations are running.

Tanzu Kubernetes Grid does not support IPv6 addresses. This is because upstream Kubernetes only provides alpha support for IPv6. Always provide IPv4 addresses in the procedures in this topic.

  1. Open the .tkg/config.yaml file in a text editor.

    If you have already deployed a management cluster to Amazon EC2 from the installer interface, you will see variables that describe your previous deployment.

    If you have not already deployed a management cluster to Amazon EC2 from the installer interface, copy and paste the following rows into the configuration file, after the end of the images section.

    AWS_REGION:
    AWS_NODE_AZ:
    AWS_PRIVATE_NODE_CIDR:
    AWS_PUBLIC_NODE_CIDR:
    AWS_PUBLIC_SUBNET_ID:
    AWS_PRIVATE_SUBNET_ID:
    AWS_SSH_KEY_NAME:   
    AWS_VPC_ID:
    AWS_VPC_CIDR:    
    BASTION_HOST_ENABLED:  
    CLUSTER_CIDR:    
    CONTROL_PLANE_MACHINE_TYPE:
    NODE_MACHINE_TYPE:
    

    The table below describes all of the variables that you must set for deployment to Amazon EC2. Leave a space between the colon (:) and the variable value. For example:

    AWS_NODE_AZ: us-west-2a
    

    IMPORTANT: Any environment variables that you have set that have the same key as the variables that you set in config.yaml will override the values that you set in config.yaml. You must unset those environment variables before you deploy the management cluster from the CLI.

    Option Value Description
    AWS_REGION us-west, ap-northeast, etc. The name of the AWS region in which to deploy the management cluster. In Tanzu Kubernetes Grid 1.1.2 and later, in addition to the regular AWS regions, you can also specify the us-gov-east and us-gov-west regions in AWS GovCloud. If you have already set a different region as an environment variable, for example in Prepare to Deploy Management Clusters to Amazon EC2, you must unset that environment variable.
    AWS_NODE_AZ us-west-2a, ap-northeast-2b, etc. The name of the AWS availability zone in your chosen region, to use as the availability zone for nodes of this management cluster. Availability zone names are the same as the AWS region name, with a single lower-case letter suffix, such as a, b, c.
    AWS_PRIVATE_NODE_CIDR 10.0.0.0/24 If you set AWS_VPC_CIDR, and the recommended range of 10.0.0.0/24 is not available, enter a different IP range in CIDR format for private nodes to use. This setting is not required if you set AWS_VPC_ID.
    AWS_PUBLIC_NODE_CIDR 10.0.1.0/24 If you set AWS_VPC_CIDR, and the recommended range of 10.0.1.0/24 is not available, enter a different IP range in CIDR format for public nodes to use. This setting is not required if you set AWS_VPC_ID.
    AWS_PRIVATE_SUBNET_ID Private subnet for the VPC If you set AWS_VPC_CIDR to use an existing VPC, enter the CIDR for the private subnet for that VPC. For example, 100.84.0.0/13. This setting is optional. If you do not set it, tkg init identifies the private subnet automatically.
    AWS_PUBLIC_SUBNET_ID Public subnet for the VPC If you set AWS_VPC_CIDR to use an existing VPC, enter the CIDR for the public subnet for that VPC. For example, 100.64.0.0/24. This setting is optional. If you do not set it, tkg init identifies the public subnet automatically.
    AWS_SSH_KEY_NAME Your SSH key name Enter the name of the SSH private key that you registered with your Amazon EC2 account.
    AWS_VPC_ID VPC ID name To use a VPC that already exists in your AWS account, enter the ID of the VPC. If you want to reuse a VPC that already exists in the availability zone, configure the AWS_VPC_ID, AWS_PUBLIC_SUBNET_ID, and AWS_PRIVATE_SUBNET_ID settings. This option is not required if you set AWS_VPC_CIDR. If you set this option, the AWS_NODE_AZ setting is ignored. If you specify an existing VPC, a bastion node is not created by default.
    AWS_VPC_CIDR 10.0.0.0/16 If you want Tanzu Kubernetes Grid to create a new VPC in the selected availability zone, configure the AWS_VPC_CIDR, AWS_PUBLIC_NODE_CIDR, and AWS_PRIVATE_NODE_CIDR settings. You must also configure the AWS_NODE_AZ setting. If the recommended range of 10.0.0.0/16 is not available, enter a different IP range in CIDR format in AWS_VPC_CIDR for the management cluster to use. This setting is not required if you set AWS_VPC_ID.
    BASTION_HOST_ENABLED "true" or "false" Specify "true" to deploy an AWS basion host in the availability zone, or "false" to reuse an existing bastion host. If you set AWS_VPC_ID to use an existing VPC, by default a bastion host is not created. If no bastion host exists in your availability zone and you set AWS_VPC_ID to use an existing VPC, set BASTION_HOST_ENABLED to true.
    CLUSTER_CIDR 100.96.0.0/11 If the recommended range of 100.96.0.0/11 is not available, enter a different IP range in CIDR format for pods to use.
    CONTROL_PLANE_MACHINE_TYPE t3.size Enter i3.xlarge, r4.8xlarge, m5a.4xlarge, m5a.2xlarge, m5.xlarge, m5.large, t3.xlarge, t3.large, t3.medium, or t3.small for the control plane node VMs, depending on the expected workloads that you will run in the cluster. In Tanzu Kubernetes Grid 1.1.2 and later, you can specify or override this value by using the tkg init --size or --controlplane-size options.
    NODE_MACHINE_TYPE m5.size Enter i3.xlarge, r4.8xlarge, m5a.4xlarge, m5a.2xlarge, m5.xlarge, m5.large, t3.xlarge, t3.large, t3.medium, or t3.small for the worker node VMs, depending on the expected workloads that you will run in the cluster. In Tanzu Kubernetes Grid 1.1.2 and later, you can specify or override this value by using the tkg init --size or --worker-size options.

  2. Run the tkg init command.

    Running tkg init for the first time creates the $HOME/.tkg folder, that contains the template configuration file config.yaml from which the management cluster is deployed.

    • You must specify at least the --infrastructure aws option.

      tkg init --infrastructure aws
      
    • You can optionally specify a name for the management cluster in the --name option. If you do not specify a name, Tanzu Kubernetes Grid automatically generates a unique name for the cluster. If you do specify a name, that name must be compliant with DNS hostname requirements as outlined in RFC 952 and amended in RFC 1123.

      tkg init --infrastructure aws --name aws-mgmt-cluster
      
    • To deploy a management cluster with a single control plane node, add the --plan dev option. If you do not specify --plan, the dev plan is used by default.

      tkg init --infrastructure aws --name aws-mgmt-cluster --plan dev
      
    • To deploy a highly available management cluster with three control plane nodes, specify the --plan prod option.

      tkg init --infrastructure aws --name aws-mgmt-cluster --plan prod
      
    • By default Tanzu Kubernetes Grid creates $HOME/.tkg and creates the cluster configuration file, config.yaml in that folder. To create config.yaml in a different location or with a different name, specify the --config option. It might be useful to do this if you want to use different management clusters to deploy Tanzu Kubernetes clusters with different configurations, for example so that they can share a VPC. If you specify the --config option, Tanzu Kubernetes Grid only creates the YAML file in the specified location. Other files are still created in the $HOME/.tkg folder.

      tkg init --infrastructure aws --name aws-mgmt-cluster --config /path/to/file/my-config.yaml
      
    • By default Tanzu Kubernetes Grid saves the kubeconfig for all management clusters in the $HOME/.kube-tkg/config.yaml file. If you want to keep the kubeconfig file for a management cluster separate from the kubeconfig file for other management clusters, for example so that you can share it, specify the --kubeconfig command.

      tkg init --infrastructure aws --name aws-mgmt-cluster --kubeconfig /path/to/file/my-kubeconfig.yaml
      
    • To create a management cluster in which all of the control plane and worker node VMs are the same size, specify the --size option with a value of i3.xlarge, r4.8xlarge, m5a.4xlarge, m5a.2xlarge, m5.xlarge, m5.large, t3.xlarge, t3.large, t3.medium, or t3.small.

      tkg init --infrastructure aws --name aws-mgmt-cluster --size t3.xlarge
      

      This option is available in Tanzu Kubernetes Grid 1.1.2 and later. If you specify the --size option, any values that you specified for the CONTROL_PLANE_MACHINE_TYPE and NODE_MACHINE_TYPE settings in config.yaml are overridden.

    • To create a management cluster in which the control plane and worker node VMs are different sizes, specify the --controlplane-size and --worker-size options with values of i3.xlarge, r4.8xlarge, m5a.4xlarge, m5a.2xlarge, m5.xlarge, m5.large, t3.xlarge, t3.large, t3.medium, or t3.small.

      tkg init --infrastructure aws --name aws-mgmt-cluster --controlplane-size t3.medium --worker-size m5.large
      

      These options are available in Tanzu Kubernetes Grid 1.1.2 and later. If you specify the --controlplane-size and --worker-size options, any values that you specified for the CONTROL_PLANE_MACHINE_TYPE and NODE_MACHINE_TYPE settings in config.yaml, or in the --size option, are overridden.

  3. Follow the progress of the deployment of the management cluster in the terminal.

    Deployment of the management cluster can take several minutes. The first run of tkg init takes longer than subsequent runs because it has to pull the required Docker images into the image store on your bootstrap environment. Subsequent runs do not require this step, so are faster.

What to Do Next