Kubernetes Cluster on AWS
The AWS Kubernetes Cluster template scaffolds a Pulumi project that provisions a managed Amazon EKS cluster inside a new VPC with public and private subnets. Worker nodes run in the private subnets for improved security; load balancers created by cluster workloads are automatically placed in the public subnets.
Before you begin#
Make sure you’ve installed Pulumi and configured your AWS credentials.
Create a new project#
Create a new project using the template in the language of your choice:
TypeScript
Python
Go
C#
YAML
HCLmkdir my-k8s-cluster && cd my-k8s-clusterpulumi new kubernetes-aws-typescriptmkdir my-k8s-cluster && cd my-k8s-clusterpulumi new kubernetes-aws-pythonmkdir my-k8s-cluster && cd my-k8s-clusterpulumi new kubernetes-aws-gomkdir my-k8s-cluster && cd my-k8s-clusterpulumi new kubernetes-aws-csharpmkdir my-k8s-cluster && cd my-k8s-clusterpulumi new kubernetes-aws-yamlmkdir my-k8s-cluster && cd my-k8s-clusterpulumi new kubernetes-aws-hclpulumi new walks you through creating and configuring a new project and stack. A stack is an instance of a project and you can have many of them — dev, staging, prod — each with its own configuration settings. The template also includes some additional settings:
| Key | Description | Default |
|---|---|---|
| aws:region | The AWS region to deploy into | us-west-2 |
| minClusterSize | Minimum size (number of nodes) of cluster | 3 |
| maxClusterSize | Maximum size (number of nodes) of cluster | 6 |
| desiredClusterSize | Desired number of nodes in the cluster | 3 |
| eksNodeInstanceType | Instance type to use for worker nodes | t3.medium |
| vpcNetworkCidr | Network CIDR to use for new VPC | 10.0.0.0/16 |
pulumi config set:
pulumi config set aws:region <value>pulumi config set minClusterSize <value>pulumi config set maxClusterSize <value>pulumi config set desiredClusterSize <value>pulumi config set eksNodeInstanceType <value>pulumi config set vpcNetworkCidr <value>| Key | Description | Default |
|---|---|---|
| aws:region | The AWS region to deploy into | us-west-2 |
| minClusterSize | Minimum size (number of nodes) of cluster | 3 |
| maxClusterSize | Maximum size (number of nodes) of cluster | 6 |
| desiredClusterSize | Desired number of nodes in the cluster | 3 |
| eksNodeInstanceType | Instance type to use for worker nodes | t3.medium |
| vpcNetworkCidr | Network CIDR to use for new VPC | 10.0.0.0/16 |
pulumi config set:
pulumi config set aws:region <value>pulumi config set minClusterSize <value>pulumi config set maxClusterSize <value>pulumi config set desiredClusterSize <value>pulumi config set eksNodeInstanceType <value>pulumi config set vpcNetworkCidr <value>| Key | Description | Default |
|---|---|---|
| aws:region | The AWS region to deploy into | us-west-2 |
| minClusterSize | Minimum size (number of nodes) of cluster | 3 |
| maxClusterSize | Maximum size (number of nodes) of cluster | 6 |
| desiredClusterSize | Desired number of nodes in the cluster | 3 |
| eksNodeInstanceType | Instance type to use for worker nodes | t3.medium |
| vpcNetworkCidr | Network CIDR to use for new VPC | 10.0.0.0/16 |
pulumi config set:
pulumi config set aws:region <value>pulumi config set minClusterSize <value>pulumi config set maxClusterSize <value>pulumi config set desiredClusterSize <value>pulumi config set eksNodeInstanceType <value>pulumi config set vpcNetworkCidr <value>| Key | Description | Default |
|---|---|---|
| aws:region | The AWS region to deploy into | us-west-2 |
| minClusterSize | Minimum size (number of nodes) of cluster | 3 |
| maxClusterSize | Maximum size (number of nodes) of cluster | 6 |
| desiredClusterSize | Desired number of nodes in the cluster | 3 |
| eksNodeInstanceType | Instance type to use for worker nodes | t3.medium |
| vpcNetworkCidr | Network CIDR to use for new VPC | 10.0.0.0/16 |
pulumi config set:
pulumi config set aws:region <value>pulumi config set minClusterSize <value>pulumi config set maxClusterSize <value>pulumi config set desiredClusterSize <value>pulumi config set eksNodeInstanceType <value>pulumi config set vpcNetworkCidr <value>| Key | Description | Default |
|---|---|---|
| aws:region | The AWS region to deploy into | us-west-2 |
| minClusterSize | Minimum size (number of nodes) of cluster | 3 |
| maxClusterSize | Maximum size (number of nodes) of cluster | 6 |
| desiredClusterSize | Desired number of nodes in the cluster | 3 |
| eksNodeInstanceType | Instance type to use for worker nodes | t3.medium |
| vpcNetworkCidr | Network CIDR to use for new VPC | 10.0.0.0/16 |
pulumi config set:
pulumi config set aws:region <value>pulumi config set minClusterSize <value>pulumi config set maxClusterSize <value>pulumi config set desiredClusterSize <value>pulumi config set eksNodeInstanceType <value>pulumi config set vpcNetworkCidr <value>| Key | Description | Default |
|---|---|---|
| aws:region | The AWS region to deploy into | us-west-2 |
| min_cluster_size | The minimum number of nodes in the cluster | 3 |
| max_cluster_size | The maximum number of nodes in the cluster | 6 |
| desired_cluster_size | The desired number of nodes in the cluster | 3 |
| node_instance_type | The EC2 instance type to use for worker nodes | t3.medium |
| vpc_network_cidr | The network CIDR to use for the VPC | 10.0.0.0/16 |
pulumi config set:
pulumi config set aws:region <value>pulumi config set min_cluster_size <value>pulumi config set max_cluster_size <value>pulumi config set desired_cluster_size <value>pulumi config set node_instance_type <value>pulumi config set vpc_network_cidr <value>When setup completes, you’ll see a few key files:
Pulumi.yamlnames the project and the language it’s written in.Pulumi.dev.yamlholds thedevstack’s settings, including the values you just entered.index.tsindex.js__main__.pymain.goProgram.csProgram.fsProgram.vbApp.javaPulumi.yamlmain.tfis the program: the code that declares your cloud resources.
When setup completes, you’ll see a few key files:
Pulumi.yamlnames the project and the language it’s written in.Pulumi.dev.yamlholds thedevstack’s settings, including the values you just entered.index.tsindex.js__main__.pymain.goProgram.csProgram.fsProgram.vbApp.javaPulumi.yamlmain.tfis the program: the code that declares your cloud resources.
When setup completes, you’ll see a few key files:
Pulumi.yamlnames the project and the language it’s written in.Pulumi.dev.yamlholds thedevstack’s settings, including the values you just entered.index.tsindex.js__main__.pymain.goProgram.csProgram.fsProgram.vbApp.javaPulumi.yamlmain.tfis the program: the code that declares your cloud resources.
When setup completes, you’ll see a few key files:
Pulumi.yamlnames the project and the language it’s written in.Pulumi.dev.yamlholds thedevstack’s settings, including the values you just entered.index.tsindex.js__main__.pymain.goProgram.csProgram.fsProgram.vbApp.javaPulumi.yamlmain.tfis the program: the code that declares your cloud resources.
When setup completes, you’ll see a few key files:
Pulumi.yamlnames the project and holds the program: the resources it declares.Pulumi.dev.yamlholds thedevstack’s settings, including the values you just entered.
When setup completes, you’ll see a few key files:
Pulumi.yamlnames the project and the language it’s written in.Pulumi.dev.yamlholds thedevstack’s settings, including the values you just entered.index.tsindex.js__main__.pymain.goProgram.csProgram.fsProgram.vbApp.javaPulumi.yamlmain.tfis the program: the code that declares your cloud resources.
Deploy the project#
Deploy with pulumi up. It starts with a preview of what it’s about to create and asks before it changes anything. Choose yes to deploy. An EKS cluster takes 10 to 20 minutes to create, so expect pulumi up to run that long.
pulumi upPulumi adds a random suffix to most resource names, so the cluster declared as eks-cluster gets a name like eks-cluster-eksCluster-4f8a2c1. This is autonaming. It lets you deploy the same program to more than one stack, and lets Pulumi create a replacement before it deletes the old resource, without names colliding.
When it finishes, Pulumi prints the stack’s outputs, values it only knows once the resources exist:
- kubeconfig
The cluster’s kubeconfig file, which you can use with
kubectlto access and communicate with your cluster.- vpcId
The ID of the VPC that your cluster is running in.
- kubeconfig
The cluster’s kubeconfig file, which you can use with
kubectlto access and communicate with your cluster.- vpcId
The ID of the VPC that your cluster is running in.
- kubeconfig
The cluster’s kubeconfig file, which you can use with
kubectlto access and communicate with your cluster.- vpcId
The ID of the VPC that your cluster is running in.
- kubeconfig
The cluster’s kubeconfig file, which you can use with
kubectlto access and communicate with your cluster.- vpcId
The ID of the VPC that your cluster is running in.
- kubeconfig
The cluster’s kubeconfig file, which you can use with
kubectlto access and communicate with your cluster.- vpcId
The ID of the VPC that your cluster is running in.
- vpc_id
The ID of the VPC that your cluster is running in.
- kubeconfig
The cluster’s kubeconfig file, which you can use with
kubectlto access and communicate with your cluster.
Read one any time with pulumi stack output <name>, or pass it to another command. Save the kubeconfig to a file and point kubectl at it to list the cluster’s nodes:
pulumi stack output kubeconfig --show-secrets > kubeconfigKUBECONFIG=./kubeconfig kubectl get nodesYou should see three nodes with the status Ready. The kubeconfig gets its login token from the AWS CLI, so aws needs to be installed.
Customize the project#
Projects created with the Kubernetes template expose the following configuration settings:
- minClusterSize
The minimum number of nodes to allow in the cluster. Defaults to
3.- maxClusterSize
The maximum number of nodes to allow in the cluster. Defaults to
6.- desiredClusterSize
The desired number of nodes in the cluster. Defaults to
3.- eksNodeInstanceType
The EC2 instance type to use for the nodes. Defaults to
t3.medium.- vpcNetworkCidr
The network CIDR to use for the VPC. Defaults to
10.0.0.0/16.
- minClusterSize
The minimum number of nodes to allow in the cluster. Defaults to
3.- maxClusterSize
The maximum number of nodes to allow in the cluster. Defaults to
6.- desiredClusterSize
The desired number of nodes in the cluster. Defaults to
3.- eksNodeInstanceType
The EC2 instance type to use for the nodes. Defaults to
t3.medium.- vpcNetworkCidr
The network CIDR to use for the VPC. Defaults to
10.0.0.0/16.
- minClusterSize
The minimum number of nodes to allow in the cluster. Defaults to
3.- maxClusterSize
The maximum number of nodes to allow in the cluster. Defaults to
6.- desiredClusterSize
The desired number of nodes in the cluster. Defaults to
3.- eksNodeInstanceType
The EC2 instance type to use for the nodes. Defaults to
t3.medium.- vpcNetworkCidr
The network CIDR to use for the VPC. Defaults to
10.0.0.0/16.
- minClusterSize
The minimum number of nodes to allow in the cluster. Defaults to
3.- maxClusterSize
The maximum number of nodes to allow in the cluster. Defaults to
6.- desiredClusterSize
The desired number of nodes in the cluster. Defaults to
3.- eksNodeInstanceType
The EC2 instance type to use for the nodes. Defaults to
t3.medium.- vpcNetworkCidr
The network CIDR to use for the VPC. Defaults to
10.0.0.0/16.
- minClusterSize
The minimum number of nodes to allow in the cluster. Defaults to
3.- maxClusterSize
The maximum number of nodes to allow in the cluster. Defaults to
6.- desiredClusterSize
The desired number of nodes in the cluster. Defaults to
3.- eksNodeInstanceType
The EC2 instance type to use for the nodes. Defaults to
t3.medium.- vpcNetworkCidr
The network CIDR to use for the VPC. Defaults to
10.0.0.0/16.
- min_cluster_size
The minimum number of nodes to allow in the cluster. Defaults to
3.- max_cluster_size
The maximum number of nodes to allow in the cluster. Defaults to
6.- desired_cluster_size
The desired number of nodes in the cluster. Defaults to
3.- node_instance_type
The EC2 instance type to use for the nodes. Defaults to
t3.medium.- vpc_network_cidr
The network CIDR to use for the VPC. Defaults to
10.0.0.0/16.
All of these settings are optional and may be adjusted either by editing the stack configuration file directly (by default, Pulumi.dev.yaml) or by changing their values with pulumi config set. For example, add a fourth node:
pulumi config set desiredClusterSize 4pulumi uppulumi config set desiredClusterSize 4pulumi uppulumi config set desiredClusterSize 4pulumi uppulumi config set desiredClusterSize 4pulumi uppulumi config set desiredClusterSize 4pulumi uppulumi config set desired_cluster_size 4pulumi upThe new node takes a few minutes to start and join the cluster. Then list the nodes again; there are four:
KUBECONFIG=./kubeconfig kubectl get nodesTo see what else you can add, browse the AWS provider in the Pulumi Registry.
Cleaning up#
You can cleanly destroy the stack and all of its infrastructure with pulumi destroy:
pulumi destroyLearn more#
- Browse other architecture templates in the Templates gallery.
- Explore the Amazon EKS and AWSx provider API docs in the Pulumi Registry.
- Walk through Pulumi from the ground up in Pulumi Tutorials.
- Read the latest Kubernetes posts on the Pulumi blog.