Skip to content

Commit b110fc2

Browse files
cloutierMatquetzalliwritessimonrw
authored
document eks managed node groups (#363)
Co-authored-by: Quetzalli <hola@quetzalliwrites.com> Co-authored-by: Simon Walker <s.r.walker101@googlemail.com>
1 parent 2fcff49 commit b110fc2

File tree

1 file changed

+128
-24
lines changed
  • src/content/docs/aws/services

1 file changed

+128
-24
lines changed

‎src/content/docs/aws/services/eks.mdx‎

Lines changed: 128 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,69 @@ To interact with the Kubernetes cluster, you should also install [`kubectl`](htt
2323
Start your LocalStack container using your preferred method.
2424
We will demonstrate how you can auto-install an embedded Kubernetes cluster, configure ingress, and deploy a sample service with ECR.
2525

26+
### Deploy the necessary networking components
27+
28+
First we need to create a VPC for the EKS cluster. You can create a new VPC using the [`CreateVpc` API](https://docs.aws.amazon.com/vpc/latest/APIReference/API_CreateVpc.html).
29+
30+
Run the following command:
31+
32+
```bash title="Create VPC"
33+
awslocal ec2 create-vpc --cidr-block 10.0.0.0/16
34+
```
35+
36+
```bash title="Output"
37+
{
38+
"Vpc": {
39+
...
40+
"CidrBlock": "10.0.0.0/16",
41+
"VpcId": "<vpc-id>",
42+
...
43+
}
44+
}
45+
```
46+
47+
Next, we need to create a subnet in the VPC. You can create a 2 subnets using the [`CreateSubnet` API](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateSubnet.html). Some extra tags might be required for specific Controllers to work properly. Please refer to their specific documentation for more details.
48+
49+
Run the following command:
50+
51+
```bash title="Create Subnet 1"
52+
awslocal ec2 create-subnet \
53+
--vpc-id <vpc-id> \
54+
--cidr-block 10.0.1.0/24 \
55+
--availability-zone us-east-1a
56+
```
57+
58+
```bash title="Output"
59+
{
60+
"Subnet": {
61+
...
62+
"SubnetId": "<subnet-id-1>",
63+
"VpcId": "<vpc-id>",
64+
"CidrBlock": "10.0.1.0/24"
65+
...
66+
}
67+
}
68+
```
69+
70+
```bash title="Create Subnet 2"
71+
awslocal ec2 create-subnet \
72+
--vpc-id <vpc-id> \
73+
--cidr-block 10.0.2.0/24 \
74+
--availability-zone us-east-1b
75+
```
76+
77+
```bash title="Output"
78+
{
79+
"Subnet": {
80+
...
81+
"SubnetId": "<subnet-id-2>",
82+
"VpcId": "<vpc-id>",
83+
"CidrBlock": "10.0.2.0/24"
84+
...
85+
}
86+
}
87+
```
88+
2689
### Create an embedded Kubernetes cluster
2790

2891
The default approach for creating Kubernetes clusters using the local EKS API is by setting up an embedded [k3d](https://k3d.io/) kube cluster within Docker.
@@ -38,14 +101,15 @@ EKS_START_K3D_LB_INGRESS=1
38101
```
39102
:::
40103

41-
You can create a new cluster using the [`CreateCluster`](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateCluster.html) API.
104+
You can create a new cluster using the [`CreateCluster` API](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateCluster.html).
105+
42106
Run the following command:
43107

44-
```bash
108+
```bash title="Create Cluster"
45109
awslocal eks create-cluster \
46110
--name cluster1 \
47111
--role-arn "arn:aws:iam::000000000000:role/eks-role" \
48-
--resources-vpc-config "{}"
112+
--resources-vpc-config '{"subnetIds":["<subnet-id-1>", "<subnet-id-2>"]}'
49113
```
50114

51115
```bash title="Output"
@@ -55,7 +119,12 @@ awslocal eks create-cluster \
55119
"arn": "arn:aws:eks:us-east-1:000000000000:cluster/cluster1",
56120
"createdAt": "2022-04-13T16:38:24.850000+02:00",
57121
"roleArn": "arn:aws:iam::000000000000:role/eks-role",
58-
"resourcesVpcConfig": {},
122+
"resourcesVpcConfig": {
123+
"subnetIds": [
124+
"<subnet-id-1>",
125+
"<subnet-id-2>"
126+
]
127+
},
59128
"identity": {
60129
"oidc": {
61130
"issuer": "https://localhost.localstack.cloud/eks-oidc"
@@ -67,6 +136,14 @@ awslocal eks create-cluster \
67136
}
68137
```
69138

139+
The cluster creation process may take a few moments as LocalStack sets up the necessary components. Avoid attempting to access the cluster until the status changes to `ACTIVE`.
140+
141+
Run the following command to wait for the cluster status to become `ACTIVE`:
142+
143+
```bash title="Wait for Cluster"
144+
awslocal eks wait cluster-active --name cluster1
145+
```
146+
70147
:::note
71148
When setting up a local EKS cluster, if you encounter a `"status": "FAILED"` in the command output and see `Unable to start EKS cluster` in LocalStack logs, remove or rename the `~/.kube/config` file on your machine and retry.
72149
The CLI mounts this file automatically for CLI versions before `3.7`, leading EKS to assume you intend to use the specified cluster, a feature that has specific requirements.
@@ -86,36 +163,63 @@ f05770ec8523 rancher/k3s:v1.21.5-k3s2 "/bin/k3s server --t…" 1 minut
86163
...
87164
```
88165

89-
After successfully creating and initializing the cluster, we can easily find the server endpoint, using the [`DescribeCluster`](https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeCluster.html) API.
166+
### Creating a managed node group
167+
168+
The EKS cluster created in the previous step does not include any worker nodes by default. While you can inspect the server node, it is [tainted](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/), and workloads cannot be scheduled on it. To run workloads on the cluster, you must add at least one worker node. One way to do this is by creating a managed node group. When you create a managed node group, LocalStack automatically provisions a Docker container, joins it to the cluster, and provisions a mocked EC2 instance.
169+
170+
You can create a managed node group for your EKS cluster using the [`CreateNodegroup` API](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateNodegroup.html).
171+
90172
Run the following command:
91173

92-
```bash
93-
awslocal eks describe-cluster --name cluster1
174+
```bash title="Create Node Group"
175+
awslocal eks create-nodegroup \
176+
--cluster-name cluster1 \
177+
--nodegroup-name nodegroup1 \
178+
--node-role arn:aws:iam::000000000000:role/eks-nodegroup-role \
179+
--subnets <subnet-id-1> <subnet-id-2> \
180+
--scaling-config desiredSize=1
94181
```
95182

96183
```bash title="Output"
97184
{
98-
"cluster": {
99-
"name": "cluster1",
100-
"arn": "arn:aws:eks:us-east-1:000000000000:cluster/cluster1",
101-
"createdAt": "2022-04-13T17:12:39.738000+02:00",
102-
"endpoint": "https://localhost.localstack.cloud:4511",
103-
"roleArn": "arn:aws:iam::000000000000:role/eks-role",
104-
"resourcesVpcConfig": {},
105-
"identity": {
106-
"oidc": {
107-
"issuer": "https://localhost.localstack.cloud/eks-oidc"
108-
}
185+
"nodegroup": {
186+
"nodegroupName": "nodegroup1",
187+
"nodegroupArn": "arn:aws:eks:us-east-1:000000000000:nodegroup/cluster1/nodegroup1/xxx",
188+
"clusterName": "cluster1",
189+
"version": "1.21",
190+
"releaseVersion": "1.21.7-20220114",
191+
"createdAt": "2022-04-13T17:25:45.821000+02:00",
192+
"status": "CREATING",
193+
"capacityType": "ON_DEMAND",
194+
"scalingConfig": {
195+
"desiredSize": 1
109196
},
110-
"status": "ACTIVE",
111-
"certificateAuthority": {
112-
"data": "..."
197+
"subnets": [
198+
"<subnet-id-1>",
199+
"<subnet-id-2>"
200+
],
201+
"nodeRole": "arn:aws:iam::000000000000:role/eks-nodegroup-role",
202+
"labels": {},
203+
"health": {
204+
"issues": []
113205
},
114-
"clientRequestToken": "d188f578-b353-416b-b309-5d8c76ecc4e2"
206+
"updateConfig": {
207+
"maxUnavailable": 1
208+
}
115209
}
116210
}
117211
```
118212

213+
The node group creation process may take a few moments as LocalStack sets up the necessary components.
214+
215+
You can wait for the node group status to become `ACTIVE` by running the following command:
216+
217+
```bash title="Wait for Node Group"
218+
awslocal eks wait nodegroup-active --cluster-name cluster1 --nodegroup-name nodegroup1
219+
```
220+
221+
At this point, your EKS cluster is fully operational and ready to deploy workloads.
222+
119223
### Utilizing ECR Images within EKS
120224

121225
You can now use ECR (Elastic Container Registry) images within your EKS environment.
@@ -141,7 +245,7 @@ Once you have configured this correctly, you can seamlessly use your ECR image w
141245
To showcase this behavior, let's go through a concise step-by-step guide that will lead us to the successful pulling of an image from local ECR.
142246
For the purpose of this guide, we will retag the `nginx` image to be pushed to a local ECR repository under a different name, and then utilize it for a pod configuration.
143247

144-
You can create a new ECR repository using the [`CreateRepository`](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_CreateRepository.html) API.
248+
You can create a new ECR repository using the [`CreateRepository` API](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_CreateRepository.html).
145249
Run the following command:
146250

147251
```bash
@@ -187,7 +291,7 @@ docker push 000000000000.dkr.ecr.us-east-1.localhost.localstack.cloud:4566/fanci
187291

188292
Now, let us set up the EKS cluster using the image pushed to local ECR.
189293

190-
Next, we can configure `kubectl` to use the EKS cluster, using the [`UpdateKubeconfig`](https://docs.aws.amazon.com/eks/latest/APIReference/API_UpdateClusterConfig.html) API.
294+
Next, we can configure `kubectl` to use the EKS cluster, using the [`UpdateKubeconfig` API](https://docs.aws.amazon.com/eks/latest/APIReference/API_UpdateClusterConfig.html).
191295
Run the following command:
192296

193297
```bash

0 commit comments

Comments
 (0)