---
layout: default
navsection: installguide
-title: Multi host Arvados
+title: Multi-Host Arvados
...
{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.
# "Introduction":#introduction
# "Prerequisites and planning":#prerequisites
-# "Hosts":#hosts
# "Download the installer":#download
# "Initialize the installer":#copy_config
+# "Set up your infrastructure":#setup-infra
+## "Create AWS infrastructure with Terraform":#terraform
+## "Create required infrastructure manually":#inframanual
# "Edit local.params":#localparams
# "Configure Keep storage":#keep
# "Choose the SSL configuration":#certificates
-## "Using a self-signed certificates":#self-signed
## "Using a Let's Encrypt certificates":#lets-encrypt
## "Bring your own certificates":#bring-your-own
# "Create a compute image":#create_a_compute_image
-# "Further customization of the installation":#further_customization
# "Begin installation":#installation
-## "Run diagnostics to confirming the cluster is working":#test-install
+# "Further customization of the installation":#further_customization
+# "Confirm the cluster is working":#test-install
## "Debugging issues":#debugging
## "Iterating on config changes":#iterating
## "Common problems and solutions":#common-problems
-# "Install the CA root certificate":#ca_root_certificate
# "Initial user and login":#initial_user
# "After the installation":#post_install
h3. Cluster ID and base domain
-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.
+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.
+
+Determine the base domain for the cluster. This will be referred to as @${DOMAIN}@.
+
+For example, if CLUSTER is @xarv1@ and DOMAIN is @example.com@, then @controller.${CLUSTER}.${DOMAIN}@ means @controller.xarv1.example.com@.
+
+h3(#DNS). DNS hostnames for each service
+
+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.
+
+In the default configuration these are:
+
+# @controller.${CLUSTER}.${DOMAIN}@
+# @ws.${CLUSTER}.${DOMAIN}@
+# @keep0.${CLUSTER}.${DOMAIN}@
+# @keep1.${CLUSTER}.${DOMAIN}@
+# @keep.${CLUSTER}.${DOMAIN}@
+# @download.${CLUSTER}.${DOMAIN}@
+# @*.collections.${CLUSTER}.${DOMAIN}@ -- important note, this must be a wildcard DNS, resolving to the @keepweb@ service
+# @workbench.${CLUSTER}.${DOMAIN}@
+# @workbench2.${CLUSTER}.${DOMAIN}@
+# @webshell.${CLUSTER}.${DOMAIN}@
+# @shell.${CLUSTER}.${DOMAIN}@
+
+For more information, see "DNS entries and TLS certificates":install-manual-prerequisites.html#dnstls.
+
+h2(#download). Download the installer
+
+{% assign local_params_src = 'multiple_hosts' %}
+{% assign config_examples_src = 'multi_host/aws' %}
+{% assign terraform_src = 'terraform/aws' %}
+{% include 'download_installer' %}
+
+h2(#setup-infra). Set up your infrastructure
+
+## "Create AWS infrastructure with Terraform":#terraform
+## "Create required infrastructure manually":#inframanual
+
+h3(#terraform). Create AWS infrastructure with Terraform (AWS specific)
+
+We provide a set of Terraform code files that you can run to create the necessary infrastructure on Amazon Web Services.
+
+These files are located in the @terraform@ installer directory and are divided in three sections:
+
+# The @terraform/vpc/@ subdirectory controls the network related infrastructure of your cluster, including firewall rules and split-horizon DNS resolution.
+# 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.
+# 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.
+
+h4. Software requirements & considerations
+
+{% include 'notebox_begin' %}
+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.
+{% include 'notebox_end' %}
+
+h4. Terraform code configuration
+
+Each section described above contain a @terraform.tfvars@ file with some configuration values that you should set before applying each configuration. You should set the cluster prefix and domain name in @vpc/terraform.tfvars@:
+
+<pre><code>region_name = "us-east-1"
+# cluster_name = "xarv1"
+# domain_name = "example.com"</code></pre>
+
+If you don't set the variables @vpc/terraform.tfvars@ file, you will be asked to re-enter these parameters every time you run Terraform.
+
+The @data-storage/terraform.tfvars@ and @services/terraform.tfvars@ let you configure the location of your ssh public key (default @~/.ssh/id_rsa.pub@) and the instance type to use (default @m5a.large@).
+
+h4. Create the infrastructure
+
+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:
+
+<pre><code>$ ./installer.sh terraform
+...
+Apply complete! Resources: 16 added, 0 changed, 0 destroyed.
+
+Outputs:
+
+arvados_sg_id = "sg-02f999a99973999d7"
+arvados_subnet_id = "subnet-01234567abc"
+cluster_name = "xarv1"
+compute_subnet_id = "subnet-abcdef12345"
+deploy_user = "admin"
+domain_name = "example.com"
+letsencrypt_iam_access_key_id = "AKAA43MAAAWAKAADAASD"
+private_ip = {
+ "controller" = "10.1.1.1"
+ "keep0" = "10.1.1.3"
+ "keep1" = "10.1.1.4"
+ "keepproxy" = "10.1.1.2"
+ "shell" = "10.1.1.7"
+ "workbench" = "10.1.1.5"
+}
+public_ip = {
+ "controller" = "18.235.116.23"
+ "keep0" = "34.202.85.86"
+ "keep1" = "38.22.123.98"
+ "keepproxy" = "34.231.9.201"
+ "shell" = "44.208.155.240"
+ "workbench" = "52.204.134.136"
+}
+region_name = "us-east-1"
+route53_dns_ns = tolist([
+ "ns-1119.awsdns-11.org",
+ "ns-1812.awsdns-34.co.uk",
+ "ns-437.awsdns-54.com",
+ "ns-809.awsdns-37.net",
+])
+vpc_cidr = "10.1.0.0/16"
+vpc_id = "vpc-0999994998399923a"
+letsencrypt_iam_secret_access_key = "XXXXXSECRETACCESSKEYXXXX"
+</code></pre>
+
+
+h4. Additional DNS configuration
+
+Once Terraform has completed, the infrastructure for your Arvados cluster is up and running. One last piece of DNS configuration is required.
+
+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/ .
+
+You need to configure the parent domain to delegate to the newly created zone. In other words, you need to configure @${DOMAIN}@ (e.g. "example.com") to delegate the subdomain @${CLUSTER}.${DOMAIN}@ (e.g. "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@.
+
+If your parent domain is also controlled by Route 53, the process will be like this:
+
+# Log in to the AWS Console and navigate to the service page for *Route 53*
+# Go to the list of *Hosted zones* and click on the zone for the parent domain
+# Click on *Create record*
+# For *Record name* put the cluster id
+# For *Record type* choose @NS - Name servers for a hosted zone@
+# For *Value* add the values from Terraform output parameter @route53_dns_ns@, one hostname per line, with punctuation (quotes and commas) removed.
+# Click *Create records*
+
+If the parent domain is controlled by some other service, follow the guide for the the appropriate service.
+
+h4. Other important output parameters
+
+The certificates will be requested from Let's Encrypt when you run the installer.
+
+* @vpc_cidr@ will be used to set @CLUSTER_INT_CIDR@
+
+* 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.
+
+You can now proceed to "edit local.params":#localparams.
-Determine the base domain for the cluster. This will be referred to as ${DOMAIN}
+h3(#inframanual). Create required infrastructure manually
-For example, if CLUSTER is "xarv1" and DOMAIN is "example.com", then "controller.${CLUSTER}.${DOMAIN}" means "controller.xargv1.example.com".
+If you will be setting up infrastructure without using the provided Terraform script, here are the recommendations you will need to consider.
-h3. Virtual Private Cloud (AWS specific)
+h4. Virtual Private Cloud (AWS specific)
-We recommend setting Arvados up in a "Virtual Private Cloud (VPC)":https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html
+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
When you do so, you need to configure a couple of additional things:
# You should set up a "security group which allows SSH access (port 22)":https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html
# Make sure to add a "VPC S3 endpoint":https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html
-h3. S3 Bucket (AWS specific)
+h4(#keep-bucket). S3 Bucket (AWS specific)
-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 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@.
-Then create an IAM role called @${CLUSTER}-keepstore-00-iam-role@ which has "permission to read and write the bucket":https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html
+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.
-h3. Other IAM Roles (AWS specific)
-
-
-
-h2(#hosts). Hosts
+h4(#hosts). Required hosts
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.
{% include 'supportedlinux' %}
-Allocate these 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.
+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.
The installer will set up the Arvados services on your machines. Here is the default assignment of services to machines:
# SHELL node (optional)
## arvados shell (recommended hostname @shell.${CLUSTER}.${DOMAIN}@)
-Additional prerequisites when preparing machines to run the installer:
+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.
-# root or passwordless sudo access
-# from the account where you are performing the install, passwordless @ssh@ to each machine (meaning, the client's public key added to @~/.ssh/authorized_keys@ on each node)
+h4. Additional prerequisites when preparing machines to run the installer
+
+# From the account where you are performing the install, passwordless @ssh@ to each machine
+This means the client's public key should added to @~/.ssh/authorized_keys@ on each node.
+# Passwordless @sudo@ access on the account on each machine you will @ssh@ in to
+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.
+<pre>%sudo ALL=(ALL:ALL) NOPASSWD:ALL</pre>
# @git@ installed on each machine
-# port 443 reachable by clients
-# DNS hostnames for each service
-## @controller.${CLUSTER}.${DOMAIN}@
-## @ws.${CLUSTER}.${DOMAIN}@
-## @keep0.${CLUSTER}.${DOMAIN}@
-## @keep1.${CLUSTER}.${DOMAIN}@
-## @keep.${CLUSTER}.${DOMAIN}@
-## @download.${CLUSTER}.${DOMAIN}@
-## @*.collections.${CLUSTER}.${DOMAIN}@ -- important note, this should be a wildcard DNS, going to the keepweb service
-## @workbench.${CLUSTER}.${DOMAIN}@
-## @workbench2.${CLUSTER}.${DOMAIN}@
-## @webshell.${CLUSTER}.${DOMAIN}@
-## @shell.${CLUSTER}.${DOMAIN}@
-
-(AWS specific) The machine that runs the arvados cloud dispatcher will need an "IAM role that allows it to create EC2 instances, see here for details .":https://doc.arvados.org/v2.4/install/crunch2-cloud/install-dispatch-cloud.html#IAM
-
-If your infrastructure differs from the setup proposed above (ie, different hostnames, or using AWS RDS or an existing DB server), you can still use the installer, but additional customization will be necessary.
+# Port 443 reachable by clients
-h2(#download). Download the installer
+(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
-{% assign local_params_src = 'multiple_hosts' %}
-{% assign config_examples_src = 'multi_host/aws'%}
-{% include 'download_installer' %}
+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 .
h2(#localparams). Edit @local.params@
# Set @CLUSTER@ to the 5-character cluster identifier (e.g "xarv1")
# Set @DOMAIN@ to the base DNS domain of the environment, e.g. "example.com"
-# Edit Internal IP settings. Since services share hosts, some hosts are the same.
+# 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
# Edit @CLUSTER_INT_CIDR@, this should be the CIDR of the private network that Arvados is running on, e.g. the VPC.
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.
_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)._
# Set @INITIAL_USER_EMAIL@ to your email address, as you will be the first admin user of the system.
-# Set each @KEY@ / @TOKEN@ to a random string
- Here's an easy way to create five random tokens:
-<pre><code>for i in 1 2 3 4 5; do
- tr -dc A-Za-z0-9 </dev/urandom | head -c 32 ; echo ''
-done
+# Set each @KEY@ / @TOKEN@ / @PASSWORD@ to a random string. You can use @installer.sh generate-tokens@
+<pre><code>$ ./installer.sh generate-tokens
+BLOB_SIGNING_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+MANAGEMENT_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+SYSTEM_ROOT_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ANONYMOUS_USER_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+WORKBENCH_SECRET_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+DATABASE_PASSWORD=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
</code></pre>
-# Set @DATABASE_PASSWORD@ to a random string
+# 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)
Important! If this contains any non-alphanumeric characters, in particular ampersand ('&'), it is necessary to add backslash quoting.
- For example, if the password is `Cq&WU<A']p?j`
+ For example, if the password is @Lq&MZ<V']d?j@
With backslash quoting the special characters it should appear like this in local.params:
-<pre><code>DATABASE_PASSWORD="Cq\&WU\<A\'\]p\?j"</code></pre>
+<pre><code>DATABASE_PASSWORD="Lq\&MZ\<V\'\]d\?j"</code></pre>
+
+h3(#etchosts). Note on @/etc/hosts@
+
+Because Arvados services are typically accessed by external clients, they are likely to have both a public IP address and a internal IP address.
+
+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).
+
+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.
h2(#keep). Configure Keep storage
-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 @local_config_dir/pillars/arvados.sls@ in the section @arvados.cluster.Volumes@.
+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@.
h3. Object storage in S3 (AWS Specific)
Open @local_config_dir/pillars/arvados.sls@ and edit as follows:
-# In the @arvados.cluster.Volumes@ section, set @Region@ to the appropriate AWS region (e.g. 'us-east-1')
-# Set @IAMRole@ to the name of the `KeepstoreRole` generated by CloudFormation. Just use the part after the '/' (not the arn:aws:iam.... stuff at the beginning).
-# Set @Bucket@ to the value of `KeepBucket1`
+# In the @arvados.cluster.Volumes.DriverParameters@ section, set @Region@ to the appropriate AWS region (e.g. 'us-east-1')
+
+If "followed the recommendend naming scheme":#keep-bucket for both the bucket and role (or used the provided Terraform script), you're done.
+
+If you did not follow the recommendend naming scheme for either the bucket or role, you'll need to update these parameters as well:
+
+# Set @Bucket@ to the value of "keepstore bucket you created earlier":#keep-bucket
+# Set @IAMRole@ to "keepstore role you created earlier":#keep-bucket
{% include 'ssl_config_multi' %}
-h2(#create_a_compute_image). Create a compute image
+h2(#authentication). Configure your authentication provider (optional, recommended)
-{% include 'branchname' %}
+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* .
-On cloud installations, containers are dispatched in Docker daemons running in the <i>compute instances</i>, which need some special setup. Follow "the instructions build a cloud compute node image":https://doc.arvados.org/install/crunch2-cloud/install-compute-node.html using the "compute image builder script":https://github.com/arvados/arvados/tree/{{ branchname }}/tools/compute-images .
+h2(#ext-database). Using an external database (optional)
-Once you have that image created, Open @local_config_dir/pillars/arvados.sls@ and edit as follows (AWS specific settings described here, configuration for Azure is similar):
+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.
-# In the @arvados.cluster.Containers.CloudVMs@ section:
-## Set @ImageID@ to the AMI output from Packer
-## Set @Region@ to the appropriate AWS region
-## Set @AdminUsername@ to the admin user account on the image
-## Set the @SecurityGroupIDs@ list to the VPC security group which you set up to allow SSH connections to these nodes
-## Set @SubnetID@ to the value of SubnetId of your VPC
-# Update @arvados.cluster.Containers.DispatchPrivateKey@ and paste the contents of the @~/.ssh/id_dispatcher@ file you generated in an earlier step.
-# Update @arvados.cluster.InstanceTypes@ as necessary. If t3 and m5/c5 node types are not available, replace them with t2 and m4/c4. You'll need to double check the values for Price and IncludedScratch/AddedScratch for each type that is changed.
+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).
+
+# In @local.params@, remove 'database' from the list of roles assigned to the controller node:
+<pre><code>NODES=(
+ [controller.${CLUSTER}.${DOMAIN}]=api,controller,websocket,dispatcher,keepbalance
+ ...
+)
+</code></pre>
+# In @local.params@, set @DATABASE_INT_IP@ to the database endpoint (can be a hostname, does not have to be an IP address).
+<pre><code>DATABASE_INT_IP=...
+</code></pre>
+# In @local.params@, set @DATABASE_PASSWORD@ to the correct value. "See the previous section describing correct quoting":#localparams
+# 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@.
+
+h2(#further_customization). Further customization of the installation (optional)
+
+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.
-h2(#further_customization). Further customization of the installation
+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.
-If you are installing on AWS and following the naming conventions recommend in this guide, then likely no further configuration is necessary and you can begin installation.
+Any extra Salt "state" files you add under @local_config_dir/states@ will be added to the Salt run and applied to the hosts.
-If your infrastructure differs from the setup proposed above (ie, using AWS RDS or an existing DB server), you can still use the installer, but additional customization will be necessary.
+h2(#create_a_compute_image). Configure compute nodes
-This is done by editing the Saltstack pillars and states files found in @local_config_dir@. In particular, @local_config_dir/pillars/arvados.sls@ has the template used to produce the Arvados configuration file that is distributed to all the nodes.
+{% include 'branchname' %}
+
+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.
+
+On cloud installations, containers are dispatched in Docker daemons running in the _compute instances_, which need some additional setup.
+
+h3. Build the compute image
+
+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.
+
+h3. Configure the compute image
-Any extra salt <i>state</i> file you add under @local_config_dir/states@ will be added to the salt run and applied to the hosts.
+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):
+
+# In the @arvados.cluster.Containers.CloudVMs@ section:
+## Set @ImageID@ to the AMI produced by Packer
+## Set @DriverParameters.Region@ to the appropriate AWS region
+## Set @DriverParameters.AdminUsername@ to the admin user account on the image
+## Set the @DriverParameters.SecurityGroupIDs@ list to the VPC security group which you set up to allow SSH connections to these nodes
+## Set @DriverParameters.SubnetID@ to the value of SubnetId of your VPC
+# Update @arvados.cluster.Containers.DispatchPrivateKey@ and paste the contents of the @~/.ssh/id_dispatcher@ file you generated in an earlier step.
+# 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.
+(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.
h2(#installation). Begin installation
At this point, you are ready to run the installer script in deploy mode that will conduct all of the Arvados installation.
-Run this in ~/arvados-setup-xarv1:
+Run this in the @~/arvados-setup-xarv1@ directory:
<pre>
./installer.sh deploy
</pre>
-This will deploy all the nodes. It will take a while and produce a lot of logging. If it runs into an error, it will stop.
+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.
-h3(#test-install). Run diagnostics to confirming the cluster is working
+h2(#test-install). Confirm the cluster is working
When everything has finished, you can run the diagnostics.
Depending on where you are running the installer, you need to provide @-internal-client@ or @-external-client@.
-You are probably an "internal client" if you are running the diagnostics from one of the Arvados machines inside the VPC.
+If you are running the diagnostics from one of the Arvados machines inside the private network, you want @-internal-client@ .
-You are an "external client" if you running the diagnostics from your workstation outside of the VPC.
+You are an "external client" if you running the diagnostics from your workstation outside of the private network.
<pre>
./installer.sh diagnostics (-internal-client|-external-client)
h3(#debugging). Debugging issues
-Most service logs go to @/var/log/syslog@
+The installer records log files for each deployment.
+
+Most service logs go to @/var/log/syslog@.
The logs for Rails API server and for Workbench can be found in
on the appropriate instances.
-Workbench2 is a client-side Javascript application, if it having trouble loading, check the browser's developer console.
+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 → Developer Tools").
h3(#iterating). Iterating on config changes
h3(#common-problems). Common problems and solutions
-h4. Missing ENA support (AWS Specific)
-
-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
-
h4. PG::UndefinedTable: ERROR: relation \"api_clients\" does not exist
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.
1. correct the database information
2. run @./installer.sh deploy xarv1.example.com@ to update the configuration on the API/controller node
-3. On the API/controller server node, run this command to re-run the post-install script, which will set up the database:
-
-<pre>
-dpkg-reconfigure arvados-api-server
-</pre>
-
+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:
+<pre>dpkg-reconfigure arvados-api-server</pre>
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.
-{% include 'install_ca_cert' %}
+h4. Missing ENA support (AWS Specific)
+
+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
h2(#initial_user). Initial user and login
At this point you should be able to log into the Arvados cluster. The initial URL will be
-* https://workbench.${CLUSTER}.${DOMAIN}
-
-By default, the provision script creates an initial user for testing purposes. This user is configured as administrator of the newly created cluster.
+https://workbench.@${CLUSTER}.${DOMAIN}@
-Assuming you didn't change these values in the @local.params@ file, the initial credentials are:
+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.
-* User: 'admin'
-* Password: 'password'
-* Email: 'admin@${CLUSTER}.${DOMAIN}'
+If you *did* configure a different authentication provider, the first user to log in will automatically be given Arvados admin privileges.
h2(#post_install). After the installation
-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 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).
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.
-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@.
+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@.
-See "Maintenance and upgrading":{{site.baseurl}}/admin/maintenance-and-upgrading.html for more information.
+See also "Maintenance and upgrading":{{site.baseurl}}/admin/maintenance-and-upgrading.html for more information.
projects / arvados.git / blobdiff