{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

h2(#certificates). Choose the SSL/TLS configuration (SSL_MODE)

Arvados requires a valid TLS certificate to work correctly. This installer supports these options:

# @lets-encrypt@: "automatically obtain and install an SSL certificates for your hostnames":#lets-encrypt
# @bring-your-own@: "supply your own certificates in the @certs@ directory":#bring-your-own

h3(#lets-encrypt). Using a Let's Encrypt certificate

In the default configuration, this installer gets a valid certificate via Let's Encrypt. If you have the <b>CLUSTER.DOMAIN</b> domain in a route53 zone, you can set <b>USE_LETSENCRYPT_ROUTE53</b> to <b>YES</b> and supply appropriate credentials so that Let's Encrypt can use dns-01 validation to get the appropriate certificates.

<notextile>
<pre><code>SSL_MODE="lets-encrypt"
USE_LETSENCRYPT_ROUTE53="yes"
LE_AWS_REGION="us-east-1"
LE_AWS_ACCESS_KEY_ID="AKIABCDEFGHIJKLMNOPQ"
LE_AWS_SECRET_ACCESS_KEY="thisistherandomstringthatisyoursecretkey"
</code></pre>
</notextile>

Please note that when using AWS, EC2 instances can have a default hostname that ends with <i>amazonaws.com</i>. Let's Encrypt has a blacklist of domain names for which it will not issue certificates, and that blacklist includes the <i>amazonaws.com</i> domain, which means the default hostname can not be used to get a certificate from Let's Encrypt.

h3(#bring-your-own). Bring your own certificates

To supply your own certificates, change the configuration like this:

<notextile>
<pre><code>SSL_MODE="bring-your-own"
</code></pre>
</notextile>

{% include 'multi_host_install_custom_certificates' %}

All certificate files will be used by nginx. You may need to include intermediate certificates in your certificate files. See "the nginx documentation":http://nginx.org/en/docs/http/configuring_https_servers.html#chains for more details.

h4(#secure-tls-keys). Securing your TLS certificate keys (AWS specific) (optional)

When using @SSL_MODE=bring-your-own@, you can keep your TLS certificate keys encrypted on the server nodes. This reduces the risk of certificate leaks from node disk volumes snapshots or backups.

This feature is currently implemented in AWS by providing the certificate keys’ password via Amazon’s "Secrets Manager":https://aws.amazon.com/es/secrets-manager/ service, and installing appropriate services on the nodes that provide this password to nginx via a file that only lives in system RAM.

If you use the installer's Terraform code, the secret and related permission cloud resources are created automatically, and you can customize the secret's name by editing @terraform/services/terraform.tfvars@ and setting its suffix in @ssl_password_secret_name_suffix@.

In @local.params@ you need to set @SSL_KEY_ENCRYPTED@ to @yes@ and change the default values for @SSL_KEY_AWS_SECRET_NAME@ and @SSL_KEY_AWS_REGION@ if necessary.

Then, if your certificate key file is not yet encrypted, you can generated an encrypted version of it by running the @openssl@ command as follows:

<notextile>
<pre><code>openssl rsa -aes256 -in your.key -out your.encrypted.key
</code></pre>
</notextile>
(this will ask you to type the encryption password)

This encrypted key file will be the one needed to be copied to the @${CUSTOM_CERTS_DIR}@ directory, instead of the plain key file.

In order to allow the appropriate nodes decrypt the key file, you should set the password on Amazon Secrets Manager. There're a couple way this can be done:

# Through AWS web interface may be the easiest, just make sure to set it as "plain text" instead of JSON.
# By using the AWS CLI tools, for example:
<notextile>
<pre><code>aws secretsmanager put-secret-value --secret-id pkey-pwd --secret-string "p455w0rd" --region us-east-1
</code></pre>
</notextile>Where @pkey-pwd@ should match with what's set in @SSL_KEY_AWS_SECRET_NAME@ and @us-east-1@ with what's set in @SSL_KEY_AWS_REGION@.

Take into account that the AWS secret should be set before running @installer.sh deploy@ to avoid any failures when trying to start the @nginx@ servers.

If you ever need to change the encryption password on a running cluster, you should first change the secret's value on AWS, and only then copy the newly encrypted key file to @${CUSTOM_CERTS_DIR}@ and re-run the deploy command.