AWS Secrets Manager

Prerequisites

• An AWS account with Secrets Manager enabled in your target region
• The ev API server must be able to reach AWS (credentials configured on the server, not the client)
• ev login and a project already initialized

IAM Policy

Create an IAM policy that allows ev to manage secrets under your prefix. Scope the Resource to your prefix to follow least-privilege.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:ListSecrets",
        "secretsmanager:GetSecretValue",
        "secretsmanager:CreateSecret",
        "secretsmanager:UpdateSecret",
        "secretsmanager:DeleteSecret"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:/myapp/*"
    }
  ]
}

Attach this policy to the IAM user or role used by the ev API server.

Credential Options

The ev API server (not your local machine) needs AWS credentials. There are three options:

Option A: Environment variables on the API server

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1

Option B: IAM role (recommended for production)

Attach the IAM policy to the EC2 instance profile, ECS task role, or Lambda execution role that the ev API runs on. No credentials need to be explicitly configured.

Option C: AWS credentials file

Place ~/.aws/credentials on the machine running the ev API with a profile that has the required permissions.

Connect ev to AWS SM

Once credentials are configured on the API server, run this on your local machine:

ev backend set aws-secrets-manager --region us-east-1 --prefix /myapp/

ev tests the connection before saving. If credentials are not configured on the server, you will see a clear error message.

Import Existing Secrets

If you already have secrets in AWS SM, import them into ev's release history:

ev import aws-secrets-manager --region us-east-1 --prefix /myapp/prod/ --env prod
ev import aws-secrets-manager --region us-east-1 --prefix /myapp/dev/ --env dev

Per-Environment Override

Keep local dev on ev's encrypted storage while prod uses AWS SM:

ev backend set ev --env dev

This writes to ev.yaml:

backend:
  type: aws-secrets-manager
  region: us-east-1
  prefix: /myapp/
 
environments:
  dev:
    backend:
      type: ev

How Secrets Are Stored in AWS SM

When you run ev push, each secret is stored as a separate entry in AWS SM using the path:

{prefix}{environment}/{KEY}

For example, with prefix /myapp/ and environment prod:

/myapp/prod/DATABASE_URL
/myapp/prod/SECRET_KEY
/myapp/prod/NODE_ENV

Your Terraform, ECS task definitions, and Lambda functions reference these paths directly. ev does not change the path structure of existing secrets.

Limitations

Related

• Storage Backends overview
• ev backend command
• ev import command