# "Introduction":#introduction
# "Prerequisites and planning":#prerequisites
-# "Required hosts":#hosts
+## "Create AWS infrastructure with Terraform":#terraform
+## "Create required insfrastructure manually":#inframanual
# "Download the installer":#download
# "Initialize the installer":#copy_config
# "Edit local.params":#localparams
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}
+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.xargv1.example.com".
+For example, if CLUSTER is @xarv1@ and DOMAIN is @example.com@, then @controller.${CLUSTER}.${DOMAIN}@ means @controller.xarv1.example.com@.
-h3. Virtual Private Cloud (AWS specific)
+h3(#terraform). Create AWS infrastructure with Terraform
+
+To simplify the tedious and error-prone process of building a working cloud infrastructure for your Arvados cluster, we provide a set of Terraform code files that you can run against Amazon Web Services.
+
+These files are located in the @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
+
+In addition of having "Terraform CLI":https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli tool installed on your computer, you'll also need the "AWS CLI":https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html tool and proper credentials already configured.
+
+Once all the required tools are present, as a first step you should run @terraform init@ inside each subdirectory, so that all the required modules get downloaded. If you happen to miss this step, running @terraform apply@ will just exit with a message asking for this.
+
+{% 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. You should keep these files secure as they contain unencrypted secrets. Research on state files management best practices is left as an exercise to the reader.
+{% 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'll at least need to set up 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>
+
+The other @data-storage/terraform.tfvars@ and @services/terraform.tfvars@ files already have sensible defaults so you may not need to modify them.
+
+h4. Create the infrastructure
+
+The whole infrastructure needs to be built in stages by running @terraform apply@ inside each subdirectory in the order they are listed above. Each stage will output information that is needed by a following stage. 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>$ terraform apply
+...
+Apply complete! Resources: 16 added, 0 changed, 0 destroyed.
+
+Outputs:
+
+arvados_sg_id = "sg-02fa04a2c273166d7"
+cluster_name = "xarv1"
+deploy_user = "admin"
+domain_name = "example.com"
+letsencrypt_iam_access_key_id = "AKIA43MU4DW7K57DBVSD"
+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-072a139f03938b710"
+vpc_cidr = "10.1.0.0/16"
+vpc_id = "vpc-0934aa4738300423a"
+</code></pre>
+
+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+3lnBOtWUu+Nw+qb3RiAGqE7DxV9jFC+XTARl"</code></pre>
+
+h4. Final actions
+
+At this stage, the infrastructure for your Arvados cluster is up and running, ready for the installer to connect to the instances and do the final set up.
+
+The domain name for your cluster (e.g.: xarv1.example.com) is managed via Route53 and the SSL certificates will be issued using Let's Encrypt.
+
+Take note of the domain servers listed in @route53_dns_ns@ so you can delegate the zone to them.
+
+You'll need to take note of @letsencrypt_iam_access_key_id@ and @letsencrypt_iam_secret_access_key@ for setting up @LE_AWS_*@ variables in @local.params@.
+
+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@ as "described below":#create_a_compute_image.
+
+h3(#inframanual). Create required infrastructure manually
+
+If you would rather prefer to create/set up your infrastructure manually, below we provide some recommendations you will need to consider.
+
+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
# 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(#keep-bucket). 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 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 @xargv1@ the bucket would be called @xarv1-nyw5e-000000000000000-volume@ and the role would be called @xarv1-keepstore-00-iam-role@.
+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@.
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.
-h2(#hosts). Required 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.
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.
-h3(#DNS). DNS hostnames for each service
+h4(#DNS). DNS hostnames for each service
You will need a DNS entry for each service. In the default configuration these are:
This is described in more detail in "DNS entries and TLS certificates":install-manual-prerequisites.html#dnstls.
-h3. Additional prerequisites when preparing machines to run the installer
+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.
At this point you should be able to log into the Arvados cluster. The initial URL will be
-https://workbench.${CLUSTER}.${DOMAIN}
+https://workbench.@${CLUSTER}.${DOMAIN}@
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.
projects / arvados.git / blobdiff