From 74d9198b98ef0a8653cc126ef854fc4aa2aed52d Mon Sep 17 00:00:00 2001 From: Edward Foyle Date: Fri, 22 Mar 2024 12:56:05 -0700 Subject: [PATCH 01/11] update sandbox secret management --- .../sandbox-environments/features/index.mdx | 111 ++++++++++++------ .../sandbox-environments/setup/index.mdx | 2 +- 2 files changed, 79 insertions(+), 34 deletions(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index 8d57ec06dce..935b9e68ecd 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -18,28 +18,67 @@ Sandbox environments include additional features for managing secrets, deploying ## Secure secrets in your sandbox - Secrets set in a sandbox do not show up in the Amplify Console. You can view them in the AWS Systems Manager (SSM) Parameter Store console. + Secrets set in a sandbox do not show up in the Amplify Console. You can view + them in the AWS Systems Manager (SSM) Parameter Store console. -Amplify Gen 2 offers secure secret storage to manage sensitive data like API keys and database credentials. Secrets are similar to environment variables, but they are encrypted AWS Systems Manager Parameter Store key value pairs. Secrets are stored in AWS Parameter Store with the following naming convention: `/amplify///`. +Amplify Gen 2 offers secure secret storage to manage sensitive data like API keys and database credentials. Secrets are similar to environment variables, but they are encrypted AWS Systems Manager Parameter Store key value pairs. Secrets are stored in AWS Parameter Store under the `/amplify` prefix. ### Set secrets -You can add secrets while running your cloud sandbox with the following command: +You can add secrets to your sandbox environment using the following command: ```bash npx amplify sandbox secret set foo ? Enter secret value: ### Done! -> npx amplify sandbox secret set bar +npx amplify sandbox secret set bar ? Enter secret value: ### Done! ``` -### Access secrets +After these commands, your sandbox will have two secrets named `foo` and `bar`. -Once you have set a secret, you can access the values in code by calling the `secret()` function. The following example shows how to set up social sign-in with authentication in your app. Depending on your environment, Amplify will automatically load the correct secret value with no extra configuration. +### List secrets + +You can list all of the secret names available in your sandbox environment with the following command: + +```bash +npx amplify sandbox secret list + - foo + - bar +``` + +### Retrieve a secret + + + +**Note:** This will print a secret value in plain text to the terminal. Do not use this command anywhere that terminal logs may be stored (such as CI/CD jobs). + + + +To show the value of a secret, run the following command. + +```bash +npx amplify sandbox secret get foo +name: foo +version: 1 +value: abc123 +lastUpdated: Mon Nov 13 2023 22:19:12 GMT-0800 (Pacific Standard Time) +``` + +### Remove secrets + +To remove a secret from from the sandbox, run the following command in your terminal: + +```bash +npx amplify sandbox secret remove foo +``` + +### Reference secrets + +Once you have set a secret, you can reference the secret in your backend definition using the `secret()` function. The following example shows how to set up social sign-in with authentication in your app. Depending on your environment, Amplify will automatically load the correct secret value. ```ts import { defineAuth, secret } from '@aws-amplify/backend'; @@ -59,53 +98,57 @@ export const auth = defineAuth({ }); ``` -### Retrieve secrets - -To get the value of a secret from the cloud, run the following command in your terminal: - -```bash -npx amplify sandbox secret get foo - name: foo - version: 1 - value: 123 - lastUpdated: Mon Nov 13 2023 22:19:12 GMT-0800 (Pacific Standard Time) -``` - -### Remove secrets +The `secret()` function does NOT retrieve the value of the secret. It places a reference to the secret value in the backend definition. The secret value is only resolved during deployment of your backend. -To remove a secret from the cloud, run the following command in your terminal: +The `secret()` function can only be used in specific places in your backend definition such as [configuring auth providers](/gen2/build-a-backend/auth/add-social-provider/#configure-social-sign-in-backend) and [granting function secret access](/gen2/build-a-backend/functions/#secret-access). -```bash -npx amplify sandbox secret remove foo -``` + + To deploy a backend that uses `secret()` references via Amplify hosting, the + secret values must be [configured for the Amplify app or + branch](/gen2/deploy-and-host/fullstack-branching/secrets-and-vars) + -### Work with multiple AWS profiles +## Work with multiple AWS profiles -Sometimes you might have multiple AWS profiles set up locally. To run `amplify sandbox secret` commands, use the `--profile` flag to deploy to a specific profile. For example, let's say you have two AWS profiles set up locally—`default` and `work`. To add secrets to the `work` profile, run the following command in your terminal: +Sometimes you might have multiple AWS profiles set up locally. To run `amplify sandbox secret` commands, use the `--profile` flag to deploy to a specific profile. For example, let's say you have two AWS profiles set up locally—`default` and `work`. To add secrets to the sandbox in the `work` profile, run the following command in your terminal: ```bash npx amplify sandbox secret set foo --profile work ``` -## Multiple sandboxes per app +## Work with multiple named sandboxes - Provisioning multiple sandboxes per app is possible but not recommended because managing multiple ephemeral environments for a single app introduces complexity. With multiple sandboxes, it can be difficult to keep track of what code version or configuration is deployed where. Sticking to a single ephemeral sandbox per app keeps your workflows simple and straightforward. + Provisioning multiple sandboxes per app is possible but not recommended + because managing multiple ephemeral environments for a single developer + introduces complexity. With multiple sandboxes, it can be difficult to keep + track of what code version or configuration is deployed where. Sticking to a + single sandbox per developer keeps your workflows simpler. -You can create multiple cloud sandbox environments for each app if you want to keep persistent sandbox environments up and running to test against. First, run the following command in the terminal: +You can create multiple sandboxes if you want to have different features or test environments available in different sandboxes. By default, your sandbox is named based on the local machine username. To override this name, use the `--name` option: ```bash -npx amplify sandbox --name s1 +npx amplify sandbox --name feature1sandbox ``` -Once the deployment completes, exit sandbox `s1` and run the following command in the terminal: +This will start a sandbox named `feature1sandbox`. + +Once the deployment completes, exit sandbox and run the following command in the terminal: ```bash -npx amplify sandbox --name s2 +npx amplify sandbox --name feature2sandbox ``` -After successful deployment, sandboxes `s1` and `s2` will be ready. Pick sandbox `s1` or `s2` to activate. You can switch between them but only one can be running at a time. +After successful deployment, you will have two sandboxes `feature1sandbox` and `feature2sandbox`. You can switch between them but only one can be running at a time. + +### Secret management with named sandboxes + +When working with multiple sandboxes, secrets must be configured for each one. All of the `sandbox secret` commands accept the `--name` argument to manage secrets for named sandboxes. For example, to add a secret to `feature1sandbox`, use: + +```bash +npx amplify sandbox --name feature1sandbox secret set baz +``` ## Generate client config @@ -124,7 +167,9 @@ npx amplify generate config --app-id --branch main --format ["m ## Generate client codegen - Amplify Gen 2 introduces a fully typed experience for data that no longer requires an explicit codegen step, unlike in Amplify Gen 1. You will only need this command if you are building a mobile app or have Gen 1 requirements. + Amplify Gen 2 introduces a fully typed experience for data that no longer + requires an explicit codegen step, unlike in Amplify Gen 1. You will only need + this command if you are building a mobile app or have Gen 1 requirements. Codegen generates native code for Swift (iOS), Java (Android), and JavaScript that represents your GraphQL API's data models. It can also generate GraphQL statements (queries, mutations, and subscriptions) so that you don't have to manually code them. diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/setup/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/setup/index.mdx index 56215619f83..cf7a6851f65 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/setup/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/setup/index.mdx @@ -64,5 +64,5 @@ Keep the following best practices in mind when working with cloud sandbox enviro - Sandboxes are identical in fidelity to your production environments. - Code changes are continuously deployed to your sandbox on every save for fast iterations. - Use sandboxes for experimentation and testing, not for production workloads. -- Deploy one sandbox per Amplify app to prevent conflicts. +- Deploy one sandbox per Amplify app per developer to prevent conflicts. - Reset sandboxes occasionally to clear out unused resources and save costs. From 40a2e162aa317e38a52422b079f4c13a83758d69 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:12:37 -0700 Subject: [PATCH 02/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index 935b9e68ecd..cb8cf30e44f 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -167,9 +167,9 @@ npx amplify generate config --app-id --branch main --format ["m ## Generate client codegen - Amplify Gen 2 introduces a fully typed experience for data that no longer - requires an explicit codegen step, unlike in Amplify Gen 1. You will only need - this command if you are building a mobile app or have Gen 1 requirements. + +Amplify Gen 2 introduces a fully typed experience for data that no longer requires an explicit codegen step, unlike in Amplify Gen 1. You will only need this command if you are building a mobile app or have Gen 1 requirements. + Codegen generates native code for Swift (iOS), Java (Android), and JavaScript that represents your GraphQL API's data models. It can also generate GraphQL statements (queries, mutations, and subscriptions) so that you don't have to manually code them. From 6ea5bad631c9a6c31877d8d6ec62a6763acf3318 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:12:42 -0700 Subject: [PATCH 03/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../sandbox-environments/features/index.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index cb8cf30e44f..7fb9fd1a80f 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -119,11 +119,9 @@ npx amplify sandbox secret set foo --profile work ## Work with multiple named sandboxes - Provisioning multiple sandboxes per app is possible but not recommended - because managing multiple ephemeral environments for a single developer - introduces complexity. With multiple sandboxes, it can be difficult to keep - track of what code version or configuration is deployed where. Sticking to a - single sandbox per developer keeps your workflows simpler. + +Provisioning multiple sandboxes per app is possible but not recommended because managing multiple ephemeral environments for a single developer introduces complexity. With multiple sandboxes, it can be difficult to keep track of what code version or configuration is deployed where. Sticking to a single sandbox per developer keeps your workflows simpler. + You can create multiple sandboxes if you want to have different features or test environments available in different sandboxes. By default, your sandbox is named based on the local machine username. To override this name, use the `--name` option: From 9fa97e09bd7fef71688033d62179ba3ccc25d300 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:12:51 -0700 Subject: [PATCH 04/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index 7fb9fd1a80f..1238c20faf2 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -103,9 +103,9 @@ The `secret()` function does NOT retrieve the value of the secret. It places a r The `secret()` function can only be used in specific places in your backend definition such as [configuring auth providers](/gen2/build-a-backend/auth/add-social-provider/#configure-social-sign-in-backend) and [granting function secret access](/gen2/build-a-backend/functions/#secret-access). - To deploy a backend that uses `secret()` references via Amplify hosting, the - secret values must be [configured for the Amplify app or - branch](/gen2/deploy-and-host/fullstack-branching/secrets-and-vars) + +To deploy a backend that uses `secret()` references via Amplify hosting, the secret values must be [configured for the Amplify app or branch](/gen2/deploy-and-host/fullstack-branching/secrets-and-vars) + ## Work with multiple AWS profiles From de8ded64a91cd89633fc13c4688777dd9723ee77 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:12:58 -0700 Subject: [PATCH 05/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index 1238c20faf2..93ceda241c5 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -18,8 +18,8 @@ Sandbox environments include additional features for managing secrets, deploying ## Secure secrets in your sandbox - Secrets set in a sandbox do not show up in the Amplify Console. You can view - them in the AWS Systems Manager (SSM) Parameter Store console. + Secrets set in a sandbox do not show up in the Amplify Console. You can view them in the AWS Systems Manager (SSM) Parameter Store console. + Amplify Gen 2 offers secure secret storage to manage sensitive data like API keys and database credentials. Secrets are similar to environment variables, but they are encrypted AWS Systems Manager Parameter Store key value pairs. Secrets are stored in AWS Parameter Store under the `/amplify` prefix. From 50c329ca2358451539e271e0cece8ae6dbe1acb2 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:13:04 -0700 Subject: [PATCH 06/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../gen2/deploy-and-host/sandbox-environments/features/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index 93ceda241c5..e71c339d947 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -18,6 +18,7 @@ Sandbox environments include additional features for managing secrets, deploying ## Secure secrets in your sandbox + Secrets set in a sandbox do not show up in the Amplify Console. You can view them in the AWS Systems Manager (SSM) Parameter Store console. From b2708278a5a9ace5d78db6e00fb84fce612482e6 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:14:18 -0700 Subject: [PATCH 07/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index e71c339d947..31eea9af05b 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -146,7 +146,7 @@ After successful deployment, you will have two sandboxes `feature1sandbox` and ` When working with multiple sandboxes, secrets must be configured for each one. All of the `sandbox secret` commands accept the `--name` argument to manage secrets for named sandboxes. For example, to add a secret to `feature1sandbox`, use: ```bash -npx amplify sandbox --name feature1sandbox secret set baz +npx amplify sandbox --identifier feature1sandbox secret set baz ``` ## Generate client config From f883b1e38368433f74916bd55a2e11b654cfe578 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:14:33 -0700 Subject: [PATCH 08/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index 31eea9af05b..a0a86f0df9a 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -143,7 +143,7 @@ After successful deployment, you will have two sandboxes `feature1sandbox` and ` ### Secret management with named sandboxes -When working with multiple sandboxes, secrets must be configured for each one. All of the `sandbox secret` commands accept the `--name` argument to manage secrets for named sandboxes. For example, to add a secret to `feature1sandbox`, use: +When working with multiple sandboxes, secrets must be configured for each one. All of the `sandbox secret` commands accept the `--identifier` argument to manage secrets for named sandboxes. For example, to add a secret to `feature1sandbox`, use: ```bash npx amplify sandbox --identifier feature1sandbox secret set baz From f308fe43ecb96eac29894c3489e6008389695811 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:14:40 -0700 Subject: [PATCH 09/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index a0a86f0df9a..fc56ce5c930 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -136,7 +136,7 @@ This will start a sandbox named `feature1sandbox`. Once the deployment completes, exit sandbox and run the following command in the terminal: ```bash -npx amplify sandbox --name feature2sandbox +npx amplify sandbox --identifier feature2sandbox ``` After successful deployment, you will have two sandboxes `feature1sandbox` and `feature2sandbox`. You can switch between them but only one can be running at a time. From 76b5f25163f710525fb129eda6513ce7a92b62a3 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:14:47 -0700 Subject: [PATCH 10/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index fc56ce5c930..a784ef0ad88 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -128,7 +128,7 @@ Provisioning multiple sandboxes per app is possible but not recommended because You can create multiple sandboxes if you want to have different features or test environments available in different sandboxes. By default, your sandbox is named based on the local machine username. To override this name, use the `--name` option: ```bash -npx amplify sandbox --name feature1sandbox +npx amplify sandbox --identifier feature1sandbox ``` This will start a sandbox named `feature1sandbox`. From 0f568da9748489fdb75098885651204141e25440 Mon Sep 17 00:00:00 2001 From: josef Date: Sun, 28 Apr 2024 10:14:55 -0700 Subject: [PATCH 11/11] Update src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx --- .../deploy-and-host/sandbox-environments/features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx index a784ef0ad88..ef03fc70206 100644 --- a/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/gen2/deploy-and-host/sandbox-environments/features/index.mdx @@ -125,7 +125,7 @@ Provisioning multiple sandboxes per app is possible but not recommended because -You can create multiple sandboxes if you want to have different features or test environments available in different sandboxes. By default, your sandbox is named based on the local machine username. To override this name, use the `--name` option: +You can create multiple sandboxes if you want to have different features or test environments available in different sandboxes. By default, your sandbox is named based on the local machine username. To override this name, use the `--identifier` option: ```bash npx amplify sandbox --identifier feature1sandbox