From f30d5e1c5b7076718b01efbd3df9e5189f792ab8 Mon Sep 17 00:00:00 2001 From: Christophe Haen Date: Thu, 13 Jun 2024 11:19:27 +0200 Subject: [PATCH] start writing docs --- README.md | 180 ++++++++++++++++++++++++++--------- README.md.gotmpl | 189 +++++++++++++++++++++++++++---------- demo/values.tpl.yaml | 1 + diracx/templates/NOTES.txt | 6 +- docs/README.md | 13 +++ docs/REFERENCE.md | 7 ++ docs/RUN_DEMO.md | 47 +++++++++ run_demo.sh | 2 +- 8 files changed, 347 insertions(+), 98 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/REFERENCE.md create mode 100644 docs/RUN_DEMO.md diff --git a/README.md b/README.md index fc45981..28a1051 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,128 @@ This helm chart is intended to be used in two ways: ![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.0.1a](https://img.shields.io/badge/AppVersion-0.0.1a-informational?style=flat-square) -## Running locally +![DiracX Chart tests](https://github.com/DIRACGrid/diracx-charts/actions/workflows/main.yml/badge.svg?branch=master) -TODO +## Workflow + +This chart can be used for 4 different installation type: + +* demo/dev: we install everything and configure everything with pre-configured values (see [below](##running_locally)) +* prod: you already have a DIRAC installation with it's own DBs and everything, so you want to create a cluster, but bridge on existing external resources (like DBs) +* New: you start from absolutely nothing (no DIRAC), and you want to install all the dependencies +* New without dependencies: you start with nothing, but you want to use externally managed resources (like DB provided by your IT service) + +Depending on the installation you perform, some tasks may be necessary or not. The bottom line is that to simplify the various cases, we want to be able to always run the initialization steps (like DB initialization, or CS initialization) but they should be adiabatic and non destructive. + +To understand how the chart operates, see [reference](./docs/REFERENCE.md) + +## What this chart contains + +This chart contains the deployment for ``diracx`` and ``diracx-web``, as well as dependencies: +* Mysql database +* OpenSearch database +* Dex and IAM as identity provider +* Minio as an object store for the ``SandboxStore`` +* OpenTelemetry (see [details](#opentelemetry)) + +## Intro to Kubernetes and Helm + +[Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/) (k8s) allows you to deploy containerized applications while letting you abstract the underlying infrastructure. The configuration of your application and how you run it is communicated to k8s via ``yaml`` files. + +[Helm](https://helm.sh/) allows to template these ``yaml`` files. Such a templated description of an application like ``diracx`` is called ``chart``. Helm also allows to manage dependencies between ``charts``. For example, the ``diracx`` application needs a database to run, so the ``diracx charts`` has a dependency on the ``mysql charts``. + +To understand this ``chart`` you will need to familiarize yourself with a few k8s concepts: +* A ``node`` is one of the machine (VM, physical) which sustains your k8s cluster. +* Your application runs inside a container which is part of a ``pod``. A ``pod`` is the atomic unit with which kubernetes will work, and in most cases it corresponds to a single container. ``pods`` are deployed on ``nodes``. +* A ``ReplicaSet`` represents how many ``pods`` of a given type you want to run. For example, you want to run 3 ``pods`` containing the ``diracx`` container for redundancy reasons. +* A ``Deployment`` is how you describe your workload to k8s. It ensures that any number of replicas of your ``pod`` are running (via ``ReplicaSEt``). This chart contains a ``deployment`` for ``diracx`` (see [here](diracx/templates/diracx/deployment.yaml)), and a ``deployment`` for ``diracx-web`` (see [here](diracx/templates/diracx-web/deployment.yaml)). Kubernetes will always make sure that the ``deployment`` is satisfied. +* A ``Service`` is how you expose your ``Deployment``. If I want to talk to my ``diracx`` application, it is a ``Service`` which will take care of redirecting me within the cluster to one of the ``pod``. Most of the time, the ``Service`` is used for routing inside the cluster +* An ``Ingress`` exposes your ``Services`` outside of the cluster. + +## Running the demo locally + +Running an instance locally is useful for demo or testing purposes. This entails running a local kubernetes cluster, installing this helm chart and all its dependencies, and configuring it accordingly. In order to make that easy, we wrote the ``run_demo.sh`` script, which covers all these needs. This is also used for the [diracx ci](https://github.com/DIRACGrid/diracx/blob/main/.github/workflows/main.yml) + +### ``run_demo.sh`` + +This is the script used to start a demo or the integration tests. + +```bash +Usage: run_demo.sh [-h|--help] [--exit-when-done] [--offline] [--enable-coverage] [--no-mount-containerd] [--set-value key=value] [--] [source directories] + + -h|--help: Print this help message and exit + --exit-when-done: Exit after the demo has been started (it will be left running in the background) + --enable-coverage: Enable coverage reporting (used by diracx CI) + --no-editable-python: Do not install Python source directories in editable mode + --offline: Run in a mode which is suitable for fully offline use. + WARNING: This may result in some weird behaviour, see the demo documentation for details. + Implies: --mount-containerd + --no-mount-containerd: Mount a directory on the host for the kind containerd storage. + This option avoids needing to pull container images every time the demo is started. + WARNING: There is no garbage collection so the directory will grow without bound. + --enable-open-telemetry: lauches OpenTelemetry collection. + WARNING: experimental and resource hungry. + --set-value: Set a value in the Helm values file. This can be used to override the default values. + For example, to enable coverage reporting pass: --set-value developer.enableCoverage=true + source directories: A list of directories containing Python packages to mount in the demo cluster. +``` + +Once ready, you will get some information on how to interact with your cluster + +```md +NOTES: + +🚧 Chart has been installed in developer mode. + +ℹī¸ To interact with the cluster directly using kubectl/helm you'll need to set the +first following environment variables: + + export KUBECONFIG=/home/chaen/dirac/diracx-project/diracx-charts/.demo/kube.conf + export HELM_DATA_HOME=/home/chaen/dirac/diracx-project/diracx-charts/.demo/helm_data + export PATH=${PATH}:/home/chaen/dirac/diracx-project/diracx-charts/.demo + +Then see the chart README for more information on how to use kubectl/helm. + +ℹī¸ To use the demo with the DiracX client set: + + export DIRACX_URL=https://172.18.0.1.nip.io:8000 + export DIRACX_CA_PATH=/home/chaen/dirac/diracx-project/diracx-charts/.demo/demo-ca.pem + +ℹī¸ To use the demo with a DiracX client without local installation: + + kubectl exec -it deployment/diracx-demo-cli -- bash + +ℹī¸ To access the web application visit: + https://172.18.0.1.nip.io:8000 + +ℹī¸ To access the interactive API documentation visit: + + https://172.18.0.1.nip.io:8000/api/docs + +ℹī¸ When prompted to login the credentials are: + + Username: admin@example.com + Password: password + +ℹī¸ Grafana dashboard for telemetry (if enabled) + + https://172.18.0.1.nip.io:32004 + + Username: admin + Password: run ``kubectl get secrets diracx-demo-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo`` + +đŸĻ„ Waiting for installation to finish... +pod/diracx-demo-7fd5c47cd6-mq8s7 condition met +🎉 🎉 🎉 Pods are ready! 🎉 🎉 🎉 +đŸĻ„ Creating initial CS content ... +Writing back configuration to /cs_store/initialRepo/default.yml +Successfully added vo to git+file:///cs_store/initialRepo +Writing back configuration to /cs_store/initialRepo/default.yml +Successfully added user to git+file:///cs_store/initialRepo + +ℹī¸ Press Ctrl+C to clean up and exit +``` ### Interacting with the demo #### Kubernetes basics @@ -26,15 +144,13 @@ kubectl describe pod/ kubectl logs # Show the logs of a running pod and keep following them kubectl logs -f -# Run a command in one of the non-LbAPI pods -kubectl exec -it -- /bin/bash -# Run a command in one of the LbAPI pods with the conda environment loaded -kubectl exec -it -- /dockerMicroMambaEntrypoint.sh bash +# Run a command in one of the pods +kubectl exec -it -- /bin/bash /entrypoint.sh ``` #### Helm basics -When running the demo some an `values.yaml` file is created as `.demo/values.yaml`. +When running the demo, an `values.yaml` file is created as `.demo/values.yaml`. This file can be used with helm to interact with the running demo to make changes to what is running in the cluster. ```bash @@ -53,7 +169,17 @@ helm diff upgrade diracx-demo ./diracx --values .demo/values.yaml --set rabbitm helm upgrade diracx-demo ./diracx --values .demo/values.yaml ``` -## Deploying a custom branch to DIRAC certification +See [here](./docs/RUN_DEMO.md) for more details on what you can do to alter the behavior of the local installation. + +## Deploying in production + +TODO: Link to k3s + +TODO: Explain how to download the values from helm + +TODO: add info about diracx-web + +### Deploying a custom branch to DIRAC certification Apply the following on top of the standard `values.yaml` file, replacing `USERNAME` and `BRANCH_NAME` with the appropriate values. @@ -72,30 +198,6 @@ diracx: - "git+https://github.com/USERNAME/diracx.git@BRANCH_NAME#egg=diracx_routers&subdirectory=diracx-routers"yaml ``` -## ``run_demo.sh`` - -This is the script used to start a demo or the integration tests. - -``` -Usage: run_demo.sh [-h|--help] [--exit-when-done] [--offline] [--enable-coverage] [--no-mount-containerd] [--set-value key=value] [--] [source directories] - - -h|--help: Print this help message and exit - --exit-when-done: Exit after the demo has been started (it will be left running in the background) - --enable-coverage: Enable coverage reporting - --no-editable-python: Do not install Python source directories in editable mode - --offline: Run in a mode which is suitable for fully offline use. - WARNING: This may result in some weird behaviour, see the demo documentation for details. - Implies: --mount-containerd - --no-mount-containerd: Mount a directory on the host for the kind containerd storage. - This option avoids needing to pull container images every time the demo is started. - WARNING: There is no garbage collection so the directory will grow without bound. - --enable-open-telemetry: lauches OpenTelemetry collection. - WARNING: experimental and resource hungry. - --set-value: Set a value in the Helm values file. This can be used to override the default values. - For example, to enable coverage reporting pass: --set-value developer.enableCoverage=true - source directories: A list of directories containing Python packages to mount in the demo cluster. -``` - ## OpenTelemetry > :warning: **Experimental**: opentelemetry is an evolving product, and so is our implementation of it. @@ -113,20 +215,6 @@ Note that this configuration is trivial and does not follow production recommand ![OTEL collector configuration](./demo/otel-collector.png) -## Deploying in production - -TODO - -## Workflow - -4 types of installations: -* demo/dev: we install everything and configure everything with pre-configured values -* prod: you already have a DIRAC installation with it's own DBs and everything, so you want to create a cluster, but bridge on existing external resources (like DBs) -* New: you start from absolutely nothing (no DIRAC), and you want to install all the dependencies -* New without dependencies: you start with nothing, but you want to use externally managed resources (like DB provided by your IT service) - -Depending on the installation you perform, some tasks may be necessary or not. The bottom line is that to simplify the various cases, we want to be able to always run the initialization steps (like DB initialization, or CS initialization) but they should be adiabatic and non destructive. - ## Requirements | Repository | Name | Version | diff --git a/README.md.gotmpl b/README.md.gotmpl index 0d25059..e76d157 100644 --- a/README.md.gotmpl +++ b/README.md.gotmpl @@ -4,10 +4,132 @@ {{ template "chart.versionBadge" . }}{{ template "chart.typeBadge" . }}{{ template "chart.appVersionBadge" . }} -## Running locally +![DiracX Chart tests](https://github.com/DIRACGrid/diracx-charts/actions/workflows/main.yml/badge.svg?branch=master) -TODO +## Workflow + +This chart can be used for 4 different installation type: + +* demo/dev: we install everything and configure everything with pre-configured values (see [below](##running_locally)) +* prod: you already have a DIRAC installation with it's own DBs and everything, so you want to create a cluster, but bridge on existing external resources (like DBs) +* New: you start from absolutely nothing (no DIRAC), and you want to install all the dependencies +* New without dependencies: you start with nothing, but you want to use externally managed resources (like DB provided by your IT service) + +Depending on the installation you perform, some tasks may be necessary or not. The bottom line is that to simplify the various cases, we want to be able to always run the initialization steps (like DB initialization, or CS initialization) but they should be adiabatic and non destructive. + +To understand how the chart operates, see [reference](./docs/REFERENCE.md) + +## What this chart contains + +This chart contains the deployment for ``diracx`` and ``diracx-web``, as well as dependencies: +* Mysql database +* OpenSearch database +* Dex and IAM as identity provider +* Minio as an object store for the ``SandboxStore`` +* OpenTelemetry (see [details](#opentelemetry)) + +## Intro to Kubernetes and Helm + +[Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/) (k8s) allows you to deploy containerized applications while letting you abstract the underlying infrastructure. The configuration of your application and how you run it is communicated to k8s via ``yaml`` files. + +[Helm](https://helm.sh/) allows to template these ``yaml`` files. Such a templated description of an application like ``diracx`` is called ``chart``. Helm also allows to manage dependencies between ``charts``. For example, the ``diracx`` application needs a database to run, so the ``diracx charts`` has a dependency on the ``mysql charts``. + +To understand this ``chart`` you will need to familiarize yourself with a few k8s concepts: +* A ``node`` is one of the machine (VM, physical) which sustains your k8s cluster. +* Your application runs inside a container which is part of a ``pod``. A ``pod`` is the atomic unit with which kubernetes will work, and in most cases it corresponds to a single container. ``pods`` are deployed on ``nodes``. +* A ``ReplicaSet`` represents how many ``pods`` of a given type you want to run. For example, you want to run 3 ``pods`` containing the ``diracx`` container for redundancy reasons. +* A ``Deployment`` is how you describe your workload to k8s. It ensures that any number of replicas of your ``pod`` are running (via ``ReplicaSEt``). This chart contains a ``deployment`` for ``diracx`` (see [here](diracx/templates/diracx/deployment.yaml)), and a ``deployment`` for ``diracx-web`` (see [here](diracx/templates/diracx-web/deployment.yaml)). Kubernetes will always make sure that the ``deployment`` is satisfied. +* A ``Service`` is how you expose your ``Deployment``. If I want to talk to my ``diracx`` application, it is a ``Service`` which will take care of redirecting me within the cluster to one of the ``pod``. Most of the time, the ``Service`` is used for routing inside the cluster +* An ``Ingress`` exposes your ``Services`` outside of the cluster. + + +## Running the demo locally + +Running an instance locally is useful for demo or testing purposes. This entails running a local kubernetes cluster, installing this helm chart and all its dependencies, and configuring it accordingly. In order to make that easy, we wrote the ``run_demo.sh`` script, which covers all these needs. This is also used for the [diracx ci](https://github.com/DIRACGrid/diracx/blob/main/.github/workflows/main.yml) + + +### ``run_demo.sh`` + +This is the script used to start a demo or the integration tests. + +```bash +Usage: run_demo.sh [-h|--help] [--exit-when-done] [--offline] [--enable-coverage] [--no-mount-containerd] [--set-value key=value] [--] [source directories] + + -h|--help: Print this help message and exit + --exit-when-done: Exit after the demo has been started (it will be left running in the background) + --enable-coverage: Enable coverage reporting (used by diracx CI) + --no-editable-python: Do not install Python source directories in editable mode + --offline: Run in a mode which is suitable for fully offline use. + WARNING: This may result in some weird behaviour, see the demo documentation for details. + Implies: --mount-containerd + --no-mount-containerd: Mount a directory on the host for the kind containerd storage. + This option avoids needing to pull container images every time the demo is started. + WARNING: There is no garbage collection so the directory will grow without bound. + --enable-open-telemetry: lauches OpenTelemetry collection. + WARNING: experimental and resource hungry. + --set-value: Set a value in the Helm values file. This can be used to override the default values. + For example, to enable coverage reporting pass: --set-value developer.enableCoverage=true + source directories: A list of directories containing Python packages to mount in the demo cluster. +``` + +Once ready, you will get some information on how to interact with your cluster + +```md +NOTES: + +🚧 Chart has been installed in developer mode. + +ℹī¸ To interact with the cluster directly using kubectl/helm you'll need to set the +first following environment variables: + + export KUBECONFIG=/home/chaen/dirac/diracx-project/diracx-charts/.demo/kube.conf + export HELM_DATA_HOME=/home/chaen/dirac/diracx-project/diracx-charts/.demo/helm_data + export PATH=${PATH}:/home/chaen/dirac/diracx-project/diracx-charts/.demo + +Then see the chart README for more information on how to use kubectl/helm. + +ℹī¸ To use the demo with the DiracX client set: + + export DIRACX_URL=https://172.18.0.1.nip.io:8000 + export DIRACX_CA_PATH=/home/chaen/dirac/diracx-project/diracx-charts/.demo/demo-ca.pem + +ℹī¸ To use the demo with a DiracX client without local installation: + + kubectl exec -it deployment/diracx-demo-cli -- bash + +ℹī¸ To access the web application visit: + + https://172.18.0.1.nip.io:8000 + +ℹī¸ To access the interactive API documentation visit: + + https://172.18.0.1.nip.io:8000/api/docs + +ℹī¸ When prompted to login the credentials are: + + Username: admin@example.com + Password: password + +ℹī¸ Grafana dashboard for telemetry (if enabled) + + https://172.18.0.1.nip.io:32004 + + Username: admin + Password: run ``kubectl get secrets diracx-demo-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo`` + + +đŸĻ„ Waiting for installation to finish... +pod/diracx-demo-7fd5c47cd6-mq8s7 condition met +🎉 🎉 🎉 Pods are ready! 🎉 🎉 🎉 +đŸĻ„ Creating initial CS content ... +Writing back configuration to /cs_store/initialRepo/default.yml +Successfully added vo to git+file:///cs_store/initialRepo +Writing back configuration to /cs_store/initialRepo/default.yml +Successfully added user to git+file:///cs_store/initialRepo + +ℹī¸ Press Ctrl+C to clean up and exit +``` ### Interacting with the demo #### Kubernetes basics @@ -23,15 +145,13 @@ kubectl describe pod/ kubectl logs # Show the logs of a running pod and keep following them kubectl logs -f -# Run a command in one of the non-LbAPI pods -kubectl exec -it -- /bin/bash -# Run a command in one of the LbAPI pods with the conda environment loaded -kubectl exec -it -- /dockerMicroMambaEntrypoint.sh bash +# Run a command in one of the pods +kubectl exec -it -- /bin/bash /entrypoint.sh ``` #### Helm basics -When running the demo some an `values.yaml` file is created as `.demo/values.yaml`. +When running the demo, an `values.yaml` file is created as `.demo/values.yaml`. This file can be used with helm to interact with the running demo to make changes to what is running in the cluster. ```bash @@ -51,9 +171,20 @@ helm diff upgrade diracx-demo ./diracx --values .demo/values.yaml --set rabbitm helm upgrade diracx-demo ./diracx --values .demo/values.yaml ``` +See [here](./docs/RUN_DEMO.md) for more details on what you can do to alter the behavior of the local installation. + + +## Deploying in production + +TODO: Link to k3s -## Deploying a custom branch to DIRAC certification +TODO: Explain how to download the values from helm + +TODO: add info about diracx-web + + +### Deploying a custom branch to DIRAC certification Apply the following on top of the standard `values.yaml` file, replacing `USERNAME` and `BRANCH_NAME` with the appropriate values. @@ -72,32 +203,6 @@ diracx: - "git+https://github.com/USERNAME/diracx.git@BRANCH_NAME#egg=diracx_routers&subdirectory=diracx-routers"yaml ``` - -## ``run_demo.sh`` - -This is the script used to start a demo or the integration tests. - -``` -Usage: run_demo.sh [-h|--help] [--exit-when-done] [--offline] [--enable-coverage] [--no-mount-containerd] [--set-value key=value] [--] [source directories] - - -h|--help: Print this help message and exit - --exit-when-done: Exit after the demo has been started (it will be left running in the background) - --enable-coverage: Enable coverage reporting - --no-editable-python: Do not install Python source directories in editable mode - --offline: Run in a mode which is suitable for fully offline use. - WARNING: This may result in some weird behaviour, see the demo documentation for details. - Implies: --mount-containerd - --no-mount-containerd: Mount a directory on the host for the kind containerd storage. - This option avoids needing to pull container images every time the demo is started. - WARNING: There is no garbage collection so the directory will grow without bound. - --enable-open-telemetry: lauches OpenTelemetry collection. - WARNING: experimental and resource hungry. - --set-value: Set a value in the Helm values file. This can be used to override the default values. - For example, to enable coverage reporting pass: --set-value developer.enableCoverage=true - source directories: A list of directories containing Python packages to mount in the demo cluster. -``` - - ## OpenTelemetry > :warning: **Experimental**: opentelemetry is an evolving product, and so is our implementation of it. @@ -116,22 +221,6 @@ Note that this configuration is trivial and does not follow production recommand ![OTEL collector configuration](./demo/otel-collector.png) -## Deploying in production - -TODO - - -## Workflow - -4 types of installations: -* demo/dev: we install everything and configure everything with pre-configured values -* prod: you already have a DIRAC installation with it's own DBs and everything, so you want to create a cluster, but bridge on existing external resources (like DBs) -* New: you start from absolutely nothing (no DIRAC), and you want to install all the dependencies -* New without dependencies: you start with nothing, but you want to use externally managed resources (like DB provided by your IT service) - -Depending on the installation you perform, some tasks may be necessary or not. The bottom line is that to simplify the various cases, we want to be able to always run the initialization steps (like DB initialization, or CS initialization) but they should be adiabatic and non destructive. - - {{ template "chart.requirementsSection" . }} {{ template "chart.valuesSection" . }} diff --git a/demo/values.tpl.yaml b/demo/values.tpl.yaml index f76f398..861c9a3 100644 --- a/demo/values.tpl.yaml +++ b/demo/values.tpl.yaml @@ -9,6 +9,7 @@ developer: minio: http://{{ hostname }}:32000 dex: http://{{ hostname }}:32002 iam: http://{{ hostname }}:32003 + grafana: http://{{ hostname }}:32004 demoDir: {{ demo_dir }} mountedPythonModulesToInstall: {{ mounted_python_modules }} editableMountedPythonModules: {{ editable_mounted_modules }} diff --git a/diracx/templates/NOTES.txt b/diracx/templates/NOTES.txt index 4801f8b..08f99bf 100644 --- a/diracx/templates/NOTES.txt +++ b/diracx/templates/NOTES.txt @@ -16,6 +16,10 @@ Then see the chart README for more information on how to use kubectl/helm. export DIRACX_URL={{ .Values.developer.urls.diracx }} export DIRACX_CA_PATH={{ .Values.developer.demoDir }}/demo-ca.pem +i To use the demo with a DiracX client without local installation: + + kubectl exec -it deployment/diracx-demo-cli -- bash + ℹī¸ To access the web application visit: {{ .Values.developer.urls.diracx }} @@ -31,7 +35,7 @@ Then see the chart README for more information on how to use kubectl/helm. i Grafana dashboard for telemetry (if enabled) - {{ .Values.developer.urls.diracx }}:32004 + {{ .Values.developer.urls.grafana }} Username: admin Password: run ``kubectl get secrets diracx-demo-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo`` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e3007c4 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,13 @@ +TODO: Chris H + +Quick intro to kunernetes: + links and concept of what you need to know (pods, deployment, replicas, jobs, etc) + +Quick intro to helm + templating language to generate yaml files understood by k8 + +What does this chart contains: + deployments for diracx, diracx-web + dependencies + +Initialization steps: diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md new file mode 100644 index 0000000..42605b7 --- /dev/null +++ b/docs/REFERENCE.md @@ -0,0 +1,7 @@ +# How the chart operates + + * secret generations + * CS creation + * dex + * DB/sandbox/OSDB init + * wait for the dbs to be ready diff --git a/docs/RUN_DEMO.md b/docs/RUN_DEMO.md new file mode 100644 index 0000000..c4e108f --- /dev/null +++ b/docs/RUN_DEMO.md @@ -0,0 +1,47 @@ +# Details of ``run_demo.sh`` + +## What ``run_demo.sh`` does + +In order to run the ``diracx charts`` locally, this script: +* downloads various utilities (``kind``, ``helm``, ``kubectl``, etc) +* Starts a local kubernetes using [kind](https://kind.sigs.k8s.io/) +* Installs the ``chart`` using ``helm``, enabling all the dependencies (DBs, IdP, Object store, etc) +* Generate the initial configuration for all the dependencies and ``diracx`` (db credentials, urls of services, create admin users, etc) + +All this relies on templated configuration in the [demo](../demo/) directory. A temporary folder (``diracx-charts/.demo``) is used to generate the actual config and host various tools. It is important for this directory to have a deterministic location as it is used by the ``diracx`` integration tests. + +## Mounted containers + +``kind`` creates a docker container, and runs kubernetes inside. In order to avoid that ``kind`` downloads the ``diracx`` and dependencies images everytime, ``run_demo.sh`` creates a docker volume ``diracx-demo-containerd`` that is mounted in the container in which the images are stored. +This volume could grow very large, do not forget to clean it up regularely, as suggested by the ``run_demo.sh`` script + +```bash +⚠ī¸ Volume for containerd is 21 GB, if you want to save space shutdown the demo and run "docker volume rm diracx-demo-containerd" +``` + +## DiracX configuration + +The configuration yaml used by the ``diracx`` service is a mounted directory: ``diracx-charts/.demo/cs-mount``. This means that if you want to change the configuration of diracx, you can just edit and ``git commit`` this file. + +## Coverage volume + +In order for the ``diracx CI`` to collect and aggregate coverage report, a local path is mounted inside the container ``diracx-charts/.demo/coverage-reports``. + +## Mounted python module + +Because you may want to test changes in ``diracx`` itself, or ``DIRAC`` or any other python package, listing these packages at the end of the ``run_demo.sh`` command line will mount these directories and (by default) perform an editable install of these packages. + +Effectively, that means that you can do ``diracx-charts/run_demo.sh ``, edit the code of your ``diracx`` checkout, and see it run directly in the demo. + +## Mounted node module +Because you may want to test changes in ``diracx-web`` itself, appending the package at the end of the ``run_demo.sh`` command line will mount the directory and (by default) perform an editable install of the package. +Effectively, that means that you can do ``diracx-charts/run_demo.sh ``, edit the code of your ``diracx-web`` checkout, and see it run directly in the demo. + +## CA certificates + +The ``run_demo.sh`` generates a self signed certificate and dumps it in ``diracx-charts/.demo/demo-ca.pem`` to allow for a local client to interact with it. + + +## Secret generation + +Multiple secrets are needed for ``diracx`` to run. In the case of the demo, they are auto generated, and are persisted during ``helm upgrade`` diff --git a/run_demo.sh b/run_demo.sh index ae8930b..cb10603 100755 --- a/run_demo.sh +++ b/run_demo.sh @@ -101,7 +101,7 @@ usage="${0##*/} [-h|--help] [--exit-when-done] [--offline] [--enable-coverage] [ usage+="\n\n" usage+=" -h|--help: Print this help message and exit\n" usage+=" --exit-when-done: Exit after the demo has been started (it will be left running in the background)\n" -usage+=" --enable-coverage: Enable coverage reporting\n" +usage+=" --enable-coverage: Enable coverage reporting (used by diracx CI)\n" usage+=" --no-editable-python: Do not install Python source directories in editable mode\n" usage+=" --offline: Run in a mode which is suitable for fully offline use.\n" usage+=" WARNING: This may result in some weird behaviour, see the demo documentation for details.\n"