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 # "Create an SSH keypair":#sshkeypair
  18 # "Compute image requirements":#requirements
  19 # "The build script":#building
  20 # "Singularity mksquashfs configuration":#singularity_mksquashfs_configuration
  21 # "Build an AWS image":#aws
  22 # "Build an Azure image":#azure
  23
  24 h2(#introduction). Introduction
  25
  26 This page describes how to build a compute node image that can be used to run containers dispatched by Arvados in the cloud.
  27
  28 Packer templates for AWS and Azure are provided with Arvados. To use them, the following are needed:
  29
  30 * "Packer":https://www.packer.io/
  31 * credentials for your cloud account
  32 * configuration details for your cloud account
  33
  34
  35 h2(#sshkeypair). Create a SSH keypair
  36
  37 @arvados-dispatch-cloud@ communicates with the compute nodes via SSH. To do this securely, a SSH keypair is needed.
  38
  39 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.
  40
  41 <notextile>
  42 <pre><code>~$ <span class="userinput">ssh-keygen -N '' -f ~/.ssh/id_dispatcher</span>
  43 Generating public/private rsa key pair.
  44 Your identification has been saved in /home/user/.ssh/id_dispatcher.
  45 Your public key has been saved in /home/user/.ssh/id_dispatcher.pub.
  46 The key fingerprint is:
  47 [...]
  48 ~$ <span class="userinput">cat ~/.ssh/id_dispatcher</span>
  49 -----BEGIN RSA PRIVATE KEY-----
  50 MIIEpQIBAAKCAQEAqXoCzcOBkFQ7w4dvXf9B++1ctgZRqEbgRYL3SstuMV4oawks
  51 ttUuxJycDdsPmeYcHsKo8vsEZpN6iYsX6ZZzhkO5nEayUTU8sBjmg1ZCTo4QqKXr
  52 ...
  53 oFyAjVoexx0RBcH6BveTfQtJKbktP1qBO4mXo2dP0cacuZEtlAqW9Eb06Pvaw/D9
  54 foktmqOY8MyctzFgXBpGTxPliGjqo8OkrOyQP2g+FL7v+Km31Xs61P8=
  55 -----END RSA PRIVATE KEY-----
  56 </code></pre>
  57 </notextile>
  58
  59 {% assign show_docker_warning = true %}
  60
  61 {% include 'singularity_mksquashfs_configuration' %}
  62
  63 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@.
  64
  65 h2(#requirements). Compute image requirements
  66
  67 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:
  68
  69 * 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.
  70 * 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.
  71 * 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)
  72 * the @python3-arvados-fuse@ package needs to be installed
  73 * @Docker@ or @Singularity@ needs to be installed (cf. @Containers.RuntimeEngine@ in the Arvados config file).
  74 * all available scratch space should be made available under `/tmp`.
  75
  76 h2(#building). The build script
  77
  78 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:
  79
  80 <notextile><pre><code>~$ <span class="userinput">./build.sh --help</span>
  81 build.sh: Build cloud images for arvados-dispatch-cloud
  82
  83 Syntax:
  84         build.sh [options]
  85
  86 Options:
  87
  88   --json-file (required)
  89       Path to the packer json file
  90   --arvados-cluster-id (required)
  91       The ID of the Arvados cluster, e.g. zzzzz
  92   --aws-profile (default: false)
  93       AWS profile to use (valid profile from ~/.aws/config
  94   --aws-secrets-file (default: false, required if building for AWS)
  95       AWS secrets file which will be sourced from this script
  96   --aws-source-ami (default: false, required if building for AWS)
  97       The AMI to use as base for building the images
  98   --aws-region (default: us-east-1)
  99       The AWS region to use for building the images
 100   --aws-vpc-id (optional)
 101       VPC id for AWS, otherwise packer will pick the default one
 102   --aws-subnet-id
 103       Subnet id for AWS otherwise packer will pick the default one for the VPC
 104   --gcp-project-id (default: false, required if building for GCP)
 105       GCP project id
 106   --gcp-account-file (default: false, required if building for GCP)
 107       GCP account file
 108   --gcp-zone (default: us-central1-f)
 109       GCP zone
 110   --azure-secrets-file (default: false, required if building for Azure)
 111       Azure secrets file which will be sourced from this script
 112   --azure-resource-group (default: false, required if building for Azure)
 113       Azure resource group
 114   --azure-location (default: false, required if building for Azure)
 115       Azure location, e.g. centralus, eastus, westeurope
 116   --azure-sku (default: unset, required if building for Azure, e.g. 16.04-LTS)
 117       Azure SKU image to use
 118   --ssh_user  (default: packer)
 119       The user packer will use to log into the image
 120   --resolver (default: host's network provided)
 121       The dns resolver for the machine
 122   --reposuffix (default: unset)
 123       Set this to "-dev" to track the unstable/dev Arvados repositories
 124   --public-key-file (required)
 125       Path to the public key file that a-d-c will use to log into the compute node
 126   --mksquashfs-mem (default: 256M)
 127       Only relevant when using Singularity. This is the amount of memory mksquashfs is allowed to use.
 128   --nvidia-gpu-support (default: false)
 129       Install all the necessary tooling for Nvidia GPU support
 130   --debug (default: false)
 131       Output debug information
 132 </code></pre></notextile>
 133
 134 h2(#building). NVIDIA GPU support
 135
 136 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.
 137
 138 h2(#aws). Build an AWS image
 139
 140 <notextile><pre><code>~$ <span class="userinput">./build.sh --json-file arvados-images-aws.json \
 141            --arvados-cluster-id ClusterID \
 142            --aws-profile AWSProfile \
 143            --aws-source-ami AMI \
 144            --aws-vpc-id VPC \
 145            --aws-subnet-id Subnet \
 146            --ssh_user admin \
 147            --resolver ResolverIP \
 148            --public-key-file ArvadosDispatchCloudPublicKeyPath
 149 </span>
 150 </code></pre></notextile>
 151
 152 For @ClusterID@, fill in your cluster ID. The @VPC@ and @Subnet@ should be configured for where you want the compute image to be generated and stored. 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/.
 153
 154 @AWSProfile@ should be replaced with the name of an AWS profile with sufficient permissions to create the image.
 155
 156 @ArvadosDispatchCloudPublicKeyPath@ should be replaced with the path to the ssh *public* key file generated in "Create an SSH keypair":#sshkeypair, above.
 157
 158 Compute nodes must be able to resolve the hostnames of the API server and any keepstore servers to your internal IP addresses. You can do this by running an internal DNS resolver. The IP address of the resolver should replace the string @ResolverIP@ in the command above.
 159
 160 Alternatively, the services could be hardcoded into an @/etc/hosts@ file. For example:
 161
 162 <notextile><pre><code>10.20.30.40     <span class="userinput">ClusterID.example.com</span>
 163 10.20.30.41     <span class="userinput">keep1.ClusterID.example.com</span>
 164 10.20.30.42     <span class="userinput">keep2.ClusterID.example.com</span>
 165 </code></pre></notextile>
 166
 167 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.
 168
 169 h2(#azure). Build an Azure image
 170
 171 <notextile><pre><code>~$ <span class="userinput">./build.sh --json-file arvados-images-azure.json \
 172            --arvados-cluster-id ClusterID \
 173            --azure-resource-group ResourceGroup \
 174            --azure-location AzureRegion \
 175            --azure-sku AzureSKU \
 176            --azure-secrets-file AzureSecretsFilePath \
 177            --resolver ResolverIP \
 178            --public-key-file ArvadosDispatchCloudPublicKeyPath
 179 </span>
 180 </code></pre></notextile>
 181
 182 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.
 183
 184 @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:
 185
 186 <notextile><pre><code>export ARM_CLIENT_ID=...
 187 export ARM_CLIENT_SECRET=...
 188 export ARM_SUBSCRIPTION_ID=...
 189 export ARM_TENANT_ID=...
 190 </code></pre></notextile>
 191
 192 These secrets can be generated from the Azure portal, or with the cli using a command like this:
 193
 194 <notextile><pre><code>~$ <span class="userinput">az ad sp create-for-rbac --name Packer --password ...</span>
 195 </code></pre></notextile>
 196
 197 @ArvadosDispatchCloudPublicKeyPath@ should be replaced with the path to the ssh *public* key file generated in "Create an SSH keypair":#sshkeypair, above.
 198
 199 Compute nodes must be able to resolve the hostnames of the API server and any keepstore servers to your internal IP addresses. You can do this by running an internal DNS resolver. The IP address of the resolver should replace the string @ResolverIP@ in the command above.
 200
 201 Alternatively, the services could be hardcoded into an @/etc/hosts@ file. For example:
 202
 203 <notextile><pre><code>10.20.30.40     <span class="userinput">ClusterID.example.com</span>
 204 10.20.30.41     <span class="userinput">keep1.ClusterID.example.com</span>
 205 10.20.30.42     <span class="userinput">keep2.ClusterID.example.com</span>
 206 </code></pre></notextile>
 207
 208 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.