doc/install/arvados-on-kubernetes.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Arvados on Kubernetes
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 Arvados on Kubernetes is implemented as a Helm chart.
  13
  14 {% include 'notebox_begin_warning' %}
  15 This Helm chart does not retain any state after it is deleted. An Arvados cluster spun up with this Helm Chart is entirely ephemeral, and all data stored on the cluster will be deleted when it is shut down. This will be fixed in a future version.
  16 {% include 'notebox_end' %}
  17
  18 h2. Requirements
  19
  20 * Kubernetes 1.10+ cluster with at least 3 nodes, 2 or more cores per node
  21 * `kubectl` and `helm` installed locally, and able to connect to your Kubernetes cluster
  22
  23 If that does not describe your environment, please see the "GKE":#GKE or "Minikube":#Minikube sections below to get set up with Kubernetes.
  24
  25 h2(#helm). Install helm on the Kubernetes cluster
  26
  27 If you already have helm running on the Kubernetes cluster, proceed directly to "Start the Arvados cluster":#Start below.
  28
  29 <pre>
  30 $ helm init
  31 $ kubectl create serviceaccount --namespace kube-system tiller
  32 $ kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
  33 $ kubectl patch deploy --namespace kube-system tiller-deploy -p '{"spec":{"template":{"spec":{"serviceAccount":"tiller"}}}}'
  34 </pre>
  35
  36 Test `helm` by running
  37
  38 <pre>
  39 $ helm ls
  40 </pre>
  41
  42 There should be no errors. The command will return nothing.
  43
  44 h2(#Start). Start the Arvados cluster
  45
  46 First, determine the IP address that the Arvados cluster will use to expose its API, Workbench, etc. If you want this Arvados cluster to be reachable from places other than the local machine, the IP address will need to be routable as appropriate.
  47
  48 <pre>
  49 $ git clone https://github.com/curoverse/arvados-kubernetes.git
  50 $ cd arvados-kubernetes/charts/arvados
  51 $ ./cert-gen.sh <IP ADDRESS>
  52 </pre>
  53
  54 The `values.yaml` file contains a number of variables that can be modified.
  55 Specifically, you probably want to modify the values for
  56
  57 <pre>
  58   adminUserEmail
  59   adminUserPassword
  60   superUserSecret
  61   anonymousUserSecret
  62 </pre>
  63
  64 Now start the Arvados cluster:
  65
  66 <pre>
  67 $ helm install --name arvados . --set externalIP=<IP ADDRESS>
  68 </pre>
  69
  70 At this point, you can use kubectl to see the Arvados cluster boot:
  71
  72 <pre>
  73 $ kubectl get pods
  74 $ kubectl get svc
  75 </pre>
  76
  77 After a few minutes, you can access Arvados Workbench at the IP address specified
  78
  79 * https://&lt;IP ADDRESS&gt;
  80
  81 with the username and password specified in the `values.yaml` file.
  82
  83 Alternatively, use the Arvados cli tools or SDKs:
  84
  85 Set the environment variables:
  86
  87 <pre>
  88 $ export ARVADOS_API_TOKEN=<superUserSecret from values.yaml>
  89 $ export ARVADOS_API_HOST=<STATIC IP>:444
  90 $ export ARVADOS_API_HOST_INSECURE=true
  91 </pre>
  92
  93 Test access with:
  94
  95 <pre>
  96 $ arv user current
  97 </pre>
  98
  99 h2. Reload
 100
 101 If you make changes to the Helm chart (e.g. to `values.yaml`), you can reload Arvados with
 102
 103 <pre>
 104 $ helm upgrade arvados .
 105 </pre>
 106
 107 h2. Shut down
 108
 109 {% include 'notebox_begin_warning' %}
 110 This Helm chart does not retain any state after it is deleted. An Arvados cluster spun up with this Helm Chart is entirely ephemeral, and <strong>all data stored on the Arvados cluster will be deleted</strong> when it is shut down. This will be fixed in a future version.
 111 {% include 'notebox_end' %}
 112
 113 <pre>
 114 $ helm del arvados --purge
 115 </pre>
 116
 117 h2(#GKE). GKE
 118
 119 h3. Install tooling
 120
 121 Install `gcloud`:
 122
 123 * Follow the instructions at "https://cloud.google.com/sdk/downloads":https://cloud.google.com/sdk/downloads
 124
 125 Install `kubectl`:
 126
 127 <pre>
 128 $ gcloud components install kubectl
 129 </pre>
 130
 131 Install `helm`:
 132
 133 * Follow the instructions at "https://docs.helm.sh/using_helm/#installing-helm":https://docs.helm.sh/using_helm/#installing-helm
 134
 135 h3. Boot the GKE cluster
 136
 137 This can be done via the "cloud console":https://console.cloud.google.com/kubernetes/ or via the command line:
 138
 139 <pre>
 140 $ gcloud container clusters create <CLUSTERNAME> --zone us-central1-a --machine-type n1-standard-2 --cluster-version 1.10.2-gke.3
 141 </pre>
 142
 143 It takes a few minutes for the cluster to be initialized.
 144
 145 h3. Reserve a static IP
 146
 147 Reserve a "static IP":https://console.cloud.google.com/networking/addresses in GCE. Make sure the IP is in the same region as your GKE cluster, and is of the "Regional" type.
 148
 149 h3. Connect to the GKE cluster.
 150
 151 Via the web:
 152 * Click the "Connect" button next to your "GKE cluster"https://console.cloud.google.com/kubernetes/.
 153 * Execute the "Command-line access" command on your development machine.
 154
 155 Alternatively, use this command:
 156
 157 <pre>
 158 $ gcloud container clusters get-credentials <CLUSTERNAME> --zone us-central1-a --project <YOUR-PROJECT>
 159 </pre>
 160
 161 Test the connection:
 162
 163 <pre>
 164 $ kubectl get nodes
 165 </pre>
 166
 167 Now proceed to the "Install helm on the Kubernetes cluster":#helm section.
 168
 169 h2(#Minikube). Minikube
 170
 171 h3. Install tooling
 172
 173 Install `kubectl`:
 174
 175 * Follow the instructions at "https://kubernetes.io/docs/tasks/tools/install-kubectl/":https://kubernetes.io/docs/tasks/tools/install-kubectl/
 176
 177 Install `helm`:
 178
 179 * Follow the instructions at "https://docs.helm.sh/using_helm/#installing-helm":https://docs.helm.sh/using_helm/#installing-helm
 180
 181 h3. Install Minikube
 182
 183 Follow the instructions at "https://kubernetes.io/docs/setup/minikube/":https://kubernetes.io/docs/setup/minikube/
 184
 185 Test the connection:
 186
 187 <pre>
 188 $ kubectl get nodes
 189 </pre>
 190
 191 Now proceed to the "Install helm on the Kubernetes cluster":#helm section.