Skip to main content
Version: 1.27

Red Hat OpenShift
EnterpriseSelf-Hosted

This guide will walk you through the process of installing Okteto on a Red Hat OpenShift cluster.

Red Hat OpenShift enhances the functionality and security of applications running on Kubernetes but may introduce additional steps when installing applications like Okteto. This guide has been crafted to help you overcome these hurdles, but we encourage you to talk to us to guide you during the installation.

Installation Requirements

Before you begin, make sure you have the following command-line interfaces (CLIs) installed on your machine:

You'll also need:

  • An Okteto License
  • A Kubernetes cluster with Red Hat OpenShift (≥ 4.0.0) installed

For this guide, you will need to obtain the following values:

  • <openshift-base-domain>: for example, okteto.r9yz.p2.openshiftapps.com
  • <openshift-cluster-name>: for example, okteto

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.

Preparing your cluster for Okteto installation

Before installing Okteto, prepare your Red Hat OpenShift cluster by following these steps.

Create the okteto namespace

Run the following command to create the okteto namespace:

oc create namespace okteto

Allow containers as root in the okteto namespace

By default, running containers as root is not allowed in Red Hat OpenShift. Currently, some components of the Okteto Control Plane require root privileges (this is something we will fix soon!). To allow root containers for the Okteto Control Plane components, run the following commands:

oc adm policy add-scc-to-user anyuid -z default -n okteto 
oc adm policy add-scc-to-user anyuid -z okteto -n okteto
oc adm policy add-scc-to-user anyuid -z okteto-buildkit -n okteto
oc adm policy add-scc-to-user anyuid -z okteto-registry -n okteto

These commands grant the anyuid Security Context Constraint (SCC) to the specified service accounts in the okteto namespace, allowing them to run containers as root.

Grant access to the "privileged" SCC for the Okteto Build service account

By default, running privileged containers is not allowed in Red Hat OpenShift. This restriction affects the Okteto Build service. To grant privileged access to the Okteto Build service account, run:

 oc adm policy add-scc-to-user privileged -z okteto-buildkit -n okteto

This command grants the privileged SCC to the okteto-buildkit service account in the okteto namespace.

Grant access to the host to the Okteto Daemon service account

By default, access to the host is restricted by default in Red Hat OpenShift. This restriction impacts the he Okteto Daemon service. To grant the necessary permissions to the Okteto Daemon, run:

oc adm policy add-scc-to-user hostaccess -z okteto -n okteto

This command grants the hostaccess SCC to the okteto service account in the okteto namespace.

Copy Red Hat OpenShift wildcard certificate to the okteto namespace

Red Hat OpenShift requires a wildcard certificate for the wildcard domain *.apps.<openshift-base-domain>. We recommend reusing it when installing Okteto to expose secure and unique endpoints for your development environments.

By default, Red Hat OpenShift creates the wildcard certificate in the secret <openshift-cluster-name>-primary-cert-bundle-secret in the openshift-ingress. In this case, copy the certificate to the okteto namespace by running:

kubectl get secret <openshift-cluster-name>-primary-cert-bundle-secret -n openshift-ingress -o yaml | sed 's/namespace: openshift-ingress/namespace: okteto/' | kubectl apply -f -

If you installed OpenShift with a custom certificate, copy the certificate's secret (and CA if needed) to the okteto namespace. This guide explains how to configure a custom certificate and CA in Okteto.

Retrieve the Red Hat OpenShift Ingress Controller IP

We recommend installing Okteto behind the Red Hat Openshift Ingress Controller. Obtain the IP address of your Red Hat OpenShift Ingress Controller by running:

kubectl get svc router-default -n openshift-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Store this value as <ingress-controller-ip>; you'll use it in the Okteto Helm configuration.

Installing Okteto

Okteto is installed using a Helm chart. Follow these steps to install it.

Add the Okteto Helm repository

Add the Okteto Helm repository and update it:

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

Create the Helm configuration file

Create a configuration file named config.yaml with the following content. Replace <okteto-license>, <openshift-base-domain>, <openshift-cluster-name>, and <ingress-controller-ip> with your actual values:

license: <okteto-license>

openshift:
enabled: true

subdomain: apps.<openshift-base-domain>

wildcardCertificate:
create: false
name: <openshift-cluster-name>-primary-cert-bundle-secret

ingress-nginx:
enabled: false

okteto-nginx:
enabled: false

ingress:
oktetoIngressClass: openshift-default
class: openshift-default
forceIngressClass: true
ip: <ingress-controller-ip>

cluster:
endpoint: https://api.<openshift-base-domain>:6443

user:
extraRoleBindings:
enabled: true
roleBindings:
okteto:
- system:openshift:scc:anyuid

The extraRoleBindings section allows your developers to use use images that require root privileges in their development environments.

tip

This is the minimum configuration. Check our Helm configuration documentation to learn more

Installing the Okteto Helm chart

Install the latest version of Okteto by running:

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

This command installs Okteto in the okteto namespace using the configuration specified in config.yaml.

After a few seconds, all the resources will be created. You should see output similar to:

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

Sign in to your Okteto instance

After a successful installation, you can access your Okteto instance at https://okteto.apps.<openshift-base-domain>.

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

Install the Okteto CLI if you haven't done so yet and 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 😎