Main site

Deploying CipherStash Proxy to AWS ECS

  • AWS Account: Make sure you have an active AWS account.
  • AWS CLI: Install and configure the AWS CLI with appropriate permissions.
  • Docker: Install Docker if you need to build and push the Docker image to AWS ECR.
  • CipherStash Proxy configuration: Refer to the CipherStash Proxy config for details.
  • AWS RDS instance: Create a PostgreSQL RDS instance in the same VPC as the ECS cluster you are deploying CipherStash Proxy into. You will need to known the hostname, port, username, password, subnet, and security group of the PostgreSQL RDS instance.

Create a CipherStash account, configuration, and credentials so that you can use Proxy:

1# Install the CipherStash CLI
2## macOS
3brew install cipherstash/tap/stash
4## Linux
5## Download from https://github.com/cipherstash/cli-releases/releases/latest
6
7# Setup your CipherStash configuration
8stash setup --proxy
9# ⬆️ this outputs credentials to .env.proxy.docker

Note down the credentials output to .env.proxy.docker — you will need these in Step 3 and Step 5.

You can deploy CipherStash Proxy to AWS ECS using the Docker image from the AWS Marketplace or Docker Hub.

If you want to purchase CipherStash Proxy from the AWS Marketplace, follow the instructions in this how to guide to pull the Docker image.

If you'd prefer to use the Docker Hub registry, push the cipherstash/proxy image to Amazon ECR (Elastic Container Registry) as follows:

1# Ensure you have set these environment variables:
2# export AWS_ACCOUNT_ID=111222333444
3# export AWS_REGION=ap-southeast-2
4
5set -u
6
7# Create an ECR repository to push the image to
8aws ecr create-repository --repository-name cipherstash-proxy
9
10# Authenticate local Docker to ECR repository
11aws ecr get-login-password | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com
12
13# Tag and push the image
14docker tag cipherstash/proxy:latest $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/cipherstash-proxy:latest
15docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/cipherstash/cipherstash-proxy:latest

Using the credentials from .env.proxy.docker that you obtained in Step 1, create a file named cipherstash-proxy-secrets.json, and populate it with these secrets:

1{
2  "CS_WORKSPACE_ID": "...",
3  "CS_CLIENT_ID": "...",
4  "CS_DEFAULT_KEYSET_ID": "...",
5  "CS_CLIENT_KEY": "...",
6  "CS_CLIENT_ACCESS_KEY": "...",
7  "CS_DATABASE__PASSWORD": "..."
8}

The value of CS_DATABASE__PASSWORD is the password of the PostgreSQL RDS instance.

Now create a secret in Secrets Manager:

1aws secretsmanager create-secret --name cipherstash-proxy --secret-string file://cipherstash-proxy-secrets.json

Note the ARN of the secret that is created — you will need it when creating the ECS task definition in Step 5.

If you need more help with creating secrets, read the AWS Secrets Manager documentation.

For all the components to work together, some IAM configuration is required:

Create a file named ecs-tasks-trust-policy.json for the trust policy, with the following contents:

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Sid": "",
6      "Effect": "Allow",
7      "Principal": {
8        "Service": "ecs-tasks.amazonaws.com"
9      },
10      "Action": "sts:AssumeRole"
11    }
12  ]
13}

This policy allows ECS to assume the IAM role.

Create an IAM role named ecsTaskExecutionRole, using the policy in ecs-tasks-trust-policy.json:

1aws iam create-role --role-name ecsTaskExecutionRole --assume-role-policy-document file://ecs-tasks-trust-policy.json

Note the ARN of the role that is created — you will need it when creating the ECS task definition in Step 5.

Create a file named cipherstash-proxy-ecs-policy.json for the inline policy, with the following contents, substituting the ARN of the Secrets Manager secret created in Step 3:

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": [
7        "secretsmanager:GetSecretValue",
8        "kms:Decrypt"
9      ],
10      "Resource": [
11        "ARN_OF_SECRETSMANAGER_SECRET"
12      ]
13    }
14  ]
15}

This policy allows ECS to fetch secrets from Secrets Manager.

Attach the inline policy to the ecsTaskExecutionRole, using the policy in cipherstash-proxy-ecs-policy.json:

1aws iam put-role-policy --role-name ecsTaskExecutionRole --policy-name CipherStashProxyECSPolicy --policy-document file://cipherstash-proxy-ecs-policy.json

Attach the AmazonECSTaskExecutionRolePolicy managed policy to the ecsTaskExecutionRole role:

1aws iam attach-role-policy --role-name ecsTaskExecutionRole --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

This policy allows ECS to pull container images from ECR, and send logs to CloudWatch.

The ECS task definition is used to configure the CipherStash Proxy container with:

  • environment variables
  • secrets
  • logging

Create a file named cipherstash-proxy-task-def.json for the ECS task definition, using the ARNs and identifiers created in the previous steps:

