diff --git a/src/content/docs/aws/services/eks.mdx b/src/content/docs/aws/services/eks.mdx index f275eb64..c238105b 100644 --- a/src/content/docs/aws/services/eks.mdx +++ b/src/content/docs/aws/services/eks.mdx @@ -23,6 +23,69 @@ To interact with the Kubernetes cluster, you should also install [`kubectl`](htt Start your LocalStack container using your preferred method. We will demonstrate how you can auto-install an embedded Kubernetes cluster, configure ingress, and deploy a sample service with ECR. +### Deploy the necessary networking components + +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). + +Run the following command: + +```bash title="Create VPC" +awslocal ec2 create-vpc --cidr-block 10.0.0.0/16 +``` + +```bash title="Output" +{ + "Vpc": { + ... + "CidrBlock": "10.0.0.0/16", + "VpcId": "", + ... + } +} +``` + +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. + +Run the following command: + +```bash title="Create Subnet 1" +awslocal ec2 create-subnet \ + --vpc-id \ + --cidr-block 10.0.1.0/24 \ + --availability-zone us-east-1a +``` + +```bash title="Output" +{ + "Subnet": { + ... + "SubnetId": "", + "VpcId": "", + "CidrBlock": "10.0.1.0/24" + ... + } +} +``` + +```bash title="Create Subnet 2" +awslocal ec2 create-subnet \ + --vpc-id \ + --cidr-block 10.0.2.0/24 \ + --availability-zone us-east-1b +``` + +```bash title="Output" +{ + "Subnet": { + ... + "SubnetId": "", + "VpcId": "", + "CidrBlock": "10.0.2.0/24" + ... + } +} +``` + ### Create an embedded Kubernetes cluster 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 ``` ::: -You can create a new cluster using the [`CreateCluster`](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateCluster.html) API. +You can create a new cluster using the [`CreateCluster` API](https://docs.aws.amazon.com/eks/latest/APIReference/API_CreateCluster.html). + Run the following command: -```bash +```bash title="Create Cluster" awslocal eks create-cluster \ --name cluster1 \ --role-arn "arn:aws:iam::000000000000:role/eks-role" \ - --resources-vpc-config "{}" + --resources-vpc-config '{"subnetIds":["", ""]}' ``` ```bash title="Output" @@ -55,7 +119,12 @@ awslocal eks create-cluster \ "arn": "arn:aws:eks:us-east-1:000000000000:cluster/cluster1", "createdAt": "2022-04-13T16:38:24.850000+02:00", "roleArn": "arn:aws:iam::000000000000:role/eks-role", - "resourcesVpcConfig": {}, + "resourcesVpcConfig": { + "subnetIds": [ + "", + "" + ] + }, "identity": { "oidc": { "issuer": "https://localhost.localstack.cloud/eks-oidc" @@ -67,6 +136,14 @@ awslocal eks create-cluster \ } ``` +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`. + +Run the following command to wait for the cluster status to become `ACTIVE`: + +```bash title="Wait for Cluster" +awslocal eks wait cluster-active --name cluster1 +``` + :::note 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. 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 ... ``` -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. +### Creating a managed node group + +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. + +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). + Run the following command: -```bash -awslocal eks describe-cluster --name cluster1 +```bash title="Create Node Group" +awslocal eks create-nodegroup \ + --cluster-name cluster1 \ + --nodegroup-name nodegroup1 \ + --node-role arn:aws:iam::000000000000:role/eks-nodegroup-role \ + --subnets \ + --scaling-config desiredSize=1 ``` ```bash title="Output" { - "cluster": { - "name": "cluster1", - "arn": "arn:aws:eks:us-east-1:000000000000:cluster/cluster1", - "createdAt": "2022-04-13T17:12:39.738000+02:00", - "endpoint": "https://localhost.localstack.cloud:4511", - "roleArn": "arn:aws:iam::000000000000:role/eks-role", - "resourcesVpcConfig": {}, - "identity": { - "oidc": { - "issuer": "https://localhost.localstack.cloud/eks-oidc" - } + "nodegroup": { + "nodegroupName": "nodegroup1", + "nodegroupArn": "arn:aws:eks:us-east-1:000000000000:nodegroup/cluster1/nodegroup1/xxx", + "clusterName": "cluster1", + "version": "1.21", + "releaseVersion": "1.21.7-20220114", + "createdAt": "2022-04-13T17:25:45.821000+02:00", + "status": "CREATING", + "capacityType": "ON_DEMAND", + "scalingConfig": { + "desiredSize": 1 }, - "status": "ACTIVE", - "certificateAuthority": { - "data": "..." + "subnets": [ + "", + "" + ], + "nodeRole": "arn:aws:iam::000000000000:role/eks-nodegroup-role", + "labels": {}, + "health": { + "issues": [] }, - "clientRequestToken": "d188f578-b353-416b-b309-5d8c76ecc4e2" + "updateConfig": { + "maxUnavailable": 1 + } } } ``` +The node group creation process may take a few moments as LocalStack sets up the necessary components. + +You can wait for the node group status to become `ACTIVE` by running the following command: + +```bash title="Wait for Node Group" +awslocal eks wait nodegroup-active --cluster-name cluster1 --nodegroup-name nodegroup1 +``` + +At this point, your EKS cluster is fully operational and ready to deploy workloads. + ### Utilizing ECR Images within EKS 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 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. 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. -You can create a new ECR repository using the [`CreateRepository`](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_CreateRepository.html) API. +You can create a new ECR repository using the [`CreateRepository` API](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_CreateRepository.html). Run the following command: ```bash @@ -187,7 +291,7 @@ docker push 000000000000.dkr.ecr.us-east-1.localhost.localstack.cloud:4566/fanci Now, let us set up the EKS cluster using the image pushed to local ECR. -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. +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). Run the following command: ```bash