Merge pull request #206301 from anthonychu/patch-11

Container Apps - clarify secrets

Author: v-ccolin

articles/container-apps/manage-secrets.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: container-apps
 ms.topic: how-to
-ms.date: 11/02/2021
+ms.date: 07/28/2022
 ms.author: cshoe
 ms.custom: ignite-fall-2021, event-tier1-build-2022
 ---
@@ -19,15 +19,12 @@ Azure Container Apps allows your application to securely store sensitive configu
 - Each application revision can reference one or more secrets.
 - Multiple revisions can reference the same secret(s).
 
-When a secret is updated or deleted, you can respond to changes in one of two ways:
+An updated or deleted secret does not automatically impact existing revisions in your app. When a secret is updated or deleted, you can respond to changes in one of two ways:
 
  1. Deploy a new revision.
  2. Restart an existing revision.
 
-An updated or removed secret does not automatically restart a revision.
-
-- Before you delete a secret, deploy a new revision that no longer references the old secret.
-- If you change a secret value, you need to restart the revision to consume the new value.
+Before you delete a secret, deploy a new revision that no longer references the old secret. Then deactivate all revisions that reference the secret.
 
 ## Defining secrets
 
@@ -51,13 +48,13 @@ Secrets are defined at the application level in the `resources.properties.config
 }
 ```
 
-Here, a connection string to a queue storage account is declared in the `secrets` array. To use this configuration you would replace `<MY-CONNECTION-STRING-VALUE>` with the value of your connection string.
+Here, a connection string to a queue storage account is declared in the `secrets` array. In this example, you would replace `<MY-CONNECTION-STRING-VALUE>` with the value of your connection string.
 
 # [Azure CLI](#tab/azure-cli)
 
-Secrets are defined using the `--secrets` parameter.
+When you create a container app, secrets are defined using the `--secrets` parameter.
 
-- The parameter accepts a comma-delimited set of name/value pairs.
+- The parameter accepts a space-delimited set of name/value pairs.
 - Each pair is delimited by an equals sign (`=`).
 
 ```bash
@@ -66,16 +63,16 @@ az containerapp create \
   --name queuereader \
   --environment "my-environment-name" \
   --image demos/queuereader:v1 \
-  --secrets "queue-connection-string=$CONNECTION_STRING" \
+  --secrets "queue-connection-string=$CONNECTION_STRING"
 ```
 
 Here, a connection string to a queue storage account is declared in the `--secrets` parameter. The value for `queue-connection-string` comes from an environment variable named `$CONNECTION_STRING`.
 
 # [PowerShell](#tab/powershell)
 
-Secrets are defined using the `--secrets` parameter.
+When you create a container app, secrets are defined using the `--secrets` parameter.
 
-- The parameter accepts a comma-delimited set of name/value pairs.
+- The parameter accepts a space-delimited set of name/value pairs.
 - Each pair is delimited by an equals sign (`=`).
 
 ```azurecli
@@ -84,34 +81,34 @@ az containerapp create `
   --name queuereader `
   --environment "my-environment-name" `
   --image demos/queuereader:v1 `
-  --secrets "queue-connection-string=$CONNECTION_STRING" `
+  --secrets "queue-connection-string=$CONNECTION_STRING"
 ```
 
 Here, a connection string to a queue storage account is declared in the `--secrets` parameter. The value for `queue-connection-string` comes from an environment variable named `$CONNECTION_STRING`.
 
 ---
 
-## Using secrets
+## <a name="using-secrets"></a>Referencing secrets in environment variables
 
-The secret value is mapped to the secret name declared at the application level as described in the [defining secrets](#defining-secrets) section.    The `passwordSecretRef` and `secretref` parameters are used to reference the secret names as environment variables at the container level.  The `passwordSecretRef` provides a descriptive parameter name for secrets containing passwords.
+After declaring secrets at the application level as described in the [defining secrets](#defining-secrets) section, you can reference them in environment variables when you create a new revision in your container app. When an environment variable references a secret, its value is populated with the value defined in the secret.
 
 ## Example
 
-The following example shows an application that declares a connection string at the application level and is used throughout the configuration via `secretref`.
+The following example shows an application that declares a connection string at the application level. This connection is referenced in a container environment variable and in a scale rule.
 
 # [ARM template](#tab/arm-template)
 
 In this example, the application connection string is declared as `queue-connection-string` and becomes available elsewhere in the configuration sections.
 
 :::code language="json" source="code/secure-app-arm-template.json" highlight="11,12,13,27,28,29,30,31,44,45,61,62":::
 
-Here, the environment variable named `connection-string` gets its value from the application-level `queue-connection-string` secret. Also, the Azure Queue Storage scale rule's authorization configuration uses the `queue-connection-string` as a connection is established.
+Here, the environment variable named `connection-string` gets its value from the application-level `queue-connection-string` secret. Also, the Azure Queue Storage scale rule's authentication configuration uses the `queue-connection-string` secret as to define its connection.
 
 To avoid committing secret values to source control with your ARM template, pass secret values as ARM template parameters.
 
 # [Azure CLI](#tab/azure-cli)
 
-In this example, you create an application with a secret that's referenced in an environment variable using the Azure CLI.
+In this example, you create a container app using the Azure CLI with a secret that's referenced in an environment variable. To reference a secret in an environment variable in the Azure CLI, set its value to `secretref:`, followed by the name of the secret.
 
 ```bash
 az containerapp create \
@@ -123,11 +120,11 @@ az containerapp create \
   --env-vars "QueueName=myqueue" "ConnectionString=secretref:queue-connection-string"
 ```
 
-Here, the environment variable named `connection-string` gets its value from the application-level `queue-connection-string` secret by using `secretref`.
+Here, the environment variable named `connection-string` gets its value from the application-level `queue-connection-string` secret.
 
 # [PowerShell](#tab/powershell)
 
-In this example, you create an application with a secret that's referenced in an environment variable using the Azure CLI.
+In this example, you create a container app using the Azure CLI with a secret that's referenced in an environment variable. To reference a secret in an environment variable in the Azure CLI, set its value to `secretref:`, followed by the name of the secret.
 
 ```azurecli
 az containerapp create `
@@ -139,7 +136,7 @@ az containerapp create `
   --env-vars "QueueName=myqueue" "ConnectionString=secretref:queue-connection-string"
 ```
 
-Here, the environment variable named `connection-string` gets its value from the application-level `queue-connection-string` secret by using `secretref`.
+Here, the environment variable named `connection-string` gets its value from the application-level `queue-connection-string` secret.
 
 ---