AWS Secrets Manager

This article walks you through the steps required to integrate your AWS Secrets Manager with Hyperscience.

Configure AWS Secrets Manager

To configure the AWS Secrets Manager integration, follow the steps below:

  1. Determine and configure your authentication scheme with AWS.

    • If you’re using a Virtual Private Cloud (VPC) in AWS in which your EC2 machines use IAM roles with access to secrets, no additional configuration may be required for this step.

    • If you’re using an access key approach with a pair of AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY keys, you’ll need to configure authentication. To learn more about environment variables, the shared credential file, and the AWS config file, see the “Configuring credentials” section of Amazon’s Boto3 Developer guide.

  2. Depending on the version used, the secrets.yml or .secrets file maps any secrets to retrieve the appropriate environment variables.

    • In v32 to v35.0.6, this mapping is done by the secrets.yml file. See the "[v32 to v35.0.6] Configure secrets.yml" section below for more information.

    • In v35.0.7 and later, a .secrets file can be used instead of secrets.yml. This file uses the same structure for variables as the “.env” file. For example, a typical variable in the .secrets file looks like this:

      FORMS_DB_PASS=hs/prod/db_password

      Place the secrets.yml or the .secrets file in the same folder as the “.env” file.

    • The secrets.yml file is backward compatible. If you have configured this file in a previous version of Hyperscience, you do not need to configure a .secrets file. If both secrets.yml and .secrets files exist, the integration will ignore the .secrets file.

  3. Confirm that the secrets manager works outside of Hyperscience.

  4. In the “.env” file, add the following variable and value:

    HS_SECRETS_MANAGER=awssecretsmanager
  5. Restart the Hyperscience application with the following commands. Make sure that the commands work as expected.

    sudo bash run.sh init
    sudo bash run.sh --restart --clean
  6. Rotate the secrets and restart the application with the above commands again. Make sure that the Hyperscience application starts successfully upon restart.

[v32 to v35.0.6] Configure secrets.yml

The secrets.yml file defines a format for mapping an environment variable to a location where a secret is stored. There are no sensitive values in the secrets.yml file itself.

For example, a typical secrets.yml file looks like this:

FORMS_DB_PASS: !var hs/prod/db_password

To learn more about secrets.yml, see Summon’s secrets.yml guide. Summon is a command-line tool that reads a file in secrets.yml format and injects secrets as environment variables into any process. You do not need to download Summon, as the tool is part of our AWS Secrets Manager integration.