charts/arvados/README.md

   1 [//]: # Copyright (C) The Arvados Authors. All rights reserved.
   2 [//]: #
   3 [//]: # SPDX-License-Identifier: Apache-2.0
   4
   5 # Arvados Helm Chart
   6
   7 This directory contains a simple Helm chart for Arvados, excluding the Git
   8 server. This is an initial version, there is (a lot of) room for improvement.
   9
  10 **WARNING**
  11
  12 This Helm chart does not retain any state after it is deleted. An Arvados
  13 cluster spun up with this Helm Chart is entirely ephemeral.
  14
  15 **/WARNING**
  16
  17 ## Usage example (GKE)
  18
  19 1. Install `gcloud`, `kubectl`, and `helm` on your development machine.
  20    `gcloud` is used to setup the connection to your GKE cluster. `kubectl` is
  21    used to interact with the Kubernetes cluster. `helm` is used to deploy to
  22    the cluster.
  23      - Follow the instructions [here](https://cloud.google.com/sdk/downloads) to install `gcloud`.
  24      - `gcloud components install kubectl` to install `kubectl`.
  25      - Follow the instructions [here](//docs.helm.sh/using_helm/#installing-helm) to install `helm`.
  26      - If that doesn't work, see the official installation instructions for
  27        [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl)
  28        and [helm](https://docs.helm.sh/using_helm/#installing-helm).
  29
  30 2. Boot a [GKE cluster](https://console.cloud.google.com/kubernetes/) with at
  31    least 3 nodes, n1-standard-2 or larger.
  32
  33    Kubernetes 1.10 is required, because this chart uses the binaryData configmap feature.
  34
  35    It is also possible to boot the cluster from the command line:
  36
  37      gcloud container clusters create <CLUSTERNAME> --zone us-central1-a --machine-type n1-standard-2 --cluster-version 1.10.2-gke.3
  38
  39    It takes a few minutes for the cluster to be initialized.
  40
  41 3. Reserve a [static IP](https://console.cloud.google.com/networking/addresses) in GCE.
  42     - Make sure the IP is in the same region as your GKE cluster, and is of the
  43       "Regional" type.
  44
  45 4. Connect to the GKE cluster.
  46
  47    Web:
  48     - Click the "Connect" button next to your [GKE cluster](https://console.cloud.google.com/kubernetes/).
  49     - Execute the "Command-line access" command on your development machine.
  50
  51    Alternatively, use this command:
  52     - gcloud container clusters get-credentials <CLUSTERNAME> --zone us-central1-a --project <YOUR-PROJECT>
  53
  54   Test:
  55     - Run `kubectl get nodes` to test your connection to the GKE cluster. The
  56       nodes you specified in step 2 should show up in the output.
  57
  58 4. Install `helm` on the cluster.
  59     - Run the following commands from your development machine. The last three
  60       commands are necessary since GKE clusters use RBAC for authentication, so
  61       the default `helm` installation doesn't have sufficient permissions to
  62       deploy to the cluster:
  63         - `helm init`
  64         - `kubectl create serviceaccount --namespace kube-system tiller`
  65         - `kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller`
  66         - `kubectl patch deploy --namespace kube-system tiller-deploy -p '{"spec":{"template":{"spec":{"serviceAccount":"tiller"}}}}'`
  67     - Wait until the `tiller` container's status is "Running" in `kubectl get pods --namespace kube-system`
  68     - Test `helm` by running `helm ls`. There shouldn't be any errors.
  69
  70 5. Generate an SSL certificate.
  71     - Run `./cert-gen.sh <STATIC IP>` where `<STATIC IP>` is the IP allocated in step 1.
  72
  73 6. *Optional*: Trust the generated certificate. By default, browsers treat
  74    self-signed certificates as insecure. Therefore, the generated certificate
  75    must be manually trusted through the OS settings.  If you skip this step,
  76    you'll have to manually override browser SSL warnings when connecting to
  77    workbench.
  78
  79    To do this on On Mac OS:
  80    1. Open the "Keychain Access" application.
  81    2. Click "File" in the menu at the top left.
  82    3. Click "Import Items...".
  83    4. Navigate to the generated `cert` and click "Open".
  84    5. Double click on the certificate and change the trust level to "Always
  85       Trust". The certificate will be named "arvados-test-cert".
  86
  87 7. Install the Arvados Kubernetes configs.
  88     - Run `helm install --name arvados . --set externalIP=<YOUR-OFFICIAL-IP>`
  89     - If you make a change to the Kubernetes manifests and want to reinstall
  90       the configs, run `helm delete --purge arvados`, followed by the `helm
  91       install` command.
  92
  93 8. Wait for everything to boot in the cluster. This takes about 5 minutes.
  94     - `kubectl get pods` should show all the pods as running.
  95     - `kubectl get services` shouldn't show anything as `<pending>`.
  96         - If some services are stuck in `<pending>` check their status with
  97           `kubectl describe service/serviceName` (e.g. `kubectl describe
  98           service/arvados-api-server`). If there's an error along the lines of
  99           "Specified IP address is in-use and would result in a conflict.",
 100           manually delete all entries under "Forwarding rules" and "Target
 101           pools" in the [console UI](https://console.cloud.google.com/net-services/loadbalancing/advanced/targetPools/list).
 102     - Even after the containers are running, they take a couple minutes to
 103       download and install various packages. If some component seem down,
 104       check its logs with `kubectl logs <POD NAME>` and see if it's fully
 105       initialized.
 106
 107 10. Connect to Workbench:
 108     - Navigate to `https://<STATIC IP>` in your browser. Use the username and
 109       password specified in values.yaml to log in.
 110
 111     Alternatively, use the Arvados cli tools or SDKs:
 112
 113     Set the environment variables properly:
 114
 115     ARVADOS_API_TOKEN=<superUserSecret from values.yaml>
 116     ARVADOS_API_HOST=<STATIC IP>:444
 117     ARVADOS_API_HOST_INSECURE=true
 118
 119 11. Destroy the GKE cluster when finished, via the web or command line:
 120     - helm del arvados --purge
 121     - gcloud container clusters delete <CLUSTERNAME> --zone us-central1-a
 122
 123 ## Future Work
 124
 125 - Add an option to use an external PostgreSQL database
 126 - Add an option to use an external Keep storage backend
 127 - Add Arvados Docker Cleaner to the compute nodes.
 128 - Figure out how to reduce redundant YAML files.
 129     - The Nginx SSL proxies (`./templates/keep-web-https.yaml`,
 130       `./templates/keep-proxy-https.yaml`, `./templates/ws-https.yaml`) are
 131       extremely similar. Only a couple lines related to hostnames and
 132       ports different.
 133     - The configmap YAMLs are all basically the same.
 134     - This might be possible with partials (a Helm templating feature). Or in a
 135       different templating language such as ksonnet.
 136 - Support changing keep-store scale. Right now the scale is set to `replicas:
 137   2` in `templates/keep-store-deployment.yaml`. Unfortunately, increasing the scale
 138   isn't as simple as changing the number since the hostnames are hardcoded in
 139   `config/shell-server/99-init-keep.sh`.
 140 - Consider adding healthchecks and readiness checks.
 141     - They would make the deployment more robust. Readiness checks would make
 142       it so services weren't exposed until they're ready to receive traffic.
 143       Healthchecks would make it so containers are restarted when they enter a
 144       failure state.
 145 - Add minimum CPU and RAM requirements to the containers.
 146     - This will prevent out of memory errors, for example. This is especially
 147       important if autoscaling is added.
 148 - Get the SSL certificate automatically using Lets Encrypt, eliminating the
 149   need for the self-signed certificate generated by the `cert-gen.sh` script.