Document function environment variables and secrets

[FirstSanny]

Environment information

System:
  OS: macOS 13.0.1
  CPU: (16) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
  Memory: 1.16 GB / 16.00 GB
  Shell: /bin/sh
Binaries:
  Node: 21.0.0 - /usr/local/bin/node
  Yarn: 1.22.21 - /usr/local/bin/yarn
  npm: 10.2.2 - /usr/local/bin/npm
  pnpm: 8.15.3 - /usr/local/bin/pnpm
NPM Packages:
  @aws-amplify/backend: 0.12.1
  @aws-amplify/backend-cli: 0.11.1
  aws-amplify: 6.0.17
  aws-cdk: 2.129.0
  aws-cdk-lib: 2.129.0
  typescript: 5.3.3
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!                                                                                                                      !!
!!  This software has not been tested with node v21.0.0.                                                                !!
!!  Should you encounter odd runtime issues, please try using one of the supported release before filing a bug report.  !!
!!                                                                                                                      !!
!!  This software is currently running on node v21.0.0.                                                                 !!
!!  As of the current release of this software, supported node releases are:                                            !!
!!  - ^20.0.0 (Planned end-of-life: 2026-04-30)                                                                         !!
!!  - ^18.0.0 (Planned end-of-life: 2025-04-30)                                                                         !!
!!                                                                                                                      !!
!!  This warning can be silenced by setting the JSII_SILENCE_WARNING_UNTESTED_NODE_VERSION environment variable.        !!
!!                                                                                                                      !!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
AWS environment variables:
  AWS_STS_REGIONAL_ENDPOINTS = regional
  AWS_NODEJS_CONNECTION_REUSE_ENABLED = 1
  AWS_SDK_LOAD_CONFIG = 1
No CDK environment variables

Description

