This page provides quickstart instructions to create a cluster and node pool, then deploy a sample application using Anthos clusters on AWS.
Create your cluster with Terraform
You can use Terraform to create a cluster and node pool. Before creating your cluster, the Terraform scripts also prepare your AWS VPC.
After you create a VPC and cluster with Terraform, skip to Deploy an application to the cluster to deploy a sample application.
Create your cluster without Terraform
If you prefer to prepare your AWS VPC and create a cluster and node pool without Terraform, follow these instructions.
Before you begin
Before creating a cluster, you must complete the prerequisites. In particular, you must provide the following resources:
- An AWS VPC where the cluster will run.
- Up to three AWS subnets for the three control plane replicas. Each must be in a different AWS Availability Zone.
- The AWS IAM role that Anthos clusters on AWS will assume when managing your cluster. This requires a specific set of IAM permissions.
- KMS symmetric CMK keys for at-rest encryption of cluster data (etcd) and configuration.
- The AWS IAM instance profile for each control plane replica. This requires a specific set of IAM permissions.
- An EC2 SSH key pair (optional) if you need SSH access to the EC2 instances that run each control plane replica.
It is your responsibility to create and manage these resources, which can be shared between all your Anthos clusters on AWS clusters. All other underlying cluster-scoped AWS resources are managed by Anthos clusters on AWS.
Set default settings for the gcloud CLI
Use the gcloud CLI to configure default settings for your default project and Google Cloud region.
Your project has a project ID as a unique identifier. When you create a project, you can use the automatically generated project ID or you can create your own.
Your Google Cloud region is a location where your clusters will be managed
from. For example,
Management regions for more details.
When you configure these default settings, you don't need to include them when
you run the Google Cloud CLI. You can also specify settings or override default
settings by passing the
--location flags to the
Google Cloud CLI.
When you create Anthos clusters on AWS resources after configuring your default project and location, the resources are automatically created in that project and location.
To set defaults, follow these steps:
Set the default project:
gcloud config set project PROJECT_ID
PROJECT_IDwith your project ID.
Set the default management location:
gcloud config set container_aws/location GOOGLE_CLOUD_LOCATION
GOOGLE_CLOUD_LOCATIONwith your location, such as
Select CIDR ranges for your cluster
Kubernetes requires two CIDR ranges to be provided for the cluster. These CIDR ranges should be chosen so that they do not overlap with CIDR ranges used by your VPC subnets. They should be large enough for the maximum expected size of your cluster.
Pod address CIDR range: When a new
Podis created, it is allocated an IP address from this range. Example range: 192.168.208.0/20
Service address CIDR range: When a new
Serviceis created, it is allocated an IP address from this range. Example range: 192.168.224.0/20
Create a cluster
Use the following command to create a cluster under Anthos clusters on AWS. For more information about this command including its optional parameters, see the gcloud container aws create reference page.
gcloud container aws clusters create aws-cluster-0 \ --cluster-version 1.24.3-gke.2100 \ --aws-region AWS_REGION \ --fleet-project FLEET_PROJECT_ID \ --vpc-id VPC_ID \ --subnet-ids CONTROL_PLANE_SUBNET_1,CONTROL_PLANE_SUBNET_2,CONTROL_PLANE_SUBNET_3 \ --pod-address-cidr-blocks POD_CIDR_BLOCK \ --service-address-cidr-blocks SERVICE_CIDR_BLOCK \ --role-arn API_ROLE_ARN \ --iam-instance-profile CONTROL_PLANE_PROFILE \ --database-encryption-kms-key-arn DB_KMS_KEY_ARN \ --config-encryption-kms-key-arn CONFIG_KMS_KEY_ARN \ --tags "google:gkemulticloud:cluster=aws-cluster-0"
Replace the following:
AWS_REGION: the AWS region to create the cluster in.
FLEET_PROJECT_ID: the Fleet host project where the cluster will be registered
VPC_ID: the ID of the AWS VPC for this cluster that you set up in the Create your VPC prerequisite step
CONTROL_PLANE_SUBNET_3: the subnet IDs for your cluster's three control plane instances that you created in the Create private subnets prerequisite step
POD_CIDR_BLOCK: the CIDR address range for your cluster's pods
SERVICE_CIDR_BLOCK: the CIDR address range for your cluster's services
API_ROLE_ARN: the ARN of the IAM role for the Anthos Multi-Cloud service that you created in the Create Anthos Multi-cloud API role prerequisite step
CONTROL_PLANE_PROFILE: the profile name of the IAM instance associated with the cluster that you chose in the Create control plane role prerequisite step
DB_KMS_KEY_ARN: the Amazon Resource Name (ARN) of one of the AWS KMS keys that you created in the Create an AWS KMS key prerequisite step
CONFIG_KMS_KEY_ARN: the Amazon Resource Name (ARN) of the other of the AWS KMS keys that you created in the Create an AWS KMS key prerequisite step
If present, the
--tags parameter applies the given AWS tag to all the
underlying AWS resources managed by Anthos clusters on AWS. This example tags your
control plane nodes with name of the cluster they belong to.
Create a node pool
Use the following command to create a node pool:
gcloud container aws node-pools create pool-0 \ --cluster aws-cluster-0 \ --node-version 1.24.3-gke.2100 \ --min-nodes 1 \ --max-nodes 5 \ --max-pods-per-node 110 \ --root-volume-size 50 \ --subnet-id NODEPOOL_SUBNET_ID \ --iam-instance-profile NODEPOOL_PROFILE \ --config-encryption-kms-key-arn CONFIG_KMS_KEY_ARN \ --ssh-ec2-key-pair EC2_KEY_PAIR \ --tags "google:gkemulticloud:cluster=aws-cluster-0"
Replace the following:
NODEPOOL_SUBNET_ID: the ID of one of the private subnets that you created in the Create private subnets prerequisite step
NODEPOOL_PROFILE: the IAM instance profile name for the EC2 instances in the node pool that you chose in the Create a node pool IAM role prerequisite step
CONFIG_KMS_KEY_ARN: the Amazon Resource Name (ARN) of the AWS KMS key to encrypt user data
EC2_KEY_PAIR(optional): the name of the EC2 key pair created for SSH access (optional) that you created in the Create SSH key pair prerequisite step
View your cluster status
After you create a cluster and node pool, you can view a cluster's status with the Google Cloud CLI or the Google Cloud console. To view the cluster's status, choose if you are using the Google Cloud CLI or Google Cloud console and follow these steps:
gcloud container aws clusters describe command to get details
about your cluster:
gcloud container aws clusters describe CLUSTER_NAME \ --location GOOGLE_CLOUD_LOCATION
Replace the following:
CLUSTER_NAME: your cluster's name
GOOGLE_CLOUD_LOCATION: the name of the Google Cloud location that manages the cluster
Google Cloud console
In the Google Cloud console, go to the Anthos Clusters page.
Find the section Anthos managed clusters. Your clusters are listed by their name and location.
Click on the cluster's name. A panel with information on the cluster, including its status and enabled Anthos features appears.
Get authentication credentials for the cluster
After creating your cluster, you need to get authentication credentials to interact with the cluster:
gcloud container aws clusters get-credentials aws-cluster-0
This command configures
kubectl to access the cluster you created using
Connect gateway. You need at
least one node pool to use Connect gateway because it relies on the
Connect agent, which runs as a Deployment in the cluster.
Deploy an application to the cluster
Now that you have created a cluster, you can deploy a containerized application
to it. For this quickstart, you can deploy our example web application,
You use Kubernetes objects to create and manage your cluster's resources. You use the Deployment object for deploying stateless applications like web servers. Service objects define rules and load balancers for accessing your application from the internet.
Create the Deployment
hello-app in your cluster, you need to deploy the application by
running the following command:
kubectl create deployment hello-server --image=us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
In this command:
--imagespecifies a container image to deploy. In this case, the command pulls the example image from an Artifact Registry repository,
:1.0indicates the specific image version to pull. If you don't specify a version, the image tagged with
Expose the Deployment
After deploying the application, you need to expose it to the internet so that users can access it. You can expose your application by creating a Service, a Kubernetes resource that exposes your application to external traffic.
To expose your application, run the following
kubectl expose deployment hello-server --type LoadBalancer --port 80 --target-port 8080
Passing in the
--type LoadBalancer flag creates an AWS load
balancer for your container. The
--port flag initializes public port 80 to the
internet and the
--target-port flag routes the traffic to port 8080 of the
Load balancers are billed according to AWS load balancer pricing.
Inspect and view the application
Inspect the running Pods by using
kubectl get pods:
kubectl get pods
You should see one
hello-serverPod running on your cluster.
hello-serverService by using
kubectl get service:
kubectl get service hello-server
From this command's output, copy the Service's external IP address from the
View the application from your web browser by using the external IP with the exposed port:
You have just deployed a containerized web application to Anthos clusters on AWS.
Delete the application's Service and Deployment:
kubectl delete service hello-server kubectl delete deployment hello-server
Delete your node pool by running
gcloud container aws node-pools delete:
gcloud container aws node-pools delete pool-0 --cluster aws-cluster-0
Delete your cluster by running
gcloud container aws clusters delete:
gcloud container aws clusters delete aws-cluster-0