README.md

AiiDAlab kubernetes deployment

Follow these instructions in order to set up an AiiDAlab deployment on a kubernetes cluster.

The AiiDAlab setup is based on z2jh. Helpful links:

• z2jh customization guide
• binderhub helm chart
• extending docker stack
• kubernetes cheatsheet

Prerequisites

This sets up the environment of your local machine for deployment.

Note: The instructions below assume that you already you have a kubernetes cluster available for the deployment of AiiDAlab. However, you can use terraform to setup a cluster suitable for an AiiDAlab (JupyterHub) deployment if needed.

Setup kubernetes

• Download kubectl: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl
• Follow instructions of your kubernetes provider in order to authenticate. kubectl get pods should work
• Download helm: https://github.com/helm/helm/releases Note: Only needed locally. Your kuberenetes cluster does not need to support helm

Clone repository and prepare Python environment

Clone the repository to your development machine:

git clone https://github.com/aiidalab/aiidalab-k8s.git
cd aiidalab-k8s/

Install Python requirements for deployment, e.g., with:

pip install -r requirements.txt

Install Jupyter hub helm chart

helm repo add jupyterhub https://jupyterhub.github.io/helm-chart/
helm repo update

Deployment

This deploys AiiDAlab on your kubernetes cluster.

Prepare configuration

1. Generate a secret, e.g., with openssl rand -hex 32 to be used as the proxy secret token.
2. cp secrets.yaml.template secrets.yaml and add the just created secret as value for secret_token.
3. Apply any other configuration details to config-template.yaml.

The configuration of OAuth and SSL certificates typically requires an initial deployment. Instructions on how to configure OAuth and certificates is therefore found below.

Initial deployment

Run ./deploy-jh.sh.

This will generate the config.yaml file by comining the config-template.yaml and secrets.yaml files and then installing the helm chart on the cluster. Important: Do not edit the autogenerated config.yaml directly, the file is going to be overwritten on the next run of ./deploy.jh.

After successful execution, you will be presented with some information about how to access the cluster. For example, you can run kubectl get pods to inspect the status of all deployed pods.

Fully qualified domain name

You can make your cluster available via a custom domain name by pointing its DNS entry (e.g. an ANAME or CNAME) directly to the external address of the cluster. The external address can be determined by running

kubectl describe service proxy-public

SSL certificates and ingress

Important: You need to point a fully-qualified domain name to the cluster before trying to obtain a certificate. The process for obtaining an SSL certificate, for example with Let's Encrypt is described here.

Requests to your domain should now be routed directly to your AiiDAlab via an encrypted HTTPS connection.

User authentication via OAuth

The best approach to enable authenticated login is to use the OAuth2 flow. To setup OAuth, edit the auth: section within the config-template.yaml file and replace them with the relevant configuration for your OAuth provider (e.g. gitHub.com). Secrets should be injected via the secrets.yaml file.