1{
2  "family": "cipherstash-proxy",
3  "networkMode": "awsvpc",
4  "executionRoleArn": "ARN_OF_ROLE_FROM_STEP_4.1",
5  "cpu": "256",
6  "memory": "512",
7  "containerDefinitions": [
8    {
9      "name": "cipherstash-proxy",
10      "image": "IMAGE_FROM_STEP_2",
11      "essential": true,
12      "portMappings": [
13        {
14          "containerPort": 6432,
15          "hostPort": 6432
16        },
17        {
18          "containerPort": 9930,
19          "hostPort": 9930
20        }
21      ],
22      "environment": [
23        {
24          "name": "CS_DATABASE__USERNAME",
25          "value": "RDS_USERNAME_FROM_PREREQUISITES"
26        },
27        {
28          "name": "CS_DATABASE__NAME",
29          "value": "RDS_DATABASE_NAME_FROM_PREREQUISITES"
30        },
31        {
32          "name": "CS_DATABASE__HOST",
33          "value": "RDS_HOSTNAME_FROM_PREREQUISITES"
34        },
35        {
36          "name": "CS_DATABASE__PORT",
37          "value": "RDS_PORT_FROM_PREREQUISITES"
38        },
39        {
40          "name": "CS_PROMETHEUS__ENABLED",
41          "value": "true"
42        },
43        {
44          "name": "CS_DATABASE__INSTALL_EQL",
45          "value": "true"
46        },
47        {
48          "name": "CS_DATABASE__INSTALL_EXAMPLE_SCHEMA",
49          "value": "true"
50        }
51      ],
52      "secrets": [
53        {
54          "name": "CS_WORKSPACE_ID",
55          "valueFrom": "ARN_OF_SECRET_FROM_STEP_3:CS_WORKSPACE_ID::"
56        },
57        {
58          "name": "CS_CLIENT_ID",
59          "valueFrom": "ARN_OF_SECRET_FROM_STEP_3:CS_CLIENT_ID::"
60        },
61        {
62          "name": "CS_DEFAULT_KEYSET_ID",
63          "valueFrom": "ARN_OF_SECRET_FROM_STEP_3:CS_DEFAULT_KEYSET_ID::"
64        },
65        {
66          "name": "CS_CLIENT_KEY",
67          "valueFrom": "ARN_OF_SECRET_FROM_STEP_3:CS_CLIENT_KEY::"
68        },
69        {
70          "name": "CS_CLIENT_ACCESS_KEY",
71          "valueFrom": "ARN_OF_SECRET_FROM_STEP_3:CS_CLIENT_ACCESS_KEY::"
72        },
73        {
74          "name": "CS_DATABASE__PASSWORD",
75          "valueFrom": "ARN_OF_SECRET_FROM_STEP_3:CS_DATABASE__PASSWORD::"
76        }
77      ],
78      "logConfiguration": {
79        "logDriver": "awslogs",
80        "options": {
81            "awslogs-group": "cipherstash-proxy",
82            "awslogs-region": "AWS_REGION",
83            "awslogs-stream-prefix": "cipherstash-proxy"
84        }
85      }
86    }
87  ],
88  "requiresCompatibilities": [
89    "FARGATE"
90  ],
91  "runtimePlatform": {
92    "operatingSystemFamily": "LINUX",
93    "cpuArchitecture": "ARM64"
94  }
95}

Ensure you have replaced placeholders with actual values from Step 2, Step 3, and Step 4.1.

Register the task definition using the AWS CLI:

1aws ecs register-task-definition --cli-input-json file://cipherstash-proxy-task-def.json

Now it's time to launch CipherStash Proxy in ECS.

Create an ECS cluster:

1aws ecs create-cluster --cluster-name ecs-app

Create a log group for CipherStash Proxy to send logs to:

1aws logs create-log-group --log-group-name cipherstash-proxy

Before you start the ECS service, make sure you have the subnet and security group that your PostgreSQL RDS instance is running in.

Create an ECS service using the task definition to run CipherStash Proxy:

1# Ensure you have set these environment variables:
2# export SUBNETS=
3# export SECURITY_GROUP=
4
5aws ecs create-service --cluster ecs-app --service-name CipherStashProxy --task-definition cipherstash-proxy --desired-count 1 --launch-type FARGATE --network-configuration "awsvpcConfiguration={subnets=[$SUBNETS], securityGroups=[$SECURITY_GROUP], assignPublicIp=ENABLED}"

Check the service and task status:

1# List services running in the cluster
2aws ecs list-services --cluster ecs-app
3
4# Show details of CipherStashProxy service
5aws ecs describe-services --cluster ecs-app --services CipherStashProxy
6
7# Tail the logs
8aws logs tail --since 6h --follow cipherstash-proxy
  • Security: Make sure sensitive data such as keys and passwords are managed securely, preferably using AWS Secrets Manager or Parameter Store.
  • Networking: Configure network settings properly to allow your ECS tasks to communicate with other services.
  • Scaling and management: Monitor the service and adjust scaling as necessary.

With CipherStash Proxy in place, you can now start encrypting your data.