Merge pull request #233055 from anthonychu/20230331-secret-kv-references

[Container Apps] Add secrets key vault references

Author: Stacyrch140

articles/container-apps/manage-secrets.md

@@ -5,14 +5,14 @@ services: container-apps
 author: craigshoemaker
 ms.service: container-apps
 ms.topic: how-to
-ms.date: 09/29/2022
+ms.date: 04/06/2023
 ms.author: cshoe
 ms.custom: event-tier1-build-2022, ignite-2022, devx-track-azurecli, devx-track-azurepowershell
 ---
 
 # Manage secrets in Azure Container Apps
 
-Azure Container Apps allows your application to securely store sensitive configuration values. Once secrets are defined at the application level, secured values are available to container apps. Specifically, you can reference secured values inside scale rules. For information on using secrets with Dapr, refer to [Dapr integration](./dapr-overview.md)
+Azure Container Apps allows your application to securely store sensitive configuration values. Once secrets are defined at the application level, secured values are available to revisions in your container apps. Additionally, you can reference secured values inside scale rules. For information on using secrets with Dapr, refer to [Dapr integration](./dapr-overview.md).
 
 - Secrets are scoped to an application, outside of any specific revision of an application.
 - Adding, removing, or changing secrets doesn't generate new revisions.
@@ -26,11 +26,29 @@ An updated or deleted secret doesn't automatically affect existing revisions in
 
 Before you delete a secret, deploy a new revision that no longer references the old secret. Then deactivate all revisions that reference the secret.
 
-> [!NOTE]
-> Container Apps doesn't support Azure Key Vault integration. Instead, enable managed identity in the container app and use the [Key Vault SDK](../key-vault/general/developers-guide.md) in your app to access secrets.
+## Defining secrets
 
+Secrets are defined as a set of name/value pairs. The value of each secret is specified directly or as a reference to a secret stored in Azure Key Vault.
 
