Deploy a DSS instance on Amazon Web Services to terraform¶

This terraform module creates a Kubernetes cluster in Amazon Web Services using the Elastic Kubernetes Service (EKS) and generates the tanka files to deploy a DSS instance.

Getting started¶

Prerequisites¶

Download & install the following tools to your workstation:

Install terraform.
Install tools from Prerequisites
Install AWS specific tools:
Install and initialize AWS CLI.
1. Confirm successful installation with aws --version.
If you don't have an account, sign-up: https://aws.amazon.com/free/
Configure terraform to connect to AWS using your account.
1. We recommend to create an AWS_PROFILE using for instance aws configure --profile aws-interuss-dss Before running terraform commands, run once in your shell: export AWS_PROFILE=aws-interuss-dss Other methods are described here: https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration

Deployment of the Kubernetes cluster¶

Paths in the documentation

In the documentation, we often refer to path starting from the root (prefixed with /). This is to indicate that the path is relative to the root of the repository.

Create a new folder in /deploy/infrastructure/personal/ for the deployment named for example: terraform-aws-dss-dev
From /deploy/infrastructure/modules/terraform-aws-dss, copy main.tf, output.tf, variables.gen.tf and terraform.dev.example.tfvars to the infrastructure personal folder.
In the infrastructure personal folder (eg /deploy/infrastructure/personal/terraform-aws-dss-dev):
1. Rename terraform.dev.example.tfvars to terraform.tfvars.
2. Check that the directory contains the following files:
  1. main.tf
  2. output.tf
  3. terraform.tfvars
  4. variables.gen.tf
3. Set the variables in terraform.tfvars according to your environment. See TFVARS.gen.md for variables descriptions.
4. Initialize terraform: terraform init.
5. Run terraform plan to check that the configuration is valid. It will display the resources which will be provisioned.
6. Run terraform apply to deploy the cluster. (This operation may take up to 15 min.)
Configure the DNS resolution according to these instructions:

Terraform managedManual setup

If your DNS zone is managed on the same account, it is possible to instruct terraform to create and manage it with the rest of the infrastructure.

For Elastic Kubernetes Service (AWS), create the zone in your aws account and set the aws_route53_zone_id variable with the zone id. Entries will be automatically created by terraform. Note that the domain or the sub-domain managed by the zone must be properly delegated by the parent domain. See instructions for subdomains delegation

If DNS entries are managed manually, set them up manually using the following steps: 1. Retrieve IP addresses and expected hostnames: terraform output Example of expected output:

crdb_addresses = [
    {
        "address" = "34.65.15.23"
        "expected_dns" = "0.interuss.example.com"
    },
    {
        "address" = "34.65.146.56"
        "expected_dns" = "1.interuss.example.com"
    },
    {
        "address" = "34.65.191.145"
        "expected_dns" = "2.interuss.example.com"
    },
]
gateway_address = {
    "address" = "35.186.236.146"
    "expected_dns" = "dss.interuss.example.com"  
    "certificate_validation_dns" = [
     {
       "managed_by_terraform" = false
       "name" = "_6e246283563dcf58e7ed.interuss.example.com."
       "records" = [
          "_6e246283563dcf58e7ed.xxxxx.acm-validations.aws.",
       ]
       "type" = "CNAME"
     },
    ]
}

2. Create the following DNS A entries to point to the static ips indicated in the output: - crdb_addresses[*].expected_dns - gateway_address.expected_dns 3. Create the entries for SSL certificate validation according to the information provided in gateway_address.certificate_validation_dns.

Deployment of the DSS services¶

During the successful run, the terraform job has created a new workspace for the cluster. The new workspace name corresponds to the cluster context. The cluster context can be retrieved by running terraform output in your infrastructure folder (ie /deploy/infrastructure/personal/terraform-aws-dss-dev).

It contains scripts to operate the cluster and setup the services.

Go to the new workspace /build/workspace/${cluster_context}.
1. Run ./get-credentials.sh to login to kubernetes. You can now access the cluster with kubectl.
Prepare the datastore certificates:

YugabyteCockroachDB

Generate the certificates using ./dss-certs.sh init
If joining a cluster, check dss-certs.sh's help to add others CA in your pool and share your CA with others pools members.
Deploy the certificates using ./dss-certs.sh apply.

Generate the certificates using ./make-certs.sh. Follow script instructions if you are not initializing the cluster.
Deploy the certificates using ./apply-certs.sh.

Go to the tanka workspace in /deploy/services/tanka/workspace/${cluster_context}.
Run tk apply . to deploy the services to kubernetes. (This may take up to 30 min)
Wait for services to initialize:
- On AWS, load balancers and certificates are created by Kubernetes Operators. Therefore, it may take few minutes (~5min) to get the services up and running and generate the certificate. To track this progress, go to the following pages and check that:
  - On the EKS page, the status of the kubernetes cluster should be Active.
  - On the EC2 page, the load balancers (1 for the gateway, 1 per cockroach nodes) are in the state Active.
Verify that basic services are functioning by navigating to https://your-gateway-domain.com/healthy.

Clean up¶

Note that the following operations can't be reverted and all data will be lost.
To delete all resources, run tk delete . in the workspace folder.
Make sure that all load balancers and target groups have been deleted from the AWS region before next step.
terraform destroy in your infrastructure folder.
On the EBS page, make sure to manually clean up the persistent storage. Note that the correct AWS region shall be selected.