Skip to main content
Version: 1.42

Amazon Elastic Kubernetes Service (EKS)

This guide will walk you through the process of installing Okteto in Amazon Elastic Kubernetes Service (EKS).

Installation Requirements​

Install these CLIs on your machine:

You also need:

  • An Okteto license
  • A domain where you can create wildcard DNS records
  • A Kubernetes cluster

Getting your Okteto License​

You need a license to install Okteto. If you have an Okteto subscription, your license key came with it, and support can send it again if you can't find it. If you don't have a subscription yet, sign up for the free tier: you get a one-year license for up to 5 users and 500 environments per month, and you don't need a credit card.

A Domain and the ability to create wildcard DNS records for it​

You need enough access to a subdomain, such as dev.example.com, to add a wildcard DNS record to it. By default, Okteto exposes the endpoints of your application environments on that subdomain.

This guide uses Amazon Route 53 for the DNS records, but any DNS service works.

Deploy a Kubernetes cluster​

This guide assumes Okteto runs in a new, dedicated cluster.

note

To install Okteto in an existing cluster with other workloads, read this section to check that your cluster meets the requirements.

warning

As of Okteto 1.35, Okteto supports Amazon Linux 2 (AL2) and introduces support for Amazon Linux 2023 (AL2023) as the AMI for cluster nodes. We recommend upgrading Okteto to version 1.35 before upgrading your EKS cluster to Kubernetes 1.33 or changing to AL2023. In mixed clusters, make sure both the control plane and development workloads run on nodes with Amazon Linux 2 or Amazon Linux 2023 using taints and tolerations.

Bottlerocket OS is not supported. Okteto requires write access to /etc/hosts on cluster nodes, which is not possible on Bottlerocket's read-only root filesystem. If you use Bottlerocket, switch to AL2023. Troubleshooting has more details.

Setting up environment variables​

Set these environment variables to script the cluster creation:

Your Kubernetes cluster version:

export K8S_VERSION="1.34"
note

Okteto supports Kubernetes versions 1.32 through 1.34.

Your Kubernetes cluster name:

export CLUSTER_NAME="okteto"

Your AWS Account ID:

export AWS_ACCOUNT_ID="$(aws sts get-caller-identity --query "Account" --output text)"

Your AWS Region:

export AWS_REGION="$(aws configure get region)"

Disable AWS CLI pagination (optional):

export AWS_PAGER=""

Create the Cluster​

For an initial evaluation, we recommend a Kubernetes cluster with a pool of 3 m5.xlarge nodes with 250 GB each:

eksctl create cluster -f - <<EOF
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
name: ${CLUSTER_NAME}
region: ${AWS_REGION}
version: "${K8S_VERSION}"

autoModeConfig:
enabled: false

iam:
withOIDC: true

nodeGroups:
- name: ng-1
instanceType: m5.xlarge
desiredCapacity: 3
volumeSize: 250
volumeType: gp3
amiFamily: AmazonLinux2023
EOF
note

Check that the Kubernetes version you select is supported:

  • By your eksctl installation. To list the versions it supports, run:
    eksctl create cluster -h | grep 'Kubernetes version'
  • By Amazon EKS, in its list of available versions.
  • By the Okteto Helm chart version you plan to install, in its supported Kubernetes versions.

Amazon's cluster creation guide has more details.

Create EBS CSI Addon IAM Role​

Okteto needs the EBS CSI Addon to create persistent volumes. It uses them for the cache of the Okteto Build Service (BuildKit) and, in the default installation, to store your container images in the Okteto Registry.

Before you install the EBS CSI Addon in your Kubernetes cluster, create its IAM Role:

eksctl create iamserviceaccount \
--region="${AWS_REGION}" \
--name="ebs-csi-controller-sa" \
--namespace="kube-system" \
--cluster="${CLUSTER_NAME}" \
--role-name="${CLUSTER_NAME}-ebs-csi-driver-role" \
--role-only \
--attach-policy-arn="arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy" \
--approve

The AWS documentation has more details.

Deploy EBS CSI Addon​

With the IAM Role created, deploy the EBS CSI Addon:

eksctl create addon \
--region="${AWS_REGION}" \
--name="aws-ebs-csi-driver" \
--cluster="${CLUSTER_NAME}" \
--service-account-role-arn="arn:aws:iam::${AWS_ACCOUNT_ID}:role/${CLUSTER_NAME}-ebs-csi-driver-role" \
--force

The AWS documentation has more details.

Create a Storage Class for the EBS CSI Addon​

Create a Storage Class for the EBS CSI Addon:

cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: ebs-sc
annotations:
storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
EOF

The EBS CSI driver documentation describes the Storage Class parameters.

Create Load Balancer Controller IAM Role​