-## Defining secrets
+### Store secret value in Container Apps
+
+When you define secrets through the portal, or via different command line options.
+
+# [Azure portal](#tab/azure-portal)
+
+1. Go to your container app in the [Azure portal](https://portal.azure.com).
+
+1. Under the *Settings* section, select **Secrets**.
+
+1. Select **Add**.
+
+1. In the *Add secret* context pane, enter the following information:
+
+    - **Name**: The name of the secret.
+    - **Type**: Select **Container Apps Secret**.
+    - **Value**: The value of the secret.
+
+1. Select **Add**.
 
 # [ARM template](#tab/arm-template)
 
@@ -67,10 +85,10 @@ 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`.
+Here, a connection string to a queue storage account is declared in the `--secrets` parameter. Replace `<CONNECTION_STRING>` with the value of your connection string.
 
 # [PowerShell](#tab/powershell)
 
@@ -97,14 +115,136 @@ Here, a connection string to a queue storage account is declared. The value for
 
 ---
 
+### <a name="reference-secret-from-key-vault"></a>Reference secret from Key Vault (preview)
+
+When you define a secret, you create a reference to a secret stored in Azure Key Vault. Container Apps automatically retrieves the secret value from Key Vault and makes it available as a secret in your container app.
+
+To reference a secret from Key Vault, you must first enable managed identity in your container app and grant the identity access to the Key Vault secrets.
+
+To enable managed identity in your container app, see [Managed identities](managed-identity.md).
+
+To grant access to Key Vault secrets, [create an access policy](../key-vault/general/assign-access-policy.md) in Key Vault for the managed identity you created. Enable the "Get" secret permission on this policy.
+
+# [Azure portal](#tab/azure-portal)
+
+1. Go to your container app in the [Azure portal](https://portal.azure.com).
+
+1. Under the *Settings* section, select **Identity**.
+
+1. In the *System assigned* tab, select **On**.
+
+1. Select **Save** to enable system-assigned managed identity.
+
+1. Under the *Settings* section, select **Secrets**.
+
+1. Select **Add**.
+
+1. In the *Add secret* context pane, enter the following information:
+
+    - **Name**: The name of the secret.
+    - **Type**: Select **Key Vault reference**.
+    - **Key Vault secret URL**: The URI of your secret in Key Vault.
+    - **Identity**: The identity to use to retrieve the secret from Key Vault.
+
+1. Select **Add**.
+
+# [ARM template](#tab/arm-template)
+
+Secrets are defined at the application level in the `resources.properties.configuration.secrets` section.
+
+```json
+"resources": [
+{
+    ...
+    "properties": {
+        "configuration": {
+            "secrets": [
+            {
+                "name": "queue-connection-string",
+                "keyVaultUrl": "<KEY-VAULT-SECRET-URI>",
+                "identity": "System"
+            }],
+        }
+    }
+}
+```
+
+Here, a connection string to a queue storage account is declared in the `secrets` array. Its value is automatically retrieved from Key Vault using the specified identity. To use a user managed identity, replace `System` with the identity's resource ID.
+
+Replace `<KEY-VAULT-SECRET-URI>` with the URI of your secret in Key Vault.
+
+# [Azure CLI](#tab/azure-cli)
+
+When you create a container app, secrets are defined using the `--secrets` parameter.
+
+- The parameter accepts a space-delimited set of name/value pairs.
+- Each pair is delimited by an equals sign (`=`).
+- To specify a Key Vault reference, use the format `<SECRET_NAME>=keyvaultref:<KEY_VAULT_SECRET_URI>,identityref:<MANAGED_IDENTITY_ID>`. For example, `queue-connection-string=keyvaultref:https://mykeyvault.vault.azure.net/secrets/queuereader,identityref:/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity`.
+
+```bash
+az containerapp create \
+  --resource-group "my-resource-group" \
+  --name queuereader \
+  --environment "my-environment-name" \
+  --image demos/queuereader:v1 \
+  --user-assigned "<USER_ASSIGNED_IDENTITY_ID>" \
+  --secrets "queue-connection-string=keyvaultref:<KEY_VAULT_SECRET_URI>,identityref:<USER_ASSIGNED_IDENTITY_ID>"
+```
+
+Here, a connection string to a queue storage account is declared in the `--secrets` parameter. Replace `<KEY_VAULT_SECRET_URI>` with the URI of your secret in Key Vault. Replace `<USER_ASSIGNED_IDENTITY_ID>` with the resource ID of the user assigned identity. For system assigned identity, use `System` instead of the resource ID.
+
+> [!NOTE]
+> The user assigned identity must have access to read the secret in Key Vault. System assigned identity can't be used with the create command because it's not available until after the container app is created.
+
+# [PowerShell](#tab/powershell)
+
+Secrets Key Vault references aren't supported in PowerShell.
+
+---
+
+#### Key Vault secret URI and secret rotation
+
+The Key Vault secret URI must be in one of the following formats:
+
+* `https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931`: Reference a specific version of a secret.
+* `https://myvault.vault.azure.net/secrets/mysecret`: Reference the latest version of a secret.
+
+If a version isn't specified in the URI, then the app uses the latest version that exists in the key vault. When newer versions become available, the app automatically retrieves the latest version within 30 minutes. Any active revisions that reference the secret in an environment variable is automatically restarted to pick up the new value.
+
+For full control of which version of a secret is used, specify the version in the URI.
+
 ## <a name="using-secrets"></a>Referencing secrets in environment variables
 
 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
+### Example
 
 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.
 
+# [Azure portal](#tab/azure-portal)
+
+After you've [defined a secret](#defining-secrets) in your container app, you can reference it in an environment variable when you create a new revision.
+
+1. Go to your container app in the [Azure portal](https://portal.azure.com).
+
+1. Open the *Revision management* page.
+
+1. Select **Create new revision**.
+
+1. In the *Create and deploy new revision* page, select a container.
+
+1. In the *Environment variables* section, select **Add**.
+
+1. Enter the following information:
+
+    - **Name**: The name of the environment variable.
+    - **Source**: Select **Reference a secret**.
+    - **Value**: Select the secret you want to reference.
+
+1. Select **Save**.
+
+1. Select **Create** to create the new revision.
+
 # [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.