Secrets

Secrets are sensitive bits of information like OAuth tokens, secret keys or API keys - information that you need in your application code, but shouldn't commit to your source code. In the AWS Copilot CLI, secrets are passed in as environment variables (read more about developing with environment variables), but they're treated differently due to their sensitive nature.

How do I add Secrets?

Adding secrets requires you to store your secret in AWS Systems Manager Parameter Store (SSM) or in AWS Secrets Manager, then add a reference to the secret in your manifest.

You can easily create a secret in SSM as a SecureString using copilot secret init!

Bring Your Own Secrets

In SSM

If you want to bring your own secrets, be sure to add two tags to your secrets:

Key	Value
copilot-application	Application name from which you want to access the secret
copilot-environment	Environment name from which you want to access the secret

Copilot requires the copilot-application and copilot-environment tags to limit access to this secret.

Suppose you have a (properly tagged!) SSM parameter named GH_WEBHOOK_SECRET with value secretvalue1234. You can modify your manifest file to pass in this value:

secrets:                      
  GITHUB_WEBHOOK_SECRET: GH_WEBHOOK_SECRET  

Once you deploy this updated manifest, your service or job will be able to access the environment variable GITHUB_WEBHOOK_SECRET, which will have the value of the SSM parameter GH_WEBHOOK_SECRET, secretvalue1234.
This works because ECS Agent will resolve the SSM parameter when it starts up your task, and set the environment variable for you.

In Secrets Manager

Similar to SSM, first ensure that your Secrets Manager secret has the copilot-application and copilot-environment tags.

Suppose you have a Secrets Manager secret with the following configuration:

Field	Value
Name	mysql
ARN	arn:aws:secretsmanager:us-west-2:111122223333:secret:demo/test/mysql-Yi6mvL
Value	{"engine": "mysql","username": "user1","password": "i29wwX!%9wFV","host": "my-database-endpoint.us-east-1.rds.amazonaws.com","dbname": "myDatabase","port": "3306"}
Tags	copilot-application=demo, copilot-environment=test

You can modify your manifest file with:

secrets:
  # Option 1. Referring to the secret by name, if your secret name does not end with a hyphen followed by 6 characters  (e.g. mysql). If it does (e.g. mysql-dbconf), see Option 2.
  DB:
    secretsmanager: 'mysql'
  # You can refer to a specific key in the JSON blob.
  DB_PASSWORD:
    secretsmanager: 'mysql:password::'

  # Option 2. Refering to the secret by name, with the random 6-character suffix.
  # If the secret name contains a hyphen followed by 6 letters (e.g. mysql-dbconf instead of mysql), then you have to include the 6-character suffix. Otherwise, secretsmanager won't be able to find your secret.
  MYSQL_DB:
    secretsmanager: 'demo/test/mysql-dbconf-Vi3nwL'

  # Option 3. Alternatively, you can refer to the secret by ARN.
  DB: "'arn:aws:secretsmanager:us-west-2:111122223333:secret:demo/test/mysql-Yi6mvL'"