DigitalOcean Kubernetes (DOKS)

This guide will show you how to install Okteto onto DigitalOcean Kubernetes. We'll be focusing exclusively on DigitalOcean Kubernetes 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 GitLab OAuth application
• A DigitalOcean personal access token
• A DigitalOcean space and access key
• An Okteto License (optional)

Subdomain

You'll need to have access to a 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 DigitalOcean. Other DNS services can be used, but aren't covered here.

In the rest of this guide, we will refer to this subdomain as DOMAIN.

Deploy a Kubernetes cluster

If you are not familiar with this step, we recommend that you follow DigitalOcean's cluster creation guide.

To get started with Okteto, follow these specs:

• v1.19 or newer
• A pool with at least 2 nodes (4CPUs and 16GBs each) without autoscalability
• 100 GB per disk

Installing kubectl

Follow the official 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 GitLab OAuth application

Okteto supports OAuth providers like Google, Bitbucket, GitHub, or OpenID Connect to handle user authentication. All the supported configuration settings are described here.

For this guide, we will focus on using GitLab OpenID Connect.

Follow GitLab's official documentation on how to create an OAuth Client.

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

Redirect URIs:

https://okteto.DOMAIN
https://okteto.DOMAIN/auth/callback

Scopes:

openid
profile
email

You'll use the Application ID and Secret of your OAuth Application when installing Okteto.

Creating a Digital Ocean Personal Access Token

Okteto requires a DigitalOcean personal access token with read/write permissions to be able to create DNS entries when responding to ACME DNS-01 challenges. The entries will be created in the subdomain you provided in the configuration. You can create your personal access token by going here.

Creating a DigitalOcean Space and Access Key

Okteto uses DigitalOcean spaces to store your private images. Follow DigitalOcean's guide on how to create a space and api key. Create the space in the same region as your Kubernetes cluster and restrict file listing.

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 DigitalOcean personal token ($TOKEN) and the space access key secret ($SECRET) you created before:

$ kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=token=$TOKEN --from-literal=key=$SECRET

Using these values:

• Your email: $EMAIL
• Your license (optional): $LICENSE
• Your subdomain: $SUBDOMAIN
• You Kubernetes cluster endpoint: $KUBERNETES_ENDPOINT. You can get it from the server field of your cluster kubeconfig file
• The URL of your GitLab instance: $GITLAB_URL. Use https://gitlab.com if your are using GitLab SaaS
• Application ID: $OAUTH_APPLICATION_ID and Secret: $OAUTH_APPLICATION_SECRET of the OAuth 2.0 Client you created
• The ID of the DigitalOcean region of your Kubernetes cluster: $REGION
• Your space name: $SPACE_NAME and access key ID : $SPACE_ACCESS_KEY_ID

create the following config.yml file to configure the Okteto Helm chart:

email: "$EMAIL"
license: "$LICENSE"
subdomain: "$SUBDOMAIN"

cluster:
  endpoint: "$KUBERNETES_ENDPOINT"

auth:
  openid:
    enabled: true
    endpoints:
       issuer: "$GITLAB_URL"
       authorization: "$GITLAB_URL/oauth/authorize"
    clientId: "$OAUTH_APPLICATION_ID"
    clientSecret: "$OAUTH_APPLICATION_SECRET"

cloud:
  provider:
    digitalocean:
      enabled: true
      region: "$REGION"
      space:
        name: "$SPACE_NAME"
        accessKeyID: "$SPACE_ACCESS_KEY_ID"

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

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

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

Retrieve the Ingress Controller IP address

You can use kubectl to fetch the address that has been dynamically allocated by DigitalOcean to the NGINX Ingress you'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.245.147.23  64.225.83.163   80:30087/TCP,443:31799/TCP,1234:31412/TC    2m

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 *.

Retrieve the Buildkit IP address

You can use kubectl to fetch the address that has been dynamically allocated by DigitalOcean 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   64.225.83.88    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

Note: after completing the previous steps, it might take a few minutes for cert manager to create a valid certificate. You can check the logs of the cert-manager deployment in the okteto namespace to check when the certificate has been created or if the certificate creation is failing. Once the certificate is created, it can take up to 5 minutes for all pods to restart and to be up and running.

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.

Refer to the general configuration documentation for advanced configuration.

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.