AWS EKS Chainlink whitepaper

AWS EKS Chainlink whitepaper is a Terraform project that deploys a Chainlink node and adapters on AWS EKS. The steps taken by TrackIt to build a secure, reliable, and scalable Chainlink environment are outlined in this article (FIXME). Multiple Terraform modules supported by the AWS community were employed to deploy the AWS infrastructure. Note that these steps are not intended for a production environment, but they will help you set up your first Chainlink node.

Quick Start

Prerequisites

• Terraform ~> 1.3.9 (you can use tfenv to manager your Terraform versions)
• An ETH URL from an ETH Client (i.e.: Infura)
• SOPS
• AWS CLI v2

Terraform Backend

You need to have a Terraform backend configured to store the Terraform state. You can use the S3 backend with DynamoDB for state locking:

1. Create your S3 bucket (replace bucket_name with your bucket name and aws_region with your AWS region):

aws s3api create-bucket --bucket {{bucket_name}} --region {{aws_region}} --create-bucket-configuration LocationConstraint={{aws_region}}

2. Create your DynamoDB table with the following command (replace {{table_name}} with your table name and {{region}} with your AWS region):

aws dynamodb create-table --table-name {{table_name}} --attribute-definitions AttributeName=LockID,AttributeType=S --key-schema AttributeName=LockID,KeyType=HASH --billing-mode PAY_PER_REQUEST --region {{region}}

Usage

Setup

Terraform

1. Update the provider with your Terraform S3 backend and provider configuration. For example, with us-east-1 as the region, terraform-state as the S3 bucket name, and terraform-state-lock as the DynamoDB table name:

