AWS deployment

Owner: Cloud Ops

Returns to: 3. Configure & install Helm

This path provisions Amazon EKS, Aurora PostgreSQL, AWS Secrets Manager, workload identities through IRSA, and an ALB with an ACM certificate.

1. Get the Terraform release

git clone https://github.com/try-caret/arbium-terraform.git
cd arbium-terraform
git checkout chaindb-v<release-version>
cd aws/customer
cp envs/example.tfvars envs/<environment>.tfvars

Use the same release number for Terraform and the Helm chart. Do not track main for a customer environment.

2. Configure the AWS foundation

Set the region, environment, non-overlapping network ranges, node sizing, and database protection in the copied file. The example file documents all inputs. A typical production baseline includes:

aws_region  = "us-east-1"
environment = "<environment>"
name_prefix = "arbium"

cluster_endpoint_public_access  = true
cluster_endpoint_private_access = true

general_node_instance_types = ["m6i.large"]
general_node_min_size       = 1
general_node_desired_size   = 2
general_node_max_size       = 3

# Leave at zero when using the CPU embedder or while GPU quota is pending.
gpu_node_desired_size = 0
gpu_node_max_size     = 1

aurora_backup_retention_days = 7
aurora_deletion_protection   = true
aurora_skip_final_snapshot   = false

create_ingress_certificate = true
ingress_domain_name        = "arbium.<customer-domain>"

# Secret containers only; values are populated out of band.
secret_names = [
  "scheduler", "scim", "sentry", "registry", "gemini",
  "enrollment", "jwt", "license", "admin-client-id",
  "admin-client-secret"
]

Confirm the region has capacity and quota for the selected general and GPU instance types. Keep secret values out of .tfvars.

3. Plan and apply

terraform init
terraform fmt -recursive
terraform validate
AWS_PROFILE=<profile> terraform plan  -var-file=envs/<environment>.tfvars
AWS_PROFILE=<profile> terraform apply -var-file=envs/<environment>.tfvars

The apply creates the VPC, private and public subnets, EKS, Aurora, Secrets Manager containers, AWS Load Balancer Controller, External Secrets Operator, and the IRSA roles used by the cluster.

4. Configure cluster access

aws eks update-kubeconfig \
  --profile <profile> \
  --region <aws-region> \
  --name "$(terraform output -raw cluster_name)"

kubectl get nodes
kubectl get pods -n kube-system -l app.kubernetes.io/name=aws-load-balancer-controller
kubectl get pods -n external-secrets

All general nodes and both cluster add-ons should be ready. If GPU mode is enabled, the GPU node should advertise nvidia.com/gpu and tolerate the workload=embedder:NoSchedule taint.

5. Validate the ACM certificate

Create the DNS validation record returned by:

terraform output ingress_certificate_validation_records

Keep that CNAME DNS-only if the DNS provider supports proxying. Wait until the certificate is issued:

$(terraform output -raw ingress_certificate_status_check_command)

The final application DNS record is created after Helm provisions the ALB.

6. Populate AWS Secrets Manager

Terraform creates the containers; populate their values through the customer’s approved secret-management workflow. Required values are:

Secret	Value
arbium/<env>/scheduler	Random scheduler token
arbium/<env>/enrollment	Random enrollment secret
arbium/<env>/jwt	Random 32-byte JWT secret
arbium/<env>/gemini	Approved Gemini API key, when enabled
arbium/<env>/license	Arbium license key
arbium/<env>/registry	JSON {"username":"...","token":"..."} for GHCR
arbium/<env>/scim	Random SCIM bearer token, when SCIM is enabled
arbium/<env>/admin-client-id	Arbium Admin app client ID, when enabled
arbium/<env>/admin-client-secret	Arbium Admin app secret, when enabled

Aurora’s RDS-managed master-user secret remains the source of truth for the database username and password; do not copy it into another secret.

7. Create the AWS provider values

Save the following as <environment>.aws.values.local.yaml outside source control. Substitute Terraform outputs and omit the optional extraSecrets, scim, and admin blocks when the fleet console is disabled.

global:
  region: <aws-region>

imagePullSecrets:
  - name: ghcr-pull

externalSecrets:
  enabled: true
  provider: aws
  region: <aws-region>
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: <terraform-output-arbium_eso_role_arn>
  db:
    fromManagedSecret: <terraform-output-aurora_master_user_secret_arn>
    host: <terraform-output-aurora_cluster_endpoint>
    name: <terraform-output-aurora_database_name>
    params: sslmode=require
  dataMappings:
    CHAINDB_SCHEDULER_TOKEN: arbium/<env>/scheduler
    ARBOR_AGENT_ENROLLMENT_SECRET: arbium/<env>/enrollment
    ROOTS_INTUNE_PILOT_ENROLLMENT_SECRET: arbium/<env>/enrollment
    GEMINI_API_KEY: arbium/<env>/gemini
    JWT_SECRET: arbium/<env>/jwt
    ARBIUM_LICENSE_KEY: arbium/<env>/license
  imagePullSecret:
    enabled: true
    secretId: arbium/<env>/registry
    targetSecretName: ghcr-pull
  extraSecrets:
    scim-bearer:
      SCIM_BEARER_TOKEN: arbium/<env>/scim
    admin-ui-oidc:
      OIDC_CLIENT_ID: arbium/<env>/admin-client-id
      OIDC_CLIENT_SECRET: arbium/<env>/admin-client-secret

secrets:
  create: false
  existingSecret: chaindb-runtime

license:
  existingSecret: chaindb-runtime

cloudSqlProxy:
  enabled: false

config:
  databaseSsl: require

ingress:
  enabled: true
  host: arbium.<customer-domain>
  scheme: internet-facing
  certificateArn: <terraform-output-ingress_certificate_arn>

embedder:
  enabled: true
  gpu:
    enabled: false

Set embedder.gpu.enabled: true only after the EKS GPU node group is ready.

8. Record the provider outputs

Keep these for the shared steps:

terraform output cluster_name
terraform output aurora_cluster_endpoint
terraform output aurora_master_user_secret_arn
terraform output arbium_eso_role_arn
terraform output ingress_certificate_arn

Continue to 3. Configure & install Helm. After Helm creates the Ingress, point the final DNS CNAME or Route 53 alias at the ALB hostname.