The secrets arent getting loaded into my app. It works if I just hardcode them (thats how I figured, it's something about the secrets). It is also worth to mention, that if I wouldn't double cast them, typescript would throw an error, because it is recognising it as an object of type BackendSecret.

This is the code:

import { secret } from "@aws-amplify/backend";

class ShopifyClient {
  private shopifyGQLClient: GraphqlClient;
  constructor() {
    // const shopifyHostName = <string>process.env.SHOPIFY_HOST_NAME;

    const shopifyApiKey = <string>(<unknown>secret("SHOPIFY_API_KEY"));
    console.log(shopifyApiKey);
    const shopifyApiSecretKey = <string>(
      (<unknown>secret("SHOPIFY_API_SECRET_KEY"))
    );
    const shopifyAdminApiAccessToken = <string>(
      (<unknown>secret("SHOPIFY_ADMIN_API_ACCESS_TOKEN"))
    );

I added for alle branches and my sandbox. But no luck...

[edwardfoyle]

Hi @FirstSanny, the secret('name') pattern can only be used in specific places within a backend. It cannot be used to resolve secrets in arbitrary locations within CDK code. Specifically, it can be used within defineAuth to configure social providers and it can be used within defineFunction to to specify secret environment variables.

Can you explain more about where you are trying to use the secrets and what your use case is?

[FirstSanny]

Hello @edwardfoyle ,

thanks for your reply. Currently this class is defined in the amplify/clients folder and will be globally assigned to an default instance like this:

The issue came, when using this instance, but is it called inside of an defineFunction context. The finction is getting exported with the data export of the resource.ts

and used like this.

We can try to fetch the credentials inside of the handler function and pass them to the instance from there. Do you think this would work?

[FirstSanny]

Tried to fetch it directly in the handler and commented out all the others. Still not working and throwing errors

Code change:

Error:

[edwardfoyle]

@FirstSanny thanks for the additional context. The way you would do this is to define a secret environment variable in your function like so:

defineFunction({
  entry: './some/path.ts',
  environment: {
    SHOPIFY_API_KEY: secret('SHOPIFY_API_KEY')
  }
})

Then in your function code, you can use SHOPIFY_API_KEY as a normal environment variable:

export const handler = async () => {
  process.env.SHOPIFY_API_KEY // this will be the value of the API key when the lambda runs
}

We need to update our docs to describe this new behavior!

[FirstSanny]

That worked. Thanks.

[chucklam]

@edwardfoyle I'm trying something similar, but I want to access the secrets inside the Next.js API routes. Is there any easy way to do that? I imagine I can rewrite it as a Function fronted by an API Gateway and follow your example above, but hoping for a simpler solution.

[josefaidt]

Hey @chucklam you can manage secrets for branches from the Amplify console

https://docs.amplify.aws/gen2/deploy-and-host/fullstack-branching/secrets-and-vars

then you can echo to a dotenv file for your Next.js app

[jbp35]

@FirstSanny thanks for the additional context. The way you would do this is to define a secret environment variable in your function like so:

defineFunction({
  entry: './some/path.ts',
  environment: {
    SHOPIFY_API_KEY: secret('SHOPIFY_API_KEY')
  }
})

Then in your function code, you can use SHOPIFY_API_KEY as a normal environment variable:

export const handler = async () => {
  process.env.SHOPIFY_API_KEY // this will be the value of the API key when the lambda runs
}

We need to update our docs to describe this new behavior!

Is it supposed to work within the sandbox? I am using npx amplify sandbox secret XXXX to configure my secret but it only works when I deploy the branch. Thanks.

[chucklam]

Hey @chucklam you can manage secrets for branches from the Amplify console https://docs.amplify.aws/gen2/deploy-and-host/fullstack-branching/secrets-and-vars

then you can echo to a dotenv file for your Next.js app

I have set the secrets from the Amplify console. Not clear to me how to echo to a dotenv file though. I know I could do the following if I set NEXTAUTH_SECRET as an environment variable. But if I set it as a secret then the echo command isn't picking it up.

build:
  commands:
    - echo "NEXTAUTH_SECRET=$NEXTAUTH_SECRET" >> .env
    - npm run build

[bnova-stefan]

Hey @chucklam you can manage secrets for branches from the Amplify console https://docs.amplify.aws/gen2/deploy-and-host/fullstack-branching/secrets-and-vars

then you can echo to a dotenv file for your Next.js app

Hey @chucklam, @josefaidt
I have the same problem. I try to use a secret in my route. So what I tried it is the following:

I have defined the secrets in the amplify console:

And then I try to read the secrets and write them to a dotenv file

build:
  commands:
    - echo "KEYCLOAK_SECRET=$(echo $secrets | jq -r '.KEYCLOAK_SECRET')" >> .env

But if I look at the .env file the I get just null as value:

Do you have any solution for this in the meantime?

Many thanks and regards,
Stefan

[chucklam]

@bnova-stefan @josefaidt In fact if I just look at process.env.secrets, I get back an empty json object {}. Maybe I need to configure something to have the secrets show up there?

echo $secrets

[campbellgoe]

process.env.secrets seems to be empty if you didn't properly specify the app id and backend name, and seems to only be available during build time, not run time.

[owlyowl]

Did anyone get the echo secrets to a .env file to work?

[taraspos]

@bnova-stefan @josefaidt In fact if I just look at process.env.secrets, I get back an empty json object {}. Maybe I need to configure something to have the secrets show up there?

echo $secrets

@owlyowl Did anyone get the echo secrets to a .env file to work?

If you look at Amplify build logs, you will see log line like this:

2024-11-08T18:50:07.430Z [INFO]: ---- Setting Up SSM Secrets ----
2024-11-08T18:50:07.430Z [INFO]: SSM params {"Path":"/amplify/<app_id>/main/","WithDecryption":true}
2024-11-08T18:05:21.329Z [WARNING]: !Failed to set up process.env.secrets

[WARNING]: !Failed to set up process.env.secrets is happening if your IAM Service role doesn't have permissions to ssm: GetParametersByPath for the /amplify/<app_id>/ path. Once you configure this your IAM role, this warning should disappear and amplify will start reading them.

However, what's even more confusing, if you configure secrets through AWS Amplify Gen2 console as mentioned in the documentation¹.

It actually creates Parameters by path like /amplify/<app-id>/main-branch-<some-unknown-id>/<secret-name>.
Which is super confusing, however if you follow gen1 documentation² it will work and manually create secrets in SSM Parameter store by path /amplify/<app_id>/main/ it will work.

Also, see this super helpful comment:

• How to access the AWS Parameter Store secret variables from within amplify.yml amplify-hosting#3348 (comment)

Footnotes

1. https://docs.amplify.aws/react/deploy-and-host/fullstack-branching/secrets-and-vars/ ↩

2. https://docs.aws.amazon.com/amplify/latest/userguide/environment-secrets.html#set-environment-secrets ↩