terraform {
  required_version = "~> 1.3.9"
  backend "s3" {
    bucket         = "terraform-state"
    key            = "terraform.state"
    region         = "us-east-1"
    dynamodb_table = "terraform-state-lock"
  }

  required_providers {
    sops = {
      source  = "carlpett/sops"
      version = "~> 0.5"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

provider "sops" {}

2. Create a KMS key in AWS to encrypt your secrets.
3. Create a new tfvars file for your environment, i.e.: envs/dev.tfvars for the dev environment.
   1. Fill in the values for the variables (example.tfvars contains an example of how it could look like).
   2. Create the env folder for your secrets: mkdir tf/secrets/dev.

Secrets: SOPS

1. Create a new file clear-dev-secrets.yaml which is going to contain the secrets for your environment.
2. Fill in the values for the secrets (use clear-secrets.yaml as an example).
3. Encrypt secrets (KMS Key ARN is needed):

export SOPS_KMS_ARN=arn:aws:kms:REGION:ACCOUNT_ID:key/KMS_KEY_ID
sops -e clear-secrets.yaml > ./tf/secrets/dev/encrypted-secrets.yaml

The encrypted file needs to be in the tf/secrets/<env> folder and named encrypted-secrets.yaml.

Deployment

Once you have completed the setup, you can follow these steps to deploy the Chainlink node and adapters:

1. Open a terminal and go to the tf folder: cd tf
2. Initialize Terraform:

terraform init

3. (optional) If you want to use workspace, you need to create it (if the workspace does not exist) and select it:

terraform workspace new dev && terraform workspace select dev

4. Plan the deployment to verify that the deployment matches your configuration:

terraform plan --var-file ../envs/dev.tfvars

5. Deploy the Infrastructure

terraform apply --var-file ../envs/dev.tfvars

Connect to the Cluster

kubectl is required to connect to the cluster. You can install it by following the official documentation.

Once your infrastructure is deployed, you can connect to the EKS cluster:

aws eks update-kubeconfig --name <CLUSTER_NAME> --region <AWS_REGION>
kubectl get pods 

Pods including Chainlink should be visible in the kubectl output. Copy the name of the Chainlink pod, and then use the following command to be able to access Chainlink UI on your machine:

kubectl port-forward <CHAINLINK_POD_NAME> 6688:6688

Open your browser and go to http://localhost:6688/ to access the Chainlink UI and fill your user credentials.

Go Further

If you want to go further and customize your Chainlink node and adapters you can look at our Chainlink Helm Charts documentation.

Known Issues

Terraform Destroy

When destroying the Terraform project, the following error may occur:

╷
│ Error: deleting EC2 EIP (eipalloc-XXXX): disassociating: AuthFailure: You do not have permission to access the specified resource.
│       status code: 400, request id: XXXX
│ 
│ 
╵

Temporary workaround: destroy the project again.

Terraform

Requirements

Name	Version
terraform	~> 1.3.9
sops	~> 0.5

Providers

Name	Version
aws	n/a
helm	n/a
kubernetes	n/a
sops	~> 0.5

Modules

Name	Source	Version
eks	terraform-aws-modules/eks/aws	~> 18.0
rds	terraform-aws-modules/rds-aurora/aws	~>6.1.4
vpc	terraform-aws-modules/vpc/aws	~> v3.10.0

Resources

Name	Type
aws_eip.p2p_ingress_a	resource
aws_eip.p2p_ingress_b	resource
aws_kms_key.eks	resource
aws_secretsmanager_secret.rds_url	resource
aws_secretsmanager_secret_version.url	resource
aws_security_group.additional	resource
helm_release.adapters	resource
helm_release.chainlink	resource
helm_release.grafana	resource
helm_release.prometheus	resource
kubernetes_secret.api_secrets	resource
aws_caller_identity.current	data source
aws_eks_cluster.cluster	data source
aws_eks_cluster_auth.cluster	data source
sops_file.secrets	data source

Inputs

Name	Description	Type	Default	Required
aws_auth_roles	List of AWS roles to map to Kubernetes users	list(object({ rolearn = string # AWS Role username = string # Username in Kubernetes groups = list(string) # Group in Kubernetes }))	[]	no
aws_auth_users	List of AWS users to map to Kubernetes users	list(object({ userarn = string # AWS User username = string # Username in Kubernetes groups = list(string) # Group in Kubernetes }))	[]	no
chainlink_acm_certificate_arn	Your ACM Certificate ARN (Route53 and LoadBalancer unimplemented)	string	"fake-acm-chainlink"	no
chainlink_dev	Whether or not to run Chainlink in dev mode	string	"true"	no
chainlink_domain_name	Your Chainlink Domain Name (Route53 and LoadBalancer unimplemented)	string	n/a	yes
chainlink_eth_chain_id	Your ETH Chain ID	string	n/a	yes
env	Environment name	string	n/a	yes
eth_url	Your WSS ETH URL	string	n/a	yes
kms_key_id	Your KMS Key ID for decrypting secrets with SOPS	string	n/a	yes
name	The name of the Chainlink deployment	string	"chainlink"	no
p2p_bootstrap_peers	Default set of bootstrap peers (see https://docs.chain.link/chainlink-nodes/v1/configuration/#p2p_bootstrap_peers)	string	""	no
rds_instance_type	RDS Instance Type (see https://aws.amazon.com/rds/instance-types/)	string	"db.r6g.large"	no
user_email	Email address for the Chainlink initial user	string	"[email protected]"	no
vpc_azs	VPC Availability Zones	list(string)	[ "us-east-2a", "us-east-2b" ]	no
vpc_cidr	VPC CIDR	string	"10.10.0.0/16"	no
vpc_database_cidrs	VPC Database Subnets CIDR	list(string)	[ "10.10.200.0/24", "10.10.201.0/24" ]	no
vpc_private_cidrs	VPC Private Subnets CIDR	list(string)	[ "10.10.100.0/24", "10.10.101.0/24" ]	no
vpc_public_cidrs	VPC Public Subnets CIDR	list(string)	[ "10.10.0.0/24", "10.10.1.0/24" ]	no

Outputs

No outputs.