Onyxia
HomeGitHub
v10
  • Documentation
  • Release Notes & Upgrade Instructions
  • Vulnerability Disclosure
v10
  • Admin doc
    • Install
      • Kubernetes
      • GitOps
      • User authentication
      • Data (S3)
      • Vault
    • Theme and branding
    • Catalog of services
      • Use your own repositories
      • Customize your charts
        • JSON Schema Support
        • Onyxia extension
      • Override schema for a specific instance
    • OpenID Connect Configuration
    • S3 Configuration
    • Setting up group projects
    • Security consideration
  • Contributors doc
    • The Web Application
      • Technical stack
      • Architecture
    • The REST API
    • Roadmap
    • Community calls
      • April 2025 community call
      • March 2025 community call
      • February 2025 community call
      • January 2025 community call
  • user doc
    • Getting started with Onyxia
    • Datascience Trainings and Tutorials
    • Setting up your dev environment in Onyxia
    • Community resources
Powered by GitBook
On this page

Was this helpful?

Edit on GitHub
Export as PDF
  1. Admin doc
  2. Install

Kubernetes

Provision a Kubernetes cluster

Was this helpful?

First you'll need a Kubernetes cluster. If you have one already you can skip and directly go to .

maintains great tutorials for Kubernetes clusters on , or .

Pick one of the three and follow the guide.

You can stop after the .

Ingress controller

Let's install ingress-ngnix on our newly created cluster:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.2.0/deploy/static/provider/aws/deploy.yaml

DNS

Let's assume you own the domain name my-domain.net, for the rest of the guide you should replace my-domain.net by a domain you actually own.

Now you need to get the external address of your cluster, run the command

kubectl get services -n ingress-nginx

and write down the External IP assigned to the LoadBalancer.

Depending on the cloud provider you are using it can be an IPv4, an IPv6 or a domain. On AWS for example, it will be a domain like xxx.elb.eu-west-1.amazonaws.com.

If you see <pending>, wait a few seconds and try again.

Once you have the address, create the following DNS records:

datalab.my-domain.net CNAME xxx.elb.eu-west-1.amazonaws.com. 
*.lab.my-domain.net   CNAME xxx.elb.eu-west-1.amazonaws.com. 

If the address you got was an IPv4 (x.x.x.x), create a A record instead of a CNAME.

If the address you got was ans IPv6 (y:y:y:y:y:y:y:y), create a AAAA record.

https://datalab.my-domain.net will be the URL for your instance of Onyxia. The URL of the services created by Onyxia are going to look like: https://<something>.lab.my-domain.net

You can customise "datalab" and "lab" to your liking, for example you could chose onyxia.my-domain.net and *.kub.my-domain.net.

SSL

If you are already familiar with certbot you're probably used to run it on a remote host via SSH. In this case you are expected to run it on your own machine, we'll use the DNS chalenge instead of the HTTP chalenge.

brew install certbot #On Mac, lookup how to install certbot for your OS

#Because we need a wildcard certificate we have to complete the DNS callange.  
sudo certbot certonly --manual --preferred-challenges dns

# When asked for the domains you wish to optains a certificate for enter:
#   datalab.my-domain.net *.lab.my-domain.net

The obtained certificate needs to be renewed every three month.

Now we want to create a Kubernetes secret containing our newly obtained certificate:

DOMAIN=my-domain.net
sudo kubectl create secret tls onyxia-tls \
    -n ingress-nginx \
    --key /etc/letsencrypt/live/datalab.$DOMAIN/privkey.pem \
    --cert /etc/letsencrypt/live/datalab.$DOMAIN/fullchain.pem

Lastly, we want to tell our ingress controller to use this TLS certificate, to do so run:

kubectl edit deployment ingress-nginx-controller -n ingress-nginx

This command will open your configured text editor, go to containers -> args and add:

      - --default-ssl-certificate=ingress-nginx/onyxia-tls
      - --watch-ingress-without-class

Port Forwarding

DNS

Let's assume you own the domain name my-domain.net, for the rest of the guide you should replace my-domain.net by a domain you actually own.

datalab.my-domain.net A <YOUR_IP>
*.lab.my-domain.net   A <YOUR_IP>

If you have DDNS domain you can create CNAME instead example:

datalab.my-domain.net CNAME jhon-doe-home.ddns.net.
*.lab.my-domain.net   CNAME jhon-doe-home.ddnc.net.

https://datalab.my-domain.net will be the URL for your instance of Onyxia.

The URL of the services created by Onyxia are going to look like: https://xxx.lab.my-domain.net

