Merge branch '20540-crunch-run-retry'
[arvados.git] / doc / install / crunch2-cloud / install-compute-node.html.textile.liquid
1 ---
2 layout: default
3 navsection: installguide
4 title: Build a cloud compute node image
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 {% include 'notebox_begin_warning' %}
13 @arvados-dispatch-cloud@ is only relevant for cloud installations. Skip this section if you are installing an on premises cluster that will spool jobs to Slurm or LSF.
14 {% include 'notebox_end' %}
15
16 # "Introduction":#introduction
17 # "Install Packer":#install-packer
18 # "Create an SSH keypair":#sshkeypair
19 # "Compute image requirements":#requirements
20 # "The build script":#building
21 # "DNS resolution":#dns-resolution
22 # "NVIDIA GPU support":#nvidia
23 # "Singularity mksquashfs configuration":#singularity_mksquashfs_configuration
24 # "Build an AWS image":#aws
25 ## "Autoscaling compute node scratch space":#aws-ebs-autoscaler
26 # "Build an Azure image":#azure
27
28 h2(#introduction). Introduction
29
30 This page describes how to build a compute node image that can be used to run containers dispatched by Arvados in the cloud.
31
32 Packer templates for AWS and Azure are provided with Arvados. To use them, the following are needed:
33
34 * "Packer":https://www.packer.io/
35 * credentials for your cloud account
36 * configuration details for your cloud account
37
38 h2(#install-packer). Install Packer
39
40 "Download Packer here":https://developer.hashicorp.com/packer/downloads
41
42 h2(#sshkeypair). Create a SSH keypair
43
44 @arvados-dispatch-cloud@ communicates with the compute nodes via SSH. To do this securely, a SSH keypair is needed.
45
46 Generate a SSH keypair with no passphrase. The private key needs to be stored in the cluster configuration file (see @Containers/DispatchPrivateKey@) for use by @arvados-dispatch-cloud@, as described in the "next section":install-dispatch-cloud.html#update-config. The public key will be baked into the compute node images, see the cloud-specific documentation below.
47
48 <notextile>
49 <pre><code>~$ <span class="userinput">ssh-keygen -N '' -f ~/.ssh/id_dispatcher</span>
50 Generating public/private rsa key pair.
51 Your identification has been saved in /home/user/.ssh/id_dispatcher.
52 Your public key has been saved in /home/user/.ssh/id_dispatcher.pub.
53 The key fingerprint is:
54 [...]
55 ~$ <span class="userinput">cat ~/.ssh/id_dispatcher</span>
56 -----BEGIN RSA PRIVATE KEY-----
57 MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
58 ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
59 ...
60 oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
61 foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
62 -----END RSA PRIVATE KEY-----
63 </code></pre>
64 </notextile>
65
66 h2(#requirements). Compute image requirements
67
68 Arvados comes with a build script to automate the creation of a suitable compute node image (see "The build script":#building below). It is provided as a convenience. It is also possible to create a compute node image via other means. These are the requirements:
69
70 * for AWS: the SSH public key for @arvados-dispatch-cloud@ (the one that corresponds with @Containers.DispatchPrivateKey@ in the Arvados config file) needs to go into ~/.ssh/authorized_keys for the SSH user you want @arvados-dispatch-cloud@ to use (cf. @CloudVMs.DriverParameters.AdminUsername@ in the Arvados config file) and that user needs to be able to sudo without password prompt, unless you use `root` in which case sudo is not used.
71 * for Azure: @arvados-dispatch-cloud@ automatically extracts the SSH public key from the value of @Containers.DispatchPrivateKey@ and uses an API call to create the user specified in @CloudVMs.DriverParameters.AdminUsername@ with that SSH public key and password-less sudo enabled.
72 * SSH needs to be running and reachable by @arvados-dispatch-cloud@ on port 22 (or a custom port, see @CloudVMS.SSHPort@ to in the Arvados config file)
73 * the @python3-arvados-fuse@ package needs to be installed
74 * @Docker@ or @Singularity@ needs to be installed (cf. @Containers.RuntimeEngine@ in the Arvados config file).
75 * all available scratch space should be made available under `/tmp`.
76
77 h2(#building). The build script
78
79 The necessary files are located in the @arvados/tools/compute-images@ directory in the source tree. A build script is provided to generate the image. The @--help@ argument lists all available options:
80
81 <notextile><pre><code>~$ <span class="userinput">./build.sh --help</span>
82 build.sh: Build cloud images for arvados-dispatch-cloud
83
84 Syntax:
85         build.sh [options]
86
87 Options:
88
89   --json-file &lt;path&gt;
90       Path to the packer json file (required)
91   --arvados-cluster-id &lt;xxxxx&gt;
92       The ID of the Arvados cluster, e.g. zzzzz(required)
93   --aws-profile &lt;profile&gt;
94       AWS profile to use (valid profile from ~/.aws/config (optional)
95   --aws-secrets-file &lt;path&gt;
96       AWS secrets file which will be sourced from this script (optional)
97       When building for AWS, either an AWS profile or an AWS secrets file
98       must be provided.
99   --aws-source-ami &lt;ami-xxxxxxxxxxxxxxxxx&gt;
100       The AMI to use as base for building the images (required if building for AWS)
101   --aws-region &lt;region&gt; (default: us-east-1)
102       The AWS region to use for building the images
103   --aws-vpc-id &lt;vpc-id&gt;
104       VPC id for AWS, if not specified packer will derive from the subnet id or pick the default one.
105   --aws-subnet-id &lt;subnet-xxxxxxxxxxxxxxxxx&gt;
106       Subnet id for AWS, if not specified packer will pick the default one for the VPC.
107   --aws-ebs-autoscale
108       Install the AWS EBS autoscaler daemon (default: do not install the AWS EBS autoscaler).
109   --aws-associate-public-ip &lt;true|false&gt;
110       Associate a public IP address with the node used for building the compute image.
111       Required when the machine running packer can not reach the node used for building
112       the compute image via its private IP. (default: true if building for AWS)
113       Note: if the subnet has "Auto-assign public IPv4 address" enabled, disabling this
114       flag will have no effect.
115   --aws-ena-support &lt;true|false&gt;
116       Enable enhanced networking (default: true if building for AWS)
117   --gcp-project-id &lt;project-id&gt;
118       GCP project id (required if building for GCP)
119   --gcp-account-file &lt;path&gt;
120       GCP account file (required if building for GCP)
121   --gcp-zone &lt;zone&gt; (default: us-central1-f)
122       GCP zone
123   --azure-secrets-file &lt;patch&gt;
124       Azure secrets file which will be sourced from this script (required if building for Azure)
125   --azure-resource-group &lt;resouce-group&gt;
126       Azure resource group (required if building for Azure)
127   --azure-location &lt;location&gt;
128       Azure location, e.g. centralus, eastus, westeurope (required if building for Azure)
129   --azure-sku &lt;sku&gt; (required if building for Azure, e.g. 16.04-LTS)
130       Azure SKU image to use
131   --ssh_user &lt;user&gt; (default: packer)
132       The user packer will use to log into the image
133   --resolver &lt;resolver_IP&gt;
134       The dns resolver for the machine (default: host's network provided)
135   --reposuffix &lt;suffix&gt;
136       Set this to "-dev" to track the unstable/dev Arvados repositories
137   --public-key-file &lt;path&gt;
138       Path to the public key file that a-d-c will use to log into the compute node (required)
139   --mksquashfs-mem (default: 256M)
140       Only relevant when using Singularity. This is the amount of memory mksquashfs is allowed to use.
141   --nvidia-gpu-support
142       Install all the necessary tooling for Nvidia GPU support (default: do not install Nvidia GPU support)
143   --debug
144       Output debug information (default: no debug output is printed)
145 </code></pre></notextile>
146
147 h2(#dns-resolution). DNS resolution
148
149 Compute nodes must be able to resolve the hostnames of the API server and any keepstore servers to your internal IP addresses.  If you are on AWS and using Route 53 for your DNS, the default resolver configuration can be used with no extra options.
150
151 You can also run your own internal DNS resolver. In that case, the IP address of the resolver should be passed as the value for the @--resolver@ argument to "the build script":#building.
152
153 As a third option, the services could be hardcoded into an @/etc/hosts@ file. For example:
154
155 <notextile><pre><code>10.20.30.40     <span class="userinput">ClusterID.example.com</span>
156 10.20.30.41     <span class="userinput">keep1.ClusterID.example.com</span>
157 10.20.30.42     <span class="userinput">keep2.ClusterID.example.com</span>
158 </code></pre></notextile>
159
160 Adding these lines to the @/etc/hosts@ file in the compute node image could be done with a small change to the Packer template and the @scripts/base.sh@ script, which will be left as an exercise for the reader.
161
162 h2(#nvidia). NVIDIA GPU support
163
164 If you plan on using instance types with NVIDIA GPUs, add @--nvidia-gpu-support@ to the build command line.  Arvados uses the same compute image for both GPU and non-GPU instance types.  The GPU tooling is ignored when using the image with a non-GPU instance type.
165
166 {% assign show_docker_warning = true %}
167
168 {% include 'singularity_mksquashfs_configuration' %}
169
170 The desired amount of memory to make available for @mksquashfs@ can be configured in an argument to "the build script":#building. It defaults to @256M@.
171
172 h2(#aws). Build an AWS image
173
174 For @ClusterID@, fill in your cluster ID.
175
176 @AWSProfile@ is the name of an AWS profile in your "credentials file":https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#shared-credentials-file (@~/.aws/credentials@) listing the @aws_access_key_id@ and @aws_secret_access_key@ to use.
177
178 The @AMI@ is the identifier for the base image to be used. Current AMIs are maintained by "Debian":https://wiki.debian.org/Cloud/AmazonEC2Image/Buster and "Ubuntu":https://cloud-images.ubuntu.com/locator/ec2/.
179
180 The @VPC@ and @Subnet@ should be configured for where you want the compute image to be generated and stored.
181
182 @ArvadosDispatchCloudPublicKeyPath@ should be replaced with the path to the ssh *public* key file generated in "Create an SSH keypair":#sshkeypair, above.
183
184 <notextile><pre><code>~$ <span class="userinput">./build.sh --json-file arvados-images-aws.json \
185            --arvados-cluster-id ClusterID \
186            --aws-profile AWSProfile \
187            --aws-source-ami AMI \
188            --aws-vpc-id VPC \
189            --aws-subnet-id Subnet \
190            --ssh_user admin \
191            --public-key-file ArvadosDispatchCloudPublicKeyPath
192 </span>
193 </code></pre></notextile>
194
195
196 h3(#aws-ebs-autoscaler). Autoscaling compute node scratch space
197
198 Arvados supports "AWS EBS autoscaler":https://github.com/awslabs/amazon-ebs-autoscale.  This feature automatically expands the scratch space on the compute node on demand by 200 GB at a time, up to 5 TB.
199
200 If you want to add the daemon in your images, add the @--aws-ebs-autoscale@ flag to the "the build script":#building.
201
202 The AWS EBS autoscaler daemon will be installed with this configuration:
203
204 <notextile><pre><code>{
205     "mountpoint": "/tmp",
206     "filesystem": "lvm.ext4",
207     "lvm": {
208       "volume_group": "autoscale_vg",
209       "logical_volume": "autoscale_lv"
210     },
211     "volume": {
212         "type": "gp3",
213         "iops": 3000,
214         "encrypted": 1
215     },
216     "detection_interval": 2,
217     "limits": {
218         "max_ebs_volume_size": 1500,
219         "max_logical_volume_size": 8000,
220         "max_ebs_volume_count": 16
221     },
222     "logging": {
223         "log_file": "/var/log/ebs-autoscale.log",
224         "log_interval": 300
225     }
226 }
227 </code></pre></notextile>
228
229 Changing the ebs-autoscale configuration is left as an exercise for the reader.
230
231 This feature also requires a few Arvados configuration changes, described in "EBS Autoscale configuration":install-dispatch-cloud.html#aws-ebs-autoscaler.
232
233 h2(#azure). Build an Azure image
234
235 <notextile><pre><code>~$ <span class="userinput">./build.sh --json-file arvados-images-azure.json \
236            --arvados-cluster-id ClusterID \
237            --azure-resource-group ResourceGroup \
238            --azure-location AzureRegion \
239            --azure-sku AzureSKU \
240            --azure-secrets-file AzureSecretsFilePath \
241            --resolver ResolverIP \
242            --public-key-file ArvadosDispatchCloudPublicKeyPath
243 </span>
244 </code></pre></notextile>
245
246 For @ClusterID@, fill in your cluster ID. The @ResourceGroup@ and @AzureRegion@ (e.g. 'eastus2') should be configured for where you want the compute image to be generated and stored. The @AzureSKU@ is the SKU of the base image to be used, e.g. '18.04-LTS' for Ubuntu 18.04.
247
248 @AzureSecretsFilePath@ should be replaced with the path to a shell script that loads the Azure secrets with sufficient permissions to create the image. The file would look like this:
249
250 <notextile><pre><code>export ARM_CLIENT_ID=...
251 export ARM_CLIENT_SECRET=...
252 export ARM_SUBSCRIPTION_ID=...
253 export ARM_TENANT_ID=...
254 </code></pre></notextile>
255
256 These secrets can be generated from the Azure portal, or with the cli using a command like this:
257
258 <notextile><pre><code>~$ <span class="userinput">az ad sp create-for-rbac --name Packer --password ...</span>
259 </code></pre></notextile>
260
261 @ArvadosDispatchCloudPublicKeyPath@ should be replaced with the path to the ssh *public* key file generated in "Create an SSH keypair":#sshkeypair, above.