Secrets usage is not documented properly and incredibly confusing

[taraspos]

Before opening, please confirm:

• I have checked to see if my question is addressed in the FAQ.
• I have searched for duplicate or closed issues.
• I have removed any sensitive information from my code snippets and submission.

Amplify Hosting feature

Build settings, Deployments, Environment variables, SSR

Is your feature request related to a problem? Please describe:

AWS Amplify Gen2 console has secrets section and following documentation page about how to use them:

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

However, it's way more confusing that it might look from the first glance.

Frontend build time secrets

1. Documentation says that secrets created through AWS Amplify Gen2 console are stored under the /amplify/<app-id>/<branch-name>/<secret-name>:
   

   • But in reality they are stored under the under the path like /amplify/<app-id>/<branch-name>-branch-<some-unknown-id>/<secret-name>, so amplify is failing to load them in Build Time::

     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}
     

   • Secrets configured as "for all branches" are created under the documented location /amplify/shared/<app_id>/, but they are not being picked up during the build.

2. Amplify Application needs IAM service role assigned permissions to do ssm: GetParametersByPath for the arn:<partition>:ssm:<region>:<account_id>:parameter/amplify/<app_id>/. Otherwise you will also see warning like [WARNING]: !Failed to set up process.env.secrets ¹

4. None of this is explained in the documentation:
   • https://docs.amplify.aws/react/deploy-and-host/fullstack-branching/secrets-and-vars/ - this documentation page says that it should be accessed via import { defineAuth, secret } from '@aws-amplify/backend'; but it doesn't explain that this works only for backend applications²
   • Instead you need to follow Gen1 documentation, which is counter-intuitive, because we're using Gen2 app, right?

See this comment for additional details:

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

Fronted run time secrets

All above also applies to the Frontend runtime secrets, but frontend runtime doesn't support env variables and seems you need to write them to the .env file instead³, however that would expose plaintext secret values in downloaded build artifact. And seems there are no other workarounds as of yet:

• There is no way to pass IAM role to server side:
  • IAM permission with NextJS #3205
• import { defineAuth, secret } from '@aws-amplify/backend'; can't be used from Server Side code²

Describe how you'd like this feature to work

1. Secrets created through AWS Amplify Gen2 console should be possible to use in build time
2. Create proper documentation page explaining how to:
   • Access secrets in build time
   • Access secrets in SSR Runtime
   • Access secrets for backend

Footnotes

1. https://github.com/aws-amplify/amplify-hosting/issues/3348 ↩

2. https://github.com/aws-amplify/amplify-backend/issues/1052#issuecomment-1957733738 ↩ ↩²

3. https://docs.aws.amazon.com/amplify/latest/userguide/ssr-environment-variables.html ↩

[github-actions]

This has been identified as a feature request. If this feature is important to you, we strongly encourage you to give a 👍 reaction on the request. This helps us prioritize new features most important to you. Thank you!

[taraspos]

Related issues:

• revise env vars and secrets page docs#7556