Google Kubernetes Engine (GKE)

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

Requirements

In order to fully install Okteto, you will 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 Google (or GitHub) OAuth application
• A Google Cloud service account and a key
• A Google Cloud Storage bucket
• An Okteto License (optional)

Subdomain

You will 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 Google's Cloud DNS. Other DNS services can be used as well, but are not covered by this guide.

Deploy a Kubernetes cluster

We recommend that you follow Google's GKE cluster creation guide.

We recommend the following specs:

• v1.19 or newer
• A pool with at least 3 n1-standard-4 nodes
• 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 Google OAuth application

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

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

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

Authorized javascript origin:

https://okteto.DOMAIN

Authorized redirect URIs:

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

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

Creating a Google Cloud Service Account

The Okteto sub-components need access to Cloud DNS (for generating certificates) and Cloud Storage (for uploading and downloading your container images).

We recommend you follow Google's official documentation on how to create and manage Service Accounts for more information on this.

You'll need to perform the following tasks:

1. Create a Service Account in the same Google Cloud project as your GKE cluster.
2. Give it the DNS Administrator and Storage Object Admin roles.
3. Create a JSON key and save it locally. We'll be using this when installing Okteto.

Creating a Google Cloud Storage Bucket

Okteto uses Google Cloud Storage to store your private images. Follow Google's guide on how to create storage buckets. Create the bucket in the same project and region as your GKE cluster, and keep it private.

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 Account key you created before:

kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-file=key=$PATH_TO_KEY_FILE

Download a copy of the Okteto GKE configuration file, open it, and set the following values:

• Your email
• Your license (optional)
• A subdomain
• clientId and clientSecret of the OAuth 2.0 Client you created
• The name of the bucket you created
• The project id of your cluster

For example:

email: admin@example.com
license: 1234567890ABCD==
subdomain: dev.example.com

auth:
  google:
    enabled: true
    clientId: clientid.apps.googleusercontent.com
    clientSecret: clientSecret

cloud:
  provider:
    gcp:
      enabled: true
      project: okteto-dev
      bucket: okteto-private-images

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 GKE 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    34.68.230.234   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 Google Cloud DNS, this is done by creating an A record with the name *. We also suggest you set the TTL to 1 minute.

Retrieve the Buildkit IP address

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