Okteto recommends installing the Load Balancer Controller to manage the Okteto certificates with Amazon Certificate Manager. The AWS documentation for the Load Balancer Controller has more details.

Before you install the Load Balancer Controller in your Kubernetes cluster, download its IAM Policy manifest:

curl \
-s \
-o iam-policy.json \
https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v3.1.0/docs/install/iam_policy.json
note

The maintainers of kubernetes-sigs/aws-load-balancer-controller recommend scoping this policy down by the VPC ID or by the cluster name resource tag. Their installation docs explain how.

Create the IAM Policy for the Load Balancer Controller IAM Role:

aws iam create-policy \
--policy-name="${CLUSTER_NAME}-load-balancer-controller-policy" \
--policy-document file://iam-policy.json

Create the IAM Role for the Load Balancer Controller:

eksctl create iamserviceaccount \
--region="${AWS_REGION}" \
--name="aws-load-balancer-controller" \
--namespace="kube-system" \
--cluster="${CLUSTER_NAME}" \
--role-name="${CLUSTER_NAME}-aws-load-balancer-controller-role" \
--attach-policy-arn="arn:aws:iam::${AWS_ACCOUNT_ID}:policy/${CLUSTER_NAME}-load-balancer-controller-policy" \
--approve

Deploy Load Balancer Controller​

With the IAM Role created, deploy the Load Balancer Controller.

Add the EKS Helm chart repository:

helm repo add eks https://aws.github.io/eks-charts
helm repo update

Install the Load Balancer Controller chart:

helm upgrade --install \
aws-load-balancer-controller \
eks/aws-load-balancer-controller \
--version="3.1.0" \
--namespace="kube-system" \
--set clusterName=${CLUSTER_NAME} \
--set serviceAccount.create=false \
--set serviceAccount.name=aws-load-balancer-controller

Installing Okteto​

note

Argo CD installs the same Helm chart declaratively. See Configure Argo CD for the Application manifest, sync policy, and the ignoreDifferences Okteto requires. It replaces Add the Okteto Helm repository and Installing the Okteto Helm chart. Every other step on this page still applies, including the DNS record and the sign-in.

You install Okteto with its Helm chart.

Add the Okteto Helm repository​

Add the Okteto Helm repository:

helm repo add okteto https://charts.okteto.com
helm repo update

Create the Helm configuration file​

Create a config.yaml file with these settings, replacing license and subdomain with your own values:

config.yaml
license: "REPLACE ME WITH YOUR OKTETO LICENSE"
subdomain: "REPLACE ME WITH YOUR OKTETO DOMAIN"

ingress-nginx:
controller:
service:
annotations:
service.beta.kubernetes.io/aws-load-balancer-type: nlb
service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"

registry:
storage:
filesystem:
persistence:
enabled: true

This is the minimum configuration. The Helm configuration lists every setting.

The service.beta.kubernetes.io/aws-load-balancer-type: nlb annotation tells AWS to expose the ingress controller with a Network Load Balancer (NLB) instead of the default Classic Load Balancer. We recommend an NLB because it supports WebSockets and static IPs, and it performs better. You can see a full comparison between the load balancers here.

Installing the Okteto Helm chart​

Install the Okteto Helm chart:

helm upgrade --install okteto okteto/okteto -f config.yaml --namespace=okteto --create-namespace --version=1.42.0

After a few seconds, Helm creates all the resources. The output looks like this:

Release "okteto" has been installed. Happy Helming!
NAME: okteto
LAST DEPLOYED: Thu Mar 26 18:07:55 2020
NAMESPACE: okteto
STATUS: deployed

Retrieve the Ingress Controller IP address​

Use kubectl to get the address that EKS allocated to the NGINX ingress controller that Okteto installs:

kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto

The output looks like this:

NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
okteto-ingress-nginx-controller LoadBalancer 10.0.7.73 a519c8b3b27f94...elb.amazonaws.com 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m

Add the EXTERNAL-IP address (a519c8b3b27f94...elb.amazonaws.com in the example) to the DNS of your domain. In Route 53, create an A record with the name * that points to the alias of the Elastic Load Balancer.

Sign in to your Okteto instance​

warning

The default installation isn't meant for production. Once you finish your evaluation, and before you give your team access to your Okteto instance, configure a wildcard AWS ACM certificate and Okteto Registry storage with S3.

Once the installation finishes, your Okteto instance is available at https://okteto.SUBDOMAIN. Okteto creates your account the first time you log in, and the first user to log in gets the Admin role.

Optional: Configure access to your Amazon ECR​

You can give Okteto access to your Amazon Elastic Container Registry. Your Dockerfiles and your deployments can then use its private images without pull secrets.

Deploy your first app​

With your Okteto instance running, install the Okteto CLI and configure it with the URL of your instance, https://okteto.SUBDOMAIN. Then deploy your first app.