+h2(#prerequisites). Prerequisites and planning
+
+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.
+
+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.
+
+h3. Install Terraform and AWS CLI (AWS specific)
+
+If you are going to use Terraform to set up the infrastructure on AWS, you will need to install the "Terraform CLI":https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli tool installed on your computer, as well as the "AWS CLI":https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html tool.
+
+h2(#download). Download the installer
+
+{% assign local_params_src = 'multiple_hosts' %}
+{% assign config_examples_src = 'multi_host/aws terraform/aws'%}
+{% include 'download_installer' %}
+
+h2(#setup-infra). Set up your infrastructure
+
+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 @arvados/tools/salt-install/terraform/aws/@ directory and are divided in three sections:
+
+# The @vpc/@ subdirectory controls the network related infrastructure of your cluster, including firewall rules and split-horizon DNS resolution.
+# The @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 @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 @services/@ 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"
+cluster_name = "xarv1"
+deploy_user = "admin"
+domain_name = "example.com"
+letsencrypt_iam_access_key_id = "AKAA43MAAAWAKAADAASD"
+letsencrypt_iam_secret_access_key = <sensitive>
+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"
+}
+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",
+])
+subnet_id = "subnet-072a999f939989710"
+vpc_cidr = "10.1.0.0/16"
+vpc_id = "vpc-0999994998399923a"
+</code></pre>
+
+
+h4. Additional DNS configuration
+
+Once Terraform has completed, the infrastructure for your Arvados cluster is up and running. You are almost ready to have the installer connect to the instances to install and configure the software.
+
+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 will 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 that contain the Arvados hostname records created by Terraform. You do this by creating an @NS@ record on the parent domain that refers to the appropriate name servers. These are the domain 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*
+
+h4. Other important output parameters
+
+Take note of @letsencrypt_iam_access_key_id@ and @letsencrypt_iam_secret_access_key@ for setting up @LE_AWS_*@ variables in @local.params@. The certificates will be requested when you run the installer.
+
+You'll see that the @letsencrypt_iam_secret_access_key@ data is obscured; to retrieve it you'll need to run the following command inside the @services/@ subdirectory:
+
+<pre><code>$ terraform output letsencrypt_iam_secret_access_key
+"FQ3+3lxxOxxUu+Nw+qx3xixxxExxxV9jFC+XxxRl"</code></pre>
+
+You'll also need @subnet_id@ and @arvados_sg_id@ to set up @DriverParameters.SubnetID@ and @DriverParameters.SecurityGroupIDs@ in @local_config_dir/pillars/arvados.sls@ for when you "create a compute image":#create_a_compute_image.
+
+h3(#inframanual). Create required infrastructure manually
+
+If you will be setting up infrastructure without using the provided Terraform script, here are the recommendations you will need to consider.
+
+h4. Virtual Private Cloud (AWS specific)
+
+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: