Skip to main content
Version: 0.13

Azure Kubernetes Service (AKS)

This guide will show you how to install Okteto onto Azure Kubernetes Service (AKS). We'll be focusing exclusively on AKS in order to keep it as simple as possible.

Requirements​

In order to fully install Okteto, you'll need the following:

  • A subdomain to which you can add a wildcard DNS record
  • A Kubernetes cluster
  • A working installation of kubectl
  • A working installation of Helm v3
  • A GitHub OAuth application
  • An Azure Storage Container
  • An Azure Service Principal with read/write access to AzureDNS
  • An Okteto license (optional)

Subdomain​

You'll need access to an internet accessible subdomain to which you can add a wildcard DNS record, such as dev.example.com. Let's Encrypt servers must be able to resolve the addresses in order to issue the required certificates.

This guide will assume that your domain is registered in AzureDNS. Other DNS services can be used, but aren't covered here.

Deploy a Kubernetes cluster​

We recommend that you follow Azure's cluster creation guide.

We recommend the following specs:

  • v1.19 or newer
  • A pool with at least 3 Standard D4 nodes
  • 100 GB per Standard SSD Managed Disk

You'll be using the cluster's API server endpoint when configuring Okteto

Installing kubectl​

Follow Azure's documentation for installing kubectl. Once installed, configure kubectl to talk to your new cluster.

Installing Helm v3​

Follow the official documentation for installing the latest release of Helm v3.

Creating the GitHub OAuth application​

Okteto supports OAuth providers like Google, GitHub, or OpenID Connect to handle user authentication. For this guide, we'll focus on using GitHub. All the supported configuration settings are described here.

Follow GitHub's official documentation on how to create an OAuth App.

When creating the OAuth App, you will need to provide the following values:

Homepage URL:

https://okteto.DOMAIN

Authorization callback URL:

https://okteto.DOMAIN/auth/callback

You'll use the Client ID and Client Secret when installing Okteto.

Creating an Azure Storage Container​

Okteto uses a storage container to store your private images. Follow Azure's guide on how to create a storage container. Create the bucket in the region as your AKS cluster, and keep it private.

You'll need the Account Name and a Storage Account Key when installing Okteto.

Creating an Azure Service Principal​

The Okteto sub-components need access to AzureDNS to fulfill the ACME challenge when generating certificates.

We recommend you follow cert-manager's documentation on this topic.

You'll need the following values from the Service Principal when installing Okteto:

  • AppID
  • Password
  • Tenant ID
  • Subscription ID

Adding the Okteto Helm repository​

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

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

Getting your Okteto License​

Okteto is free for small teams. You get all the features of Okteto for up to 3 users with 3 namespaces each.

Want to use Okteto with a bigger team? Let's talk

Installing Okteto​

Creating the Okteto namespace​

Create a dedicated namespace for your Okteto instance, and the required CRDs:

$ kubectl apply -f https://charts.okteto.com/namespace.yaml
$ kubectl apply -f https://charts.okteto.com/crds.yaml

Configuring your Okteto instance​

Create a Kubernetes secret with the Service Principal's Password you created before:

kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=STORAGE_ACCOUNT_ACCESS_KEY --from-literal=token=SERVICE_PRINCIPAL_PASSWORD

Download a copy of the Okteto AKS configuration file, open it, and update the following values:

  • Your email
  • Your license (optional)
  • A subdomain
  • clientId and clientSecret of the OAuth Application you created
  • Your cluster's API server endpoint
  • The AppID of the Service Principal
  • The Tenant ID of the Service Principal
  • The Subscription ID of the Service Principal
  • The name of the storage container you created
  • The Storage Account Name

For example:

email: admin@example.com
license: 1234567890ABCD==
subdomain: dev.example.com
cluster:
  endpoint: "https://XXXXXX.aks.microsoft.com"

auth:
  github:
    enabled: true
    clientId: ae8924d074d8c8809999
    clientSecret: ABCD90598b706d5342f07cce18fee5e5da391234

cloud:
  provider:
    azure:
      enabled: true
      servicePrincipal: "b2f3a941-1853-44fc-8600-88d6a061305e"
      subscriptionID: "6e459427-98be-414d-8476-1e0328626abf"
      tenantID: "c9ef58ed-1920-4dc8-8a24-98904464d3d8"
      resourceGroupName: "okteto-enterprise-resource-group"
      storage:
        container: "okteto-container"
        accountName: "okteto-storage-account"

buildkit:
  ingress:
    enabled: false
  service:
    type: LoadBalancer

Installing your Okteto instance​

Install the latest version of Okteto by running:

helm install okteto okteto/okteto-enterprise -f config.yaml --namespace=okteto

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
REVISION: 1
TEST SUITE: None
NOTES:
1. Create the following DNS record, pointing it to the NGINX controller service External-IP:
- "*.dev.example.com"

You can retrieve the External IP by running:
    kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto

2. Create the following DNS record, pointing it to the Buildkit service External-IP:
- "buildkit.dev.example.com"

You can retrieve the External IP by running:
    kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto

3. Once you create both DNS entries you can access your Okteto instance at this URL:
https://okteto.dev.example.com

You can also install a specific version by including the --version argument.

Retrieve the Ingress Controller IP address​

We can use the instructions kubectl to fetch the address that has been dynamically allocated by AKS 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...aks.microsoft.com   80:30795/TCP,443:32481/TCP,1234:30885/TCP   5m

You'll need to take the EXTERNAL-IP address and add it to your DNS for the domain you have chosen to use. In AzureDNS, this is done by creating an A record with the name *, pointing to the IP of the Load Balancer.

Retrieve the Buildkit IP address​

You can use kubectl to fetch the address that has been dynamically allocated by AKS to the Buildkit instance you've just installed and configured as a part of Okteto:

kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto

The output will look something like this:

NAME                                  TYPE           CLUSTER-IP      EXTERNAL-IP                           PORT(S)          AGE
okteto-okteto-enterprise-buildkit     LoadBalancer   10.245.142.73   a519c8b3b27f95...aks.microsoft.com    1234:32449/TCP   5m

You'll need to take the EXTERNAL-IP address, and add it to your DNS for the domain you have chosen to use. This is done by creating an A record with the name buildkit.

Sign in to your Okteto​

You can access your Okteto instance at https://okteto.SUBDOMAIN. Your account will be automatically created as you soon as you click the Login button.

Troubleshooting​

If you experience issues during this guide, we recommend you check these things first:

  1. okteto.SUBDOMAIN resolves to the IP address you retrieved.
  2. If you get a certificate warning, there has been a problem with Let's Encrypt. This is usually related to DNS resolution, the need to retry, or the permissions of the credentials created.

For further troubleshooting tips, see our troubleshooting guide.