20665: Provides examples on how to securely handle the secrets file.
[arvados.git] / doc / install / salt-multi-host.html.textile.liquid
1 ---
2 layout: default
3 navsection: installguide
4 title: Multi-Host Arvados
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 # "Introduction":#introduction
13 # "Prerequisites and planning":#prerequisites
14 # "Download the installer":#download
15 # "Initialize the installer":#copy_config
16 # "Set up your infrastructure":#setup-infra
17 ## "Create AWS infrastructure with Terraform":#terraform
18 ## "Create required infrastructure manually":#inframanual
19 # "Edit local.params* files":#localparams
20 # "Configure Keep storage":#keep
21 # "Choose the SSL configuration":#certificates
22 ## "Using a Let's Encrypt certificates":#lets-encrypt
23 ## "Bring your own certificates":#bring-your-own
24 # "Create a compute image":#create_a_compute_image
25 # "Begin installation":#installation
26 # "Further customization of the installation":#further_customization
27 # "Confirm the cluster is working":#test-install
28 ## "Debugging issues":#debugging
29 ## "Iterating on config changes":#iterating
30 ## "Common problems and solutions":#common-problems
31 # "Initial user and login":#initial_user
32 # "Monitoring and Metrics":#monitoring
33 # "After the installation":#post_install
34
35 h2(#introduction). Introduction
36
37 This multi host installer is the recommendend way to set up a production Arvados cluster.  These instructions include specific details for installing on Amazon Web Services (AWS), which are marked as "AWS specific".  However with additional customization the installer can be used as a template for deployment on other cloud provider or HPC systems.
38
39 h2(#prerequisites). Prerequisites and planning
40
41 h3. Cluster ID and base domain
42
43 Choose a 5-character cluster identifier that will represent the cluster.  Here are "guidelines on choosing a cluster identifier":../architecture/federation.html#cluster_id .  Only lowercase letters and digits 0-9 are allowed.  Examples will use @xarv1@ or @${CLUSTER}@, you should substitute the cluster id you have selected.
44
45 Determine the base domain for the cluster.  This will be referred to as @${DOMAIN}@.
46
47 For example, if DOMAIN is @xarv1.example.com@, then @controller.${DOMAIN}@ means @controller.xarv1.example.com@.
48
49 h3(#DNS). DNS hostnames for each service
50
51 You will need a DNS entry for each service.  When using the "Terraform script":#terraform to set up your infrastructure, these domains will be created automatically using AWS Route 53.
52
53 In the default configuration these are:
54
55 # @controller.${DOMAIN}@
56 # @ws.${DOMAIN}@
57 # @keep0.${DOMAIN}@
58 # @keep1.${DOMAIN}@
59 # @keep.${DOMAIN}@
60 # @download.${DOMAIN}@
61 # @*.collections.${DOMAIN}@  -- important note, this must be a wildcard DNS, resolving to the @keepweb@ service
62 # @workbench.${DOMAIN}@
63 # @workbench2.${DOMAIN}@
64 # @webshell.${DOMAIN}@
65 # @shell.${DOMAIN}@
66 # @prometheus.${DOMAIN}@
67 # @grafana.${DOMAIN}@
68
69 For more information, see "DNS entries and TLS certificates":install-manual-prerequisites.html#dnstls.
70
71 h2(#download). Download the installer
72
73 {% assign local_params_src = 'multiple_hosts' %}
74 {% assign config_examples_src = 'multi_host/aws' %}
75 {% assign terraform_src = 'terraform/aws' %}
76 {% include 'download_installer' %}
77
78 h2(#setup-infra). Set up your infrastructure
79
80 ## "Create AWS infrastructure with Terraform":#terraform
81 ## "Create required infrastructure manually":#inframanual
82
83 h3(#terraform). Create AWS infrastructure with Terraform (AWS specific)
84
85 We provide a set of Terraform code files that you can run to create the necessary infrastructure on Amazon Web Services.
86
87 These files are located in the @terraform@ installer directory and are divided in three sections:
88
89 # The @terraform/vpc/@ subdirectory controls the network related infrastructure of your cluster, including firewall rules and split-horizon DNS resolution.
90 # The @terraform/data-storage/@ subdirectory controls the stateful part of your cluster, currently only sets up the S3 bucket for holding the Keep blocks and in the future it'll also manage the database service.
91 # The @terraform/services/@ subdirectory controls the hosts that will run the different services on your cluster, makes sure that they have the required software for the installer to do its job.
92
93 h4. Software requirements & considerations
94
95 {% include 'notebox_begin' %}
96 The Terraform state files (that keep crucial infrastructure information from the cloud) will be saved inside each subdirectory, under the @terraform.tfstate@ name.  These will be committed to the git repository used to coordinate deployment.  It is very important to keep this git repository secure, only sysadmins that will be responsible for maintaining your Arvados cluster should have access to it.
97 {% include 'notebox_end' %}
98
99 h4. Terraform code configuration
100
101 Each section described above contain a @terraform.tfvars@ file with some configuration values that you should set before applying each configuration. You should at least set the AWS region, cluster prefix and domain name in @terraform/vpc/terraform.tfvars@:
102
103 <pre><code>{% include 'terraform_vpc_tfvars' %}</code></pre>
104
105 If you don't set the main configuration variables at @vpc/terraform.tfvars@ file, you will be asked to re-enter these parameters every time you run Terraform.
106
107 The @data-storage/terraform.tfvars@ and @services/terraform.tfvars@ let you configure additional details, including the SSH public key for deployment, instance & volume sizes, etc. All these configurations are provided with sensible defaults:
108
109 <pre><code>{% include 'terraform_datastorage_tfvars' %}</code></pre>
110
111 <pre><code>{% include 'terraform_services_tfvars' %}</code></pre>
112
113 h4. Set credentials
114
115 You will need an AWS access key and secret key to create the infrastructure.
116
117 <pre><code>$ export AWS_ACCESS_KEY_ID="anaccesskey"
118 $ export AWS_SECRET_ACCESS_KEY="asecretkey"</code></pre>
119
120 h4. Create the infrastructure
121
122 Build the infrastructure by running @./installer.sh terraform@.  The last stage will output the information needed to set up the cluster's domain and continue with the installer. for example:
123
124 <pre><code>$ ./installer.sh terraform
125 ...
126 Apply complete! Resources: 16 added, 0 changed, 0 destroyed.
127
128 Outputs:
129
130 arvados_sg_id = "sg-02f999a99973999d7"
131 arvados_subnet_id = "subnet-01234567abc"
132 cluster_int_cidr = "10.1.0.0/16"
133 cluster_name = "xarv1"
134 compute_subnet_id = "subnet-abcdef12345"
135 deploy_user = "admin"
136 domain_name = "xarv1.example.com"
137 letsencrypt_iam_access_key_id = "AKAA43MAAAWAKAADAASD"
138 private_ip = {
139   "controller" = "10.1.1.1"
140   "keep0" = "10.1.1.3"
141   "keep1" = "10.1.1.4"
142   "keepproxy" = "10.1.1.2"
143   "shell" = "10.1.1.7"
144   "workbench" = "10.1.1.5"
145 }
146 public_ip = {
147   "controller" = "18.235.116.23"
148   "keep0" = "34.202.85.86"
149   "keep1" = "38.22.123.98"
150   "keepproxy" = "34.231.9.201"
151   "shell" = "44.208.155.240"
152   "workbench" = "52.204.134.136"
153 }
154 region_name = "us-east-1"
155 route53_dns_ns = tolist([
156   "ns-1119.awsdns-11.org",
157   "ns-1812.awsdns-34.co.uk",
158   "ns-437.awsdns-54.com",
159   "ns-809.awsdns-37.net",
160 ])
161 ssl_password_secret_name = "xarv1-arvados-ssl-privkey-password"
162 vpc_id = "vpc-0999994998399923a"
163 letsencrypt_iam_secret_access_key = "XXXXXSECRETACCESSKEYXXXX"
164 </code></pre>
165
166
167 h4. Additional DNS configuration
168
169 Once Terraform has completed, the infrastructure for your Arvados cluster is up and running.  One last piece of DNS configuration is required.
170
171 The domain names for your cluster (e.g.: controller.xarv1.example.com) are managed via "Route 53":https://aws.amazon.com/route53/ and the TLS certificates will be issued using "Let's Encrypt":https://letsencrypt.org/ .
172
173 You need to configure the parent domain to delegate to the newly created zone.  For example, you need to configure "example.com" to delegate the subdomain "xarv1.example.com" to the nameservers for the Arvados hostname records created by Terraform.  You do this by creating a @NS@ record on the parent domain that refers to the name servers listed in the Terraform output parameter @route53_dns_ns@.
174
175 If your parent domain is also controlled by Route 53, the process will be like this:
176
177 # Log in to the AWS Console and navigate to the service page for *Route 53*
178 # Go to the list of *Hosted zones* and click on the zone for the parent domain
179 # Click on *Create record*
180 # For *Record name* put the cluster id
181 # For *Record type* choose @NS - Name servers for a hosted zone@
182 # For *Value* add the values from Terraform output parameter @route53_dns_ns@, one hostname per line, with punctuation (quotes and commas) removed.
183 # Click *Create records*
184
185 If the parent domain is controlled by some other service, follow the guide for the the appropriate service.
186
187 h4. Other important output parameters
188
189 The certificates will be requested from Let's Encrypt when you run the installer.
190
191 * @cluster_int_cidr@ will be used to set @CLUSTER_INT_CIDR@
192
193 * You'll also need @compute_subnet_id@ and @arvados_sg_id@ to set @DriverParameters.SubnetID@ and @DriverParameters.SecurityGroupIDs@ in @local_config_dir/pillars/arvados.sls@ and when you "create a compute image":#create_a_compute_image.
194
195 You can now proceed to "edit local.params* files":#localparams.
196
197 h3(#inframanual). Create required infrastructure manually
198
199 If you will be setting up infrastructure without using the provided Terraform script, here are the recommendations you will need to consider.
200
201 h4. Virtual Private Cloud (AWS specific)
202
203 We recommend setting Arvados up in its own "Virtual Private Cloud (VPC)":https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html
204
205 When you do so, you need to configure a couple of additional things:
206
207 # "Create a subnet for the compute nodes":https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html
208 # You should set up a "security group which allows SSH access (port 22)":https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html
209 # Make sure to add a "VPC S3 endpoint":https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html
210
211 h4(#keep-bucket). S3 Bucket (AWS specific)
212
213 We recommend "creating an S3 bucket":https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html for data storage named @${CLUSTER}-nyw5e-000000000000000-volume@.  We recommend creating an IAM role called @${CLUSTER}-keepstore-00-iam-role@ with a "policy that can read, write, list and delete objects in the bucket":configure-s3-object-storage.html#IAM .  With the example cluster id @xarv1@ the bucket would be called @xarv1-nyw5e-000000000000000-volume@ and the role would be called @xarv1-keepstore-00-iam-role@.
214
215 These names are recommended because they are default names used in the configuration template.  If you use different names, you will need to edit the configuration template later.
216
217 h4(#hosts). Required hosts
218
219 You will need to allocate several hosts (physical or virtual machines) for the fixed infrastructure of the Arvados cluster.  These machines should have at least 2 cores and 8 GiB of RAM, running a supported Linux distribution.
220
221 {% include 'supportedlinux' %}
222
223 Allocate the following hosts as appropriate for your site.  On AWS you may choose to do it manually with the AWS console, or using a DevOps tool such as CloudFormation or Terraform.  With the exception of "keep0" and "keep1", all of these hosts should have external (public) IP addresses if you intend for them to be accessible outside of the private network or VPC.
224
225 The installer will set up the Arvados services on your machines.  Here is the default assignment of services to machines:
226
227 # API node
228 ## postgresql server
229 ## arvados api server
230 ## arvados controller  (recommendend hostname @controller.${DOMAIN}@)
231 ## arvados websocket   (recommendend hostname @ws.${DOMAIN}@)
232 ## arvados cloud dispatcher
233 ## arvados keepbalance
234 # KEEPSTORE nodes (at least 1 if using S3 as a Keep backend, else 2)
235 ## arvados keepstore   (recommendend hostnames @keep0.${DOMAIN}@ and @keep1.${DOMAIN}@)
236 # KEEPPROXY node
237 ## arvados keepproxy   (recommendend hostname @keep.${DOMAIN}@)
238 ## arvados keepweb     (recommendend hostname @download.${DOMAIN}@ and @*.collections.${DOMAIN}@)
239 # WORKBENCH node
240 ## arvados workbench   (recommendend hostname @workbench.${DOMAIN}@)
241 ## arvados workbench2  (recommendend hostname @workbench2.${DOMAIN}@)
242 ## arvados webshell    (recommendend hostname @webshell.${DOMAIN}@)
243 # SHELL node  (optional)
244 ## arvados shell       (recommended hostname @shell.${DOMAIN}@)
245
246 When using the database installed by Arvados (and not an "external database":#ext-database), the database is stored under @/var/lib/postgresql@.  Arvados logs are also kept in @/var/log@ and @/var/www/arvados-api/shared/log@.  Accordingly, you should ensure that the disk partition containing @/var@ has adequate storage for your planned usage.  We suggest starting with 50GiB of free space on the database host.
247
248 h4. Additional prerequisites when preparing machines to run the installer
249
250 # From the account where you are performing the install, passwordless @ssh@ to each machine
251 This means the client's public key should added to @~/.ssh/authorized_keys@ on each node.
252 # Passwordless @sudo@ access on the account on each machine you will @ssh@ in to
253 This usually means adding the account to the @sudo@ group and having a rule like this in @/etc/sudoers.d/arvados_passwordless@ that allows members of group @sudo@ to execute any command without entering a password.
254 <pre>%sudo ALL=(ALL:ALL) NOPASSWD:ALL</pre>
255 # @git@ installed on each machine
256 # Port 443 reachable by clients
257
258 (AWS specific) The machine that runs the arvados cloud dispatcher will need an "IAM role that allows it to manage EC2 instances.":{{site.baseurl}}/install/crunch2-cloud/install-dispatch-cloud.html#IAM
259
260 If your infrastructure differs from the setup proposed above (ie, different hostnames), you can still use the installer, but "additional customization may be necessary":#further_customization .
261
262 h2(#localparams). Edit @local.params*@ files
263
264 The cluster configuration parameters are included in two files: @local.params@ and @local.params.secrets@. These files can be found wherever you choose to initialize the installation files (e.g., @~/setup-arvados-xarv1@ in these examples).
265
266 The @local.params.secrets@ file is intended to store security-sensitive data such as passwords, private keys, tokens, etc. Depending on the security requirements of the cluster deployment, you may wish to store this file in a secrets store like AWS secrets manager or Jenkins credentials.
267
268 h3. Parameters from @local.params@:
269
270 # Set @CLUSTER@ to the 5-character cluster identifier (e.g "xarv1")
271 # Set @DOMAIN@ to the base DNS domain of the environment, e.g. "xarv1.example.com"
272 # Set the @*_INT_IP@ variables with the internal (private) IP addresses of each host. Since services share hosts, some hosts are the same.  See "note about /etc/hosts":#etchosts
273 # Edit @CLUSTER_INT_CIDR@, this should be the CIDR of the private network that Arvados is running on, e.g. the VPC.  If you used terraform, this is emitted as @cluster_int_cidr@.
274 _CIDR stands for "Classless Inter-Domain Routing" and describes which portion of the IP address that refers to the network.  For example 192.168.3.0/24 means that the first 24 bits are the network (192.168.3) and the last 8 bits are a specific host on that network._
275 _AWS Specific: Go to the AWS console and into the VPC service, there is a column in this table view of the VPCs that gives the CIDR for the VPC (IPv4 CIDR)._
276 # Set @INITIAL_USER_EMAIL@ to your email address, as you will be the first admin user of the system.
277
278 h3. Parameters from @local.params.secrets@:
279
280 # Set each @KEY@ / @TOKEN@ / @PASSWORD@ to a random string.  You can use @installer.sh generate-tokens@
281 <pre><code>$ ./installer.sh generate-tokens
282 BLOB_SIGNING_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
283 MANAGEMENT_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
284 SYSTEM_ROOT_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
285 ANONYMOUS_USER_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
286 WORKBENCH_SECRET_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
287 DATABASE_PASSWORD=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
288 </code></pre>
289 # Set @DATABASE_PASSWORD@ to a random string (unless you "already have a database":#ext-database then you should set it to that database's password)
290    Important! If this contains any non-alphanumeric characters, in particular ampersand ('&'), it is necessary to add backslash quoting.
291    For example, if the password is @Lq&MZ<V']d?j@
292    With backslash quoting the special characters it should appear like this in local.params:
293 <pre><code>DATABASE_PASSWORD="Lq\&MZ\<V\'\]d\?j"</code></pre>
294 # Set @DISPATCHER_SSH_PRIVKEY@ to a SSH private key that @arvados-dispatch-cloud@ will use to connect to the compute nodes:
295 <pre><code>DISPATCHER_SSH_PRIVKEY="-----BEGIN OPENSSH PRIVATE KEY-----
296 b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABlwAAAAdzc2gtcn
297 ...
298 s4VY40kNxs6MsAAAAPbHVjYXNAaW5zdGFsbGVyAQIDBA==
299 -----END OPENSSH PRIVATE KEY-----"
300 </code></pre>You can create one by following the steps described on the "building a compute node documentation":{{site.baseurl}}/install/crunch2-cloud/install-compute-node.html#sshkeypair page.
301
302 h3(#etchosts). Note on @/etc/hosts@
303
304 Because Arvados services are typically accessed by external clients, they are likely to have both a public IP address and a internal IP address.
305
306 On cloud providers such as AWS, sending internal traffic to a service's public IP address can incur egress costs and throttling.  Thus it is very important for internal traffic to stay on the internal network.  The installer implements this by updating @/etc/hosts@ on each node to associate each service's hostname with the internal IP address, so that when Arvados services communicate with one another, they always use the internal network address.  This is NOT a substitute for DNS, you still need to set up DNS names for all of the services that have public IP addresses (it does, however, avoid a complex "split-horizon" DNS configuration).
307
308 It is important to be aware of this because if you mistype the IP address for any of the @*_INT_IP@ variables, hosts may unexpectedly fail to be able to communicate with one another.  If this happens, check and edit as necessary the file @/etc/hosts@ on the host that is failing to make an outgoing connection.
309
310 h2(#keep). Configure Keep storage
311
312 The @multi_host/aws@ template uses S3 for storage.  Arvados also supports "filesystem storage":configure-fs-storage.html and "Azure blob storage":configure-azure-blob-storage.html .  Keep storage configuration can be found in in the @arvados.cluster.Volumes@ section of @local_config_dir/pillars/arvados.sls@.
313
314 h3. Object storage in S3 (AWS Specific)
315
316 Open @local_config_dir/pillars/arvados.sls@ and edit as follows:
317
318 # In the @arvados.cluster.Volumes.DriverParameters@ section, set @Region@ to the appropriate AWS region (e.g. 'us-east-1')
319
320 If "followed the recommendend naming scheme":#keep-bucket for both the bucket and role (or used the provided Terraform script), you're done.
321
322 If you did not follow the recommendend naming scheme for either the bucket or role, you'll need to update these parameters as well:
323
324 # Set @Bucket@ to the value of "keepstore bucket you created earlier":#keep-bucket
325 # Set @IAMRole@ to "keepstore role you created earlier":#keep-bucket
326
327 {% include 'ssl_config_multi' %}
328
329 h2(#authentication). Configure your authentication provider (optional, recommended)
330
331 By default, the installer will use the "Test" provider, which is a list of usernames and cleartext passwords stored in the Arvados config file.  *This is low security configuration and you are strongly advised to configure one of the other "supported authentication methods":setup-login.html* .
332
333 h2(#ext-database). Using an external database (optional)
334
335 The standard behavior of the installer is to install and configure PostgreSQL for use by Arvados.  You can optionally configure it to use a separately managed database instead.
336
337 Arvados requires a database that is compatible with PostgreSQL 9.5 or later.  For example, Arvados is known to work with Amazon Aurora (note: even idle, Arvados services will periodically poll the database, so we strongly advise using "provisioned" mode).
338
339 # In @local.params@, remove 'database' from the list of roles assigned to the controller node:
340 <pre><code>NODES=(
341   [controller.${DOMAIN}]=api,controller,websocket,dispatcher,keepbalance
342   ...
343 )
344 </code></pre>
345 # In @local.params@, set @DATABASE_INT_IP@ to the database endpoint (can be a hostname, does not have to be an IP address).
346 <pre><code>DATABASE_INT_IP=...
347 </code></pre>
348 # In @local.params@, set @DATABASE_PASSWORD@ to the correct value.  "See the previous section describing correct quoting":#localparams
349 # In @local_config_dir/pillars/arvados.sls@ you may need to adjust the database name and user.  This can be found in the section @arvados.cluster.database@.
350
351 h2(#further_customization). Further customization of the installation (optional)
352
353 If you are installing on AWS and have followed all of the naming conventions recommend in this guide, you probably don't need to do any further customization.
354
355 If you are installing on a different cloud provider or on HPC, other changes may require editing the Saltstack pillars and states files found in @local_config_dir@.  In particular, @local_config_dir/pillars/arvados.sls@ contains the template (in the @arvados.cluster@ section) used to produce the Arvados configuration file that is distributed to all the nodes.  Consult the "Configuration reference":config.html for a comprehensive list of configuration keys.
356
357 Any extra Salt "state" files you add under @local_config_dir/states@ will be added to the Salt run and applied to the hosts.
358
359 h2(#create_a_compute_image). Configure compute nodes
360
361 {% include 'branchname' %}
362
363 If you will use fixed compute nodes with an HPC scheduler such as SLURM or LSF, you will need to "Set up your compute nodes with Docker":{{site.baseurl}}/install/crunch2/install-compute-node-docker.html or "Set up your compute nodes with Singularity":{{site.baseurl}}/install/crunch2/install-compute-node-singularity.html.
364
365 On cloud installations, containers are dispatched in Docker daemons running in the _compute instances_, which need some additional setup.
366
367 h3. Build the compute image
368
369 Follow "the instructions to build a cloud compute node image":{{site.baseurl}}/install/crunch2-cloud/install-compute-node.html using the compute image builder script found in @arvados/tools/compute-images@ in your Arvados clone from "step 3":#download.
370
371 h3. Configure the compute image
372
373 Once the image has been created, open @local_config_dir/pillars/arvados.sls@ and edit as follows (AWS specific settings described here, other cloud providers will have similar settings in their respective configuration section):
374
375 # In the @arvados.cluster.Containers.CloudVMs@ section:
376 ## Set @ImageID@ to the AMI produced by Packer
377 ## Set @DriverParameters.Region@ to the appropriate AWS region
378 ## Set @DriverParameters.AdminUsername@ to the admin user account on the image
379 ## Set the @DriverParameters.SecurityGroupIDs@ list to the VPC security group which you set up to allow SSH connections to these nodes
380 ## Set @DriverParameters.SubnetID@ to the value of SubnetId of your VPC
381 # Update @arvados.cluster.InstanceTypes@ as necessary.  The example instance types are for AWS, other cloud providers will of course have different instance types with different names and specifications.
382 (AWS specific) If m5/c5 node types are not available, replace them with m4/c4. You'll need to double check the values for Price and IncludedScratch/AddedScratch for each type that is changed.
383
384 h2(#installation). Begin installation
385
386 At this point, you are ready to run the installer script in deploy mode that will conduct all of the Arvados installation.
387
388 Run this in the @~/arvados-setup-xarv1@ directory:
389
390 <pre>
391 ./installer.sh deploy
392 </pre>
393
394 This will install and configure Arvados on all the nodes.  It will take a while and produce a lot of logging.  If it runs into an error, it will stop.
395
396 h2(#test-install). Confirm the cluster is working
397
398 When everything has finished, you can run the diagnostics.
399
400 Depending on where you are running the installer, you need to provide @-internal-client@ or @-external-client@.
401
402 If you are running the diagnostics from one of the Arvados machines inside the private network, you want @-internal-client@ .
403
404 You are an "external client" if you running the diagnostics from your workstation outside of the private network.
405
406 <pre>
407 ./installer.sh diagnostics (-internal-client|-external-client)
408 </pre>
409
410 h3(#debugging). Debugging issues
411
412 The installer records log files for each deployment.
413
414 Most service logs go to @/var/log/syslog@.
415
416 The logs for Rails API server and for Workbench can be found in
417
418 @/var/www/arvados-api/current/log/production.log@
419 and
420 @/var/www/arvados-workbench/current/log/production.log@
421
422 on the appropriate instances.
423
424 Workbench 2 is a client-side Javascript application.  If you are having trouble loading Workbench 2, check the browser's developer console (this can be found in "Tools &rarr; Developer Tools").
425
426 h3(#iterating). Iterating on config changes
427
428 You can iterate on the config and maintain the cluster by making changes to @local.params@ and @local_config_dir@ and running @installer.sh deploy@ again.
429
430 If you are debugging a configuration issue on a specific node, you can speed up the cycle a bit by deploying just one node:
431
432 <pre>
433 ./installer.sh deploy keep0.xarv1.example.com
434 </pre>
435
436 However, once you have a final configuration, you should run a full deploy to ensure that the configuration has been synchronized on all the nodes.
437
438 h3(#common-problems). Common problems and solutions
439
440 h4. PG::UndefinedTable: ERROR:  relation \"api_clients\" does not exist
441
442 The arvados-api-server package sets up the database as a post-install script.  If the database host or password wasn't set correctly (or quoted correctly) at the time that package is installed, it won't be able to set up the database.
443
444 This will manifest as an error like this:
445
446 <pre>
447 #<ActiveRecord::StatementInvalid: PG::UndefinedTable: ERROR:  relation \"api_clients\" does not exist
448 </pre>
449
450 If this happens, you need to
451
452 1. correct the database information
453 2. run @./installer.sh deploy xarv1.example.com@ to update the configuration on the API/controller node
454 3. Log in to the API/controller server node, then run this command to re-run the post-install script, which will set up the database:
455 <pre>dpkg-reconfigure arvados-api-server</pre>
456 4. Re-run @./installer.sh deploy@ again to synchronize everything, and so that the install steps that need to contact the API server are run successfully.
457
458 h4. Missing ENA support (AWS Specific)
459
460 If the AMI wasn't built with ENA (extended networking) support and the instance type requires it, it'll fail to start.  You'll see an error in syslog on the node that runs @arvados-dispatch-cloud@.  The solution is to build a new AMI with --aws-ena-support true
461
462 h2(#initial_user). Initial user and login
463
464 At this point you should be able to log into the Arvados cluster. The initial URL will be
465
466 https://workbench.${DOMAIN}@
467
468 If you did *not* "configure a different authentication provider":#authentication you will be using the "Test" provider, and the provision script creates an initial user for testing purposes. This user is configured as administrator of the newly created cluster.  It uses the values of @INITIAL_USER@ and @INITIAL_USER_PASSWORD@ the @local.params@ file.
469
470 If you *did* configure a different authentication provider, the first user to log in will automatically be given Arvados admin privileges.
471
472 h2(#monitoring). Monitoring and Metrics
473
474 You can monitor the health and performance of the system using the admin dashboard:
475
476 https://grafana.${DOMAIN}@
477
478 To log in, use username "admin" and @${INITIAL_USER_PASSWORD}@ from @local.conf@.
479
480 Once logged in, you will want to add the dashboards to the front page.
481
482 # On the left icon bar, click on "Browse"
483 # You should see a folder called "Arvados Cluster", click to open it
484 ## If you don't see anything, make sure the check box next to "Starred" is not selected
485 # You should see three dashboards "Arvados cluster overview", "Node exporter" and "Postgres exporter"
486 # Visit each dashboard, at the top of the page click on the star next to the title to "Mark as favorite"
487 # They should now be linked on the front page.
488
489 h2(#post_install). After the installation
490
491 As part of the operation of @installer.sh@, it automatically creates a @git@ repository with your configuration templates.  You should retain this repository but *be aware that it contains sensitive information* (passwords and tokens used by the Arvados services as well as cloud credentials if you used Terraform to create the infrastructure).
492
493 As described in "Iterating on config changes":#iterating you may use @installer.sh deploy@ to re-run the Salt to deploy configuration changes and upgrades.  However, be aware that the configuration templates created for you by @installer.sh@ are a snapshot which are not automatically kept up to date.
494
495 When deploying upgrades, consult the "Arvados upgrade notes":{{site.baseurl}}/admin/upgrading.html to see if changes need to be made to the configuration file template in @local_config_dir/pillars/arvados.sls@.  To specify the version to upgrade to, set the @VERSION@ parameter in @local.params@.
496
497 See also "Maintenance and upgrading":{{site.baseurl}}/admin/maintenance-and-upgrading.html for more information.