feat: publish plain manifests, auto-generate docs from CRD

SwissDataScienceCenter · Sep 20, 2021 · 176301f · 176301f
1 parent c88cfa4
commit 176301f
Show file tree

Hide file tree

Showing 13 changed files with 527 additions and 18 deletions.
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
@@ -0,0 +1,13 @@
+#!/bin/sh
+#
+# Generate the full manifests by rendering the chart.
+
+repo_root=$(git rev-parse --show-toplevel)
+current_directory=$(pwd)
+
+cd $repo_root
+pipenv run python ./utils/render-chart-manifests.py
+git add manifests
+cd ${repo_root}/helm-chart
+pipenv run chartpress --skip-build --tag latest
+cd $current_directory
diff --git a/.github/workflows/generate-crd-docs.yaml b/.github/workflows/generate-crd-docs.yaml
@@ -0,0 +1,25 @@
+name: Autogenerate the documentation for the CRD
+
+on:
+  push:
+    branches:
+      - "**"
+      - "!main"
+jobs:
+  generate-crd-docs:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: SwissDataScienceCenter/renku-actions/generate-crd-docs@3d6f5abf79b61d969b0d958e42dabb4e9f15392c
+        env:
+          RESOURCES: ./manifests/crd.yaml
+          OUTPUT: ./docs/crd.md
+      - name: Push changes to branch
+        run: |
+          git config --global user.name 'Amalthea Bot'
+          git config --global user.email '[email protected]'
+          git add docs/crd.md || true
+          git commit -m "chore(docs): update CRD docs" || true
+          git push || true
diff --git a/README.md b/README.md
@@ -5,6 +5,19 @@ This project defines a custom `JupyterServer`
 for Kubernetes and implements a Kubernetes operator which controls the lifecycle
 of custom `JupyterServer` objects.
 
