Amazon Elastic Kubernetes Service (EKS)

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

Installation Requirements

Before you start, make sure you have the following CLIs installed in your machine:

• eksctl >= 0.171 (eksctl installation guides)
• aws >= 2.15 (aws installation guides)
• kubectl >= 1.28 (kubectl installation guides)
• helm >= 3.14 (helm installation guides)

You'll also need the following:

• An Okteto License
• A Domain and the ability to create wildcard DNS records for it
• A Kubernetes cluster

Getting your Okteto License

A license is mandatory to use Okteto. You'll receive a license key as part of your subscription to Okteto. If you haven't received it, please open a support ticket.

If you are interested in evaluating Okteto, sign up for our free 30 days trial. No credit card required.

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

You'll need sufficient access to a subdomain to add a wildcard DNS record, such as dev.example.com. By default, all endpoints created by Okteto for your development environments will be exposed on the wildcard subdomain you choose.

This guide assumes your domain is registered in Amazon Route53 service. You can use any DNS service you prefer, but this guide focuses specifically on Amazon Route53.

Deploy a Kubernetes cluster

Our installation guides assume Okteto will be running in a new dedicated cluster.

note

If you plan on installing Okteto in an existing cluster with other workloads, we recommend to read this section to make sure your cluster satisfies the requirements to install Okteto

Setting up environment variables

We recommend configuring the following environment variables to help you scripting the cluster creation:

Your Kubernetes cluster version:

export K8S_VERSION="1.30"

note

Okteto supports Kubernetes versions 1.27 through 1.30.

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 initial evaluation, we recommend a Kubernetes cluster with a pool of 3 m5.xlarge nodes with 250 GB each:

eksctl create cluster \
  --region="${AWS_REGION}" \
  --name="${CLUSTER_NAME}" \
  --with-oidc \
  --version="${K8S_VERSION}" \
  --nodes=3 \
  --node-type="m5.xlarge" \
  --node-volume-size="250" \
  --node-volume-type="gp3" \
  --node-ami-family="AmazonLinux2"

note

Ensure the Kubernetes version you select meets the following requirements:

• Supported versions for your eksctl installation can be checked using the command:

  eksctl create cluster -h | grep 'Kubernetes version'
• Check the available versions for AWS EKS service.
• Verify the supported K8s versions for the Okteto Helm chart version you plan to install.

Follow Amazon's cluster creation guide for more details.

Create EBS CSI Addon IAM Role

Okteto requires the EBS CSI Addon to be able to create persistent volumes. Okteto uses persistent volumes to persist the cache of the Okteto Build service (buildkit). The default installation also uses persistent volumes to store your container images in the Okteto Registry.

To install the EBS CSI Addon in your Kubernetes cluster, you need to create the EBS CSI Addon's IAM Role first:

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

Refer to the AWS official documentation for more details.

Deploy EBS CSI Addon

Once you have the EBS CSI IAM Role created, deploy the EBS CSI Addon with the following command:

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

Refer to the AWS official documentation for 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

For more information about the EBS CSI Storage Class parameters, refer to the AWS official documentation.

Create Load Balancer Controller IAM Role

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

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

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

note

kubernetes-sigs/aws-load-balancer-controller maintainers recommends further scoping down this configuration based on the VPC ID or the Cluster Name resource tag. Checkout their docs for official instructions on it.

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

Once you have the Load Balancer Controller IAM Role created, let's deploy the Load Balancer Controller.

First, 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="1.7.1" \
  --namespace="kube-system" \
  --set clusterName=${CLUSTER_NAME} \
  --set serviceAccount.create=false \
  --set serviceAccount.name=aws-load-balancer-controller

Installing Okteto

Okteto is installed using a Helm chart. Let's start the process:

Add the Okteto Helm repository

You'll need to add the Okteto Helm repository to be able to install Okteto:

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

Create the Helm configuration file

In order to install Okteto you need to first create a config.yaml for the installation process. Replace license and subdomain with your own values, and initialize your Helm configuration file with these settings:

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"

buildkit:
  persistence:
    enabled: true

registry:
  storage:
    filesystem:
      persistence:
        enabled: true

Note: This is the minimum configuration. Check our Helm configuration docs to learn more

The service.beta.kubernetes.io/aws-load-balancer-type: nlb annotation is used to tell AWS to create a Network Load Balancer (NLB) instead of the default Classic Load Balancer to expose the ingress controller. We recommend to use a NLB as it provides benefits like: websocket support, static IPs, and better performance. You can see a full comparison between the load balancers here.

Installing the Okteto Helm chart

Install the latest version of Okteto by running:

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

After a few seconds, all the resources will be created. The output will look something 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

You can use kubectl to fetch the address that has been dynamically allocated by EKS to the NGINX Ingress we've just installed and configured as a part of Okteto:

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

The output will look something 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

You'll need to take the EXTERNAL-IP address (a519c8b3b27f94...elb.amazonaws.com in the example), and add it to your DNS for the domain you have chosen to use. In Route 53, this is done by creating an A record with the name *, pointing to the alias of the Elastic Load Balancer.

Sign in to your Okteto instance

warning

Important: The default installation is not recommended for production use. We highly advise configuring a wildcard AWS ACM certificate and Okteto Registry storage with S3 after finishing your evaluation and giving your team access to your Okteto instance.

After a successful installation, you can access your Okteto instance at https://okteto.SUBDOMAIN. Your account will be automatically created as part of the login process. The first user to successfully login into the instance will be automatically assigned the administrator role.

Configure the Okteto CLI

The first thing you need to do before using the Okteto CLI is to set the Okteto CLI context with your Okteto instance. To do this, run the command below replacing SUBDOMAIN:

okteto context use `https://okteto.SUBDOMAIN`

Once your Okteto instance is up and running and your Okteto CLI properly configured, you are going to deploy your first app to Okteto 😎

Optional: Configure access to your Amazon ECR

Optionally, you can configure Okteto to have access to your Amazon Elastic Container Registry. This will allow you to use your private images in your Dockerfiles and avoid using pull secrets everywhere to deploy your applications.