You can customise "datalab" and "lab" to your liking, for example you could chose onyxia.my-domain.net and *.kub.my-domain.net.

SSL

brew install certbot #On Mac, lookup how to install certbot for your OS

# Because we need a wildcard certificate we have to complete the DNS callange.  
sudo certbot certonly --manual --preferred-challenges dns

# When asked for the domains you wish to optains a certificate for enter:
#   datalab.my-domain.net *.lab.my-domain.net

The obtained certificate needs to be renewed every three month.

Now we want to create a Kubernetes secret containing our newly obtained certificate:

# First let's make sure we connect to our local Kube cluser
kubectl config use-context docker-desktop

kubectl create namespace ingress-nginx
DOMAIN=my-domain.net
sudo kubectl create secret tls onyxia-tls \
    -n ingress-nginx \
    --key /etc/letsencrypt/live/datalab.$DOMAIN/privkey.pem \
    --cert /etc/letsencrypt/live/datalab.$DOMAIN/fullchain.pem

Ingress controller

We will install ingress-nginx in our cluster, although any other ingress controller would be suitable as well. The configuration will be set up to handle all ingress objects, including those without a specified class, and to utilize our SSL certificate for our wildcard certificate. This approach ensures a straightforward SSL termination managed by the reverse proxy for both *.lab.my-domain.net and datalab.my-domain.net, eliminating any further concerns regarding SSL setup.

cat << EOF > ./ingress-nginx-values.yaml
controller:
  extraArgs:
    default-ssl-certificate: "ingress-nginx/onyxia-tls"
  watchIngressWithoutClass: true
EOF

helm install ingress-nginx ingress-nginx \
    --repo https://kubernetes.github.io/ingress-nginx \
    --version 4.9.1 \
    --namespace ingress-nginx \
    -f ./ingress-nginx-values.yaml

Now that we have a Kubernetes cluster ready to use let's levrage ArgoCD and GitOps practices to deploy and monitor the core services of our Onyxia Datalab.

The following command is .

For GCP use .

For Azure use .

In this section we will obtain a TLS certificate issued by using the commend line tool then get our ingress controller to use it.

To avoid the burden of having to remember to re-run the certbot command periodically you can setup and configure a on your cluster but that's out of scope for Onyxia.

You may need to delegate your DNS Servers to one of the supported .

Save and quit. Done We installed the ingress-nginx in our cluster, (but note that any other ingress controller could have been used as well). The configuration was adjusted to handle all ingress objects, even those lacking a specified class, and to employ our SSL certificate for our wildcard certificate. This strategy facilitated an effortless SSL termination, managed by the reverse proxy for both *.lab.my-domain.net and datalab.my-domain.net, thus removing any additional SSL configuration concerns.

If you are on a Mac or Window computer you can install then enable Kubernetes.

WARNING: If you are folowing this installating guide on an Apple Sillicon Mac, be aware that many of the services that comes by default with Onyxia like Jupyter RStudio and VSCode won't run because we do not yet compile our datacience stack for the ARM64 architecture. If you would like to see this change please .

Docker desktop isn't available on Linux, you can use instead.

You'll need to . It's done from the administration panel of your domestic internet Box. If you're on a corporate network you'll have to .

Get and create the following DNS records:

In this section we will obtain a TLS certificate issued by using the commend line tool.

To avoid the burden of having to remember to re-run the certbot command periodically you can setup and configure a on your cluster but that's out of scope for Onyxia.

You may need to delegate your DNS Servers to one of the supported .

🎉
for AWS
this command
this command
LetsEncrypt
certbot
cert-manager
DNS01 challenge provider
DNS service provider
Docker desktop
sumit an issue about it
Kind
your internet box routable IP
LetsEncrypt
certbot
cert-manager
DNS01 challenge provider
DNS service provider
GitOps
forward the TCP ports 80 and 443 to your local machine
test onyxia on a remote Kubernetes cluster
the Onyxia instalation section
Hashicorp
terraforming
AWS
GCP
Azure
configure kubectl section
LogoProvision an EKS Cluster (AWS) | Terraform | HashiCorp DeveloperProvision an EKS Cluster (AWS) | Terraform | HashiCorp Developer
LogoProvision a GKE Cluster (Google Cloud) | Terraform | HashiCorp DeveloperProvision a GKE Cluster (Google Cloud) | Terraform | HashiCorp Developer
LogoProvision an AKS Cluster (Azure) | Terraform | HashiCorp DeveloperProvision an AKS Cluster (Azure) | Terraform | HashiCorp Developer
Enabling Kubernetes in the Docker desktop App