+## Installation
+
+The recommended way of installing Amalthea is through its **helm chart**:
+
+```bash
+helm repo add renku https://swissdatasciencecenter.github.io/helm-charts
+helm install amalthea renku/amalthea
+```
+
+For people who prefer to use plain manifests in combination with tools like
+`kustomize`, we provide the rendered templates in the
+[manifests directory](https://github.com/SwissDataScienceCenter/amalthea/tree/main/manifests).
+
 ## Example
 
 Once Amalthea is installed in a cluster through the helm chart, deploying a
@@ -86,7 +99,7 @@ change K8s resources which are created as part of the custom resource object.
 
 The main use case of Amalthea is to provide a layer on top of which developers
 can build kubernetes-native applications that allow their users to spin-up and
-manage Jupyter servers. We do not see Amalthea as a standalone tool 
+manage Jupyter servers. We do not see Amalthea as a standalone tool
 used by end users, as creating Jupyter servers with Amalthea requires access to
 the Kubernetes API.
 
@@ -106,7 +119,7 @@ The intended scope of Amalthea is much smaller than that. Specifically:
 - Amalthea itself is stateless. All state is stored as Kubernetes objects in
   etcd.
 - Amalthea uses the Kubernetes-native ingress- and service concepts for dynamically
-  adding and removing routes as Jupyter servers come and go, instead of relying on 
+  adding and removing routes as Jupyter servers come and go, instead of relying on
   an additoinal proxy for routing.
 
 ## What's in the repo
@@ -160,6 +173,14 @@ For Amalthea development you will need python 3,
 [kubectl](https://Kubernetes.io/docs/tasks/tools/#kubectl) and
 [helm](https://helm.sh/docs/intro/install/).
 
+After cloning the repo, you can install the necessary python dependencies and
+activate a custom project git hook by running
+
+```bash
+pipenv install --dev
+git config core.hooksPath .githooks
+```
+
 ### Kind
 
 The easiest way to set up a cluster that will let you develop and test a feature

diff --git a/helm-chart/amalthea/Chart.yaml b/helm-chart/amalthea/Chart.yaml
@@ -15,12 +15,12 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.0.1-rc1
+version: latest
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to
 # follow Semantic Versioning. They should reflect the version the application is using. Note
 # that the appVersion is used as image tag if that is not specified in the values file. For
 # the time being appVersion should match the chart version for each released version of this
 # chart.
-appVersion: 0.0.1
+appVersion: latest
diff --git a/helm-chart/amalthea/templates/crd.yaml b/helm-chart/amalthea/templates/crd.yaml
@@ -58,13 +58,14 @@ spec:
                       default: /lab
                     rootDir:
                       type: string
-                      description: "The absolute path to the root/notebook directory for jupyterlab. Should lead to a subdirectory of or match the path at storage.pvc.mountPath"
+                      description: |
+                        The absolute path to the root/notebook directory for jupyterlab. Should
+                        lead to a subdirectory of or match the path at storage.pvc.mountPath
                       default: /home/jovyan/work
-
-                    # TODO: Automatically fetch and inline schema
-                    # https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#resourcerequirements-v1-core
                     resources:
-                      description: "Regular resource requests, will be set on the main notebook container."
+                      description: |
+                        Regular resource requests, will be set on the main notebook
+                        container.
                       type: object
                       x-kubernetes-preserve-unknown-fields: true
                       default: {}
@@ -97,23 +98,31 @@ spec:
                   default: {}
                   properties:
                     size:
-                      description: "Size of the PVC or sizeLimit of the emptyDir volume which backs the session respectively."
+                      description: |
+                        Size of the PVC or sizeLimit of the emptyDir volume which
+                        backs the session respectively.
                       type: string
                       default: 100Mi
                     pvc:
                       type: object
                       default: {}
                       properties:
                         enabled:
-                          description: "Wether a PVC should be used to back the session. Defaults to 'false' in which case an emptyDir volume will be used."
+                          description: |
+                            Wether a PVC should be used to back the session. Defaults
+                            to 'false' in which case an emptyDir volume will be used.
                           type: boolean
                           default: false
                         storageClassName:
                           type: string
-                          description: "Storage class to be used for the PVC. If left empty, the default storage class defined for the cluster will be used."
+                          description: |
+                            Storage class to be used for the PVC. If left empty, the
+                            default storage class defined for the cluster will be used.
                         mountPath:
                           type: string
-                          description: "The absolute path to the location where the PVC should be mounted in the user session pod."
+                          description: |
+                            The absolute path to the location where the PVC should be
+                            mounted in the user session pod.
                           default: /home/jovyan/work
 
                 auth:
@@ -194,7 +203,9 @@ spec:
                             type: string
 
                 patches:
-                  description: "Patches to be applied. Currently only json patches and json merge patches are supported."
+                  description: |
+                    Patches to be applied. Currently only json patches and json merge
+                    patches are supported.
                   type: array
                   default: []
                   items:
@@ -207,14 +218,16 @@ spec:
                           - application/merge-patch+json
                       patch:
                         x-kubernetes-preserve-unknown-fields: true
-                
+
                 culling:
-                  description: "Options about culling idle servers."
+                  description: Options about culling idle servers
                   type: object
                   default: {}
                   properties:
                     idleSecondsThreshold:
-                      description: "How long should a server be idle for before it is culled. A value of zero indicates that the server should never be culled."
+                      description: |
+                        How long should a server be idle for before it is culled. A value of zero
+                        indicates that the server should never be culled.
                       type: integer
                       minimum: 0
                       default: 0

diff --git a/helm-chart/amalthea/values.yaml b/helm-chart/amalthea/values.yaml
@@ -79,7 +79,7 @@ image:
   repository: renku/amalthea
   pullPolicy: IfNotPresent
   # Overrides the image tag whose default is the chart appVersion.
-  tag: "0.0.1-rc1"
+  tag: "latest"
 
 imagePullSecrets: []
 nameOverride: ""

diff --git a/manifests/config.yaml b/manifests/config.yaml
@@ -0,0 +1,13 @@
+# This manifest is auto-generated from the helm chart, do not modify! 
+# Source: amalthea/templates/config.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: amalthea-config
+  labels:
+    helm.sh/chart: amalthea-latest
+    app.kubernetes.io/name: amalthea
+    app.kubernetes.io/instance: amalthea
+    app.kubernetes.io/version: "latest"
+data:
+  kopf-operator-settings.yaml: "watching:\n  # This can fix a problem of a watch stream suddenly falling\n  # silent, see https://github.com/nolar/kopf/issues/762#issuecomment-838423267\n  client_timeout: 600\n"