[Secrets Mgmt] overview & how-to refresh (#2678)

* secrets refresh, initial

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* updates per Mark

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* edits from mark and diagrams

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* diagrams

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

* align yaml w quickstart

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>
Co-authored-by: Mark Fussell <markfussell@gmail.com>

daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md

@@ -6,9 +6,7 @@ weight: 1000
 description: "Overview of the pub/sub API building block"
 ---
 
-## Publish and subscribe pattern
-
-The publish and subscribe pattern (pub/sub) enables microservices to communicate with each other using messages for event-driven architectures.
+Publish and subscribe (pub/sub) enables microservices to communicate with each other using messages for event-driven architectures.
 
 - The producer, or **publisher**, writes messages to an input channel and sends them to a topic, unaware which application will receive them.
 - The consumer, or **subscriber**, subscribes to the topic and receives messages from an output channel, unaware which service produced these messages.
@@ -19,7 +17,7 @@ An intermediary message broker copies each message from a publisher's input chan
 
 <br></br>
 
-## Pub/sub API in Dapr
+## Pub/sub API
 
 The pub/sub API in Dapr:
 - Provides a platform-agnostic API to send and receive messages.
@@ -46,9 +44,9 @@ In the diagram below, the Dapr API posts an "order" topic from the publishing "c
 
 [View the complete list of pub/sub components that Dapr supports]({{< ref supported-pubsub >}}).
 
-## Dapr pub/sub API features
+## Features
 
-The pub/sub building block brings several features to your application.
+The pub/sub API building block brings several features to your application.
 
 ### Sending messages using Cloud Events
 

daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md

@@ -6,9 +6,9 @@ weight: 2000
 description: "Use the secret store building block to securely retrieve a secret"
 ---
 
-This guide demonstrates how to use Dapr's secrets API in your code to leverage the [secrets store building block]({{< ref secrets-overview >}}). With the secrets API, you easily retrieve secrets in your application code from a configured secret store.
+Now that you've learned [what the Dapr secrets building block provides]({{< ref secrets-overview >}}), learn how it can work in your service. This guide demonstrates how to call the secrets API and retrieve secrets in your application code from a configured secret store.
 
-<img src="/images/building-block-secrets-management-example.png" width=1000 alt="Diagram showing secrets management of example service">
+<img src="/images/howto-secrets/secrets-mgmt-overview.png" width=1000 alt="Diagram showing secrets management of example service.">
 
 {{% alert title="Note" color="primary" %}}
  If you haven't already, [try out the secrets management quickstart]({{< ref secrets-quickstart.md >}}) for a quick walk-through on how to use the secrets API.
@@ -17,13 +17,13 @@ This guide demonstrates how to use Dapr's secrets API in your code to leverage t
 
 ## Set up a secret store
 
-Before retrieving secrets in your application's code, you must configure a secret store component. This example configures a local secret store which uses a local JSON file to store secrets.
+Before retrieving secrets in your application's code, you must configure a secret store component. This example configures a secret store that uses a local JSON file to store secrets.
 
 {{% alert title="Warning" color="warning" %}}
 In a production-grade application, local secret stores are not recommended. [Find alternatives]({{< ref supported-secret-stores >}}) to securely manage your secrets.
 {{% /alert %}}
 
-Create a file named `secrets.json` with the following contents:
+In your project directory, create a file named `secrets.json` with the following contents:
 
 ```json
 {
@@ -31,7 +31,7 @@ Create a file named `secrets.json` with the following contents:
 }
 ```
 
-Create a directory for your components file named `components` and inside it create a file named `localSecretStore.yaml` with the following contents:
+Create a new directory named `components`. Navigate into that directory and create a component file named `local-secret-store.yaml` with the following contents:
 
 ```yaml
 apiVersion: dapr.io/v1alpha1
@@ -49,10 +49,13 @@ spec:
 ```
 
 {{% alert title="Warning" color="warning" %}}
-The path to the secret store JSON is relative to where you call `dapr run` from.
+The path to the secret store JSON is relative to where you call `dapr run`.
 {{% /alert %}}
 
-For more information, see how to [configure a different kind of secret store]({{< ref setup-secret-store >}}) and review [supported secret stores]({{< ref supported-secret-stores >}}) to see specific details required for different secret store solutions.
+For more information:
+
+- See how to [configure a different kind of secret store]({{< ref setup-secret-store >}}).
+- Review [supported secret stores]({{< ref supported-secret-stores >}}) to see specific details required for different secret store solutions.
 
 ## Get a secret
 
@@ -66,7 +69,7 @@ See a [full API reference]({{< ref secrets_api.md >}}).
 
 ## Calling the secrets API from your code
 
-Once you have a secret store, call Dapr to get the secrets from your application code. Below are code examples that leverage Dapr SDKs for retrieving a secret.
+Now that you've set up the local secret store, call Dapr to get the secrets from your application code. Below are code examples that leverage Dapr SDKs for retrieving a secret.
 
 {{< tabs Dotnet Java Python Go Javascript>}}
 
@@ -234,9 +237,7 @@ main();
 
 ## Related links
 
-- [Dapr secrets overview]({{<ref secrets-overview>}})
-- [Secrets API reference]({{<ref secrets_api>}})
-- [Configure a secret store]({{<ref setup-secret-store>}})
-- [Supported secrets]({{<ref supported-secret-stores>}})
-- [Using secrets in components]({{<ref component-secrets>}})
-- [Secret stores tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/secretstore)
+- Review the [Dapr secrets API features]({{< ref secrets-overview >}}).
+- Learn how to [use secrets scopes]({{< ref secrets-scopes >}})
+- Read the [secrets API reference]({{< ref secrets_api >}}) and review the [supported secrets]({{< ref supported-secret-stores >}}).
+- Learn how to [set up different secret store components]({{< ref setup-secret-store >}}) and how to [reference secrets in your component]({{< ref component-secrets >}}).

daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-overview.md

@@ -6,57 +6,63 @@ weight: 1000
 description: "Overview of secrets management API building block"
 ---
 
-It's common for applications to store sensitive information such as connection strings, keys and tokens that are used to authenticate with databases, services and external systems in secrets by using a dedicated secret store.
+Applications usually store sensitive information in secrets by using a dedicated secret store. For example, you authenticate databases, services, and external systems with connection strings, keys, tokens, and other application-level secrets stored in a secret store, such as [AWS Secrets Manager, Azure Key Vault, Hashicorp Vault, etc]({{< ref supported-secret-stores >}}).
 
-Usually this involves setting up a secret store such as Azure Key Vault, Hashicorp Vault and others and storing the application level secrets there. To access these secret stores, the application needs to import the secret store SDK, and use it to access the secrets. This may require a fair amount of boilerplate code that is not related to the actual business domain of the app, and so becomes an even greater challenge in multi-cloud scenarios where different vendor specific secret stores may be used.
+To access these secret stores, the application imports the secret store SDK, often requiring a fair amount of unrelated boilerplate code. This poses an even greater challenge in multi-cloud scenarios, where different vendor-specific secret stores may be used.
 
-To make it easier for developers everywhere to consume application secrets, Dapr has a dedicated secrets building block API that allows developers to get secrets from a secret store.
+## Secrets management API
 
-Using Dapr's secret store building block typically involves the following:
-1. Setting up a component for a specific secret store solution.
-1. Retrieving secrets using the Dapr secrets API in the application code.
-1. Optionally, referencing secrets in Dapr component files.
+Dapr's dedicated secrets building block API makes it easier for developers to consume application secrets from a secret store. To use Dapr's secret store building block, you:
 
-{{% alert title="Note" color="primary" %}}
-By default, Dapr enables a built-in [Kubernetes secret store in Kubernetes mode]({{<ref "kubernetes-secret-store.md">}}) deployed either via the Helm defaults or `dapr init -k`. If you are using another secret store, you can disable (not configure) the Dapr Kubernetes secret store using the `disable-builtin-k8s-secret-store` setting, when set to `true` through the Helm settings. The default is `false`.
-{{% /alert %}}
+1. Set up a component for a specific secret store solution.
+1. Retrieve secrets using the Dapr secrets API in the application code.
+1. Optionally, reference secrets in Dapr component files.
 
-## Setting up a secret store
+## Features
 
-See [Setup secret stores]({{< ref howto-secrets.md >}}) for guidance on how to setup a secret store with Dapr.
+The secrets management API building block brings several features to your application.
 
-## Using secrets in your application
+### Configure secrets without changing application code
 
-Application code can call the secrets building block API to retrieve secrets from Dapr supported secret stores that can be used in your code.
-Watch this [video](https://www.youtube.com/watch?v=OtbYCBt9C34&t=1818) for an example of how the secrets API can be used in your application.
+You can call the secrets API in your application code to retrieve and use secrets from Dapr supported secret stores. Watch [this video](https://www.youtube.com/watch?v=OtbYCBt9C34&t=1818) for an example of how the secrets management API can be used in your application.
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/OtbYCBt9C34?start=1818" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
 For example, the diagram below shows an application requesting the secret called "mysecret" from a secret store called "vault" from a configured cloud secret store.
 
 <img src="/images/secrets-overview-cloud-stores.png" width=600>
 
-Applications can use the secrets API to access secrets from a Kubernetes secret store. In the example below, the application retrieves the same secret "mysecret" from a Kubernetes secret store.
+Applications can also use the secrets API to access secrets from a Kubernetes secret store. By default, Dapr enables a built-in [Kubernetes secret store in Kubernetes mode]({{< ref "kubernetes-secret-store.md" >}}), deployed via:
+
+- The Helm defaults, or
+- `dapr init -k`
+
+If you are using another secret store, you can disable (not configure) the Dapr Kubernetes secret store by setting `disable-builtin-k8s-secret-store` to `true` through the Helm settings. The default is `false`.
+
+In the example below, the application retrieves the same secret "mysecret" from a Kubernetes secret store.
 
 <img src="/images/secrets-overview-kubernetes-store.png" width=600>
 
-In Azure Dapr can be configured to use Managed Identities to authenticate with Azure Key Vault in order to retrieve secrets. In the example below, an Azure Kubernetes Service (AKS) cluster is configured to use managed identities. Then Dapr uses [pod identities](https://docs.microsoft.com/azure/aks/operator-best-practices-identity#use-pod-identities) to retrieve secrets from Azure Key Vault on behalf of the application.
+In Azure, you can configure Dapr to retrieve secrets using managed identities to authenticate with Azure Key Vault. In the example below:
+
+1. An [Azure Kubernetes Service (AKS) cluster](https://docs.microsoft.com/azure/aks) is configured to use managed identities. 
+1. Dapr uses [pod identities](https://docs.microsoft.com/azure/aks/operator-best-practices-identity#use-pod-identities) to retrieve secrets from Azure Key Vault on behalf of the application.
 
 <img src="/images/secrets-overview-azure-aks-keyvault.png" width=600>
 
-Notice that in all of the examples above the application code did not have to change to get the same secret. Dapr did all the heavy lifting here via the secrets building block API and using the secret components.
+In the examples above, the application code did not have to change to get the same secret. Dapr uses the secret management components via the secrets management building block API.
 
-See [Access Application Secrets using the Secrets API]({{< ref howto-secrets.md >}}) for a How To guide to use secrets in your application.
+[Try out the secrets API]({{< ref "#try-out-secrets-management" >}}) using one of our quickstarts or tutorials.
 
-For detailed API information read [Secrets API]({{< ref secrets_api.md >}}).
+### Reference secret stores in Dapr components
 
-## Referencing secret stores in Dapr components
+When configuring Dapr components such as state stores, you're often required to include credentials in components files. Alternatively, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. This is the preferred approach and recommended best practice, especially in production environments.
 
-When configuring Dapr components such as state stores it is often required to include credentials in components files. Instead of doing that, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. This is preferred approach and is a recommended best practice especially in production environments.
+For more information, read [referencing secret stores in components]({{< ref component-secrets.md >}}).
 
-For more information read [referencing secret stores in components]({{< ref component-secrets.md >}})
+### Limit access to secrets
 
-## Limiting access to secrets
-
-To provide more granular control on access to secrets, Dapr provides the ability to define scopes and restricting access permissions. Learn more about [using secret scoping]({{<ref secrets-scopes>}})
+To provide more granular control on access to secrets, Dapr provides the ability to define scopes and restricting access permissions. Learn more about [using secret scoping]({{< ref secrets-scopes >}})
 
 ## Try out secrets management
 
@@ -71,4 +77,9 @@ Want to put the Dapr secrets management API to the test? Walk through the follow
 
 ### Start managing secrets directly in your app
 
-Want to skip the quickstarts? Not a problem. You can try out the secret management building block directly in your application to retrieve and manage secrets. After [Dapr is installed]({{< ref "getting-started/_index.md" >}}), you can begin using the secrets management API starting with [the secrets how-to guide]({{< ref howto-secrets.md >}}).
+Want to skip the quickstarts? Not a problem. You can try out the secret management building block directly in your application to retrieve and manage secrets. After [Dapr is installed]({{< ref "getting-started/_index.md" >}}), you can begin using the secrets management API starting with [the secrets how-to guide]({{< ref howto-secrets.md >}}).
+
+## Next steps
+
+- Learn [how to use secret scoping]({{< ref secrets-scopes.md >}}).
+- Read the [secrets API reference doc]({{< ref secrets_api.md >}}).

daprdocs/content/en/developing-applications/building-blocks/secrets/secrets-scopes.md

@@ -7,13 +7,19 @@ description: "Use scoping to limit the secrets that can be read by your applicat
 type: docs
 ---
 
-You can read [guidance on setting up secret store components]({{< ref setup-secret-store >}}) to configure a secret store for an application. Once configured, by default *any* secret defined within that store is accessible from the Dapr application.
+Once you [configure a secret store for your application]({{< ref setup-secret-store >}}), *any* secret defined within that store is accessible by default from the Dapr application. 
 
-To limit the secrets to which the Dapr application has access to, you can define secret scopes by adding a secret scope policy to the application configuration with restrictive permissions. Follow [these instructions]({{< ref configuration-concept.md >}}) to define an application configuration.
+You can limit the Dapr application's access to specific secrets by defining secret scopes. Simply add a secret scope policy [to the application configuration]({{< ref configuration-concept.md >}}) with restrictive permissions.
 
-The secret scoping policy applies to any [secret store]({{< ref supported-secret-stores.md >}}), whether that is a local secret store, a Kubernetes secret store or a public cloud secret store. For details on how to set up a [secret stores]({{< ref setup-secret-store.md >}}) read [How To: Retrieve a secret]({{< ref howto-secrets.md >}})
+The secret scoping policy applies to any [secret store]({{< ref supported-secret-stores.md >}}), including:
 
-Watch this [video](https://youtu.be/j99RN_nxExA?start=2272) for a demo on how to use secret scoping with your application.
+- A local secret store
+- A Kubernetes secret store
+- A public cloud secret store
+
+For details on how to set up a [secret store]({{< ref setup-secret-store.md >}}), read [How To: Retrieve a secret]({{< ref howto-secrets.md >}}).
+
+Watch [this video](https://youtu.be/j99RN_nxExA?start=2272) for a demo on how to use secret scoping with your application.
 
 <div class="embed-responsive embed-responsive-16by9">
 <iframe width="688" height="430" src="https://www.youtube.com/embed/j99RN_nxExA?start=2272" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
@@ -21,9 +27,7 @@ Watch this [video](https://youtu.be/j99RN_nxExA?start=2272) for a demo on how to
 
 ## Scenario 1 : Deny access to all secrets for a secret store
 
-In this example all secret access is denied to an application running on a Kubernetes cluster which has a configured [Kubernetes secret store]({{<ref kubernetes-secret-store>}}) named `mycustomsecretstore`. In the case of Kubernetes, aside from the user defined custom store, the default store named `kubernetes` is also addressed to ensure all secrets are denied access (See [here]({{<ref "kubernetes-secret-store.md#default-kubernetes-secret-store-component">}}) to learn more about the Kubernetes default secret store).
-
-To add this configuration follow the steps below:
+In this example, all secret access is denied to an application running on a Kubernetes cluster, which has a configured [Kubernetes secret store]({{< ref kubernetes-secret-store >}}) named `mycustomsecretstore`. Aside from the user-defined custom store, the example also configures the Kubernetes default store (named `kubernetes`) to ensure all secrets are denied access. [Learn more about the Kubernetes default secret store]({{< ref "kubernetes-secret-store.md#default-kubernetes-secret-store-component" >}}).
 
 Define the following `appconfig.yaml` configuration and apply it to the Kubernetes cluster using the command `kubectl apply -f appconfig.yaml`.
 
@@ -41,7 +45,7 @@ spec:
         defaultAccess: deny
 ```
 
-For applications that need to be denied access to the Kubernetes secret store, follow [these instructions]({{< ref kubernetes-overview.md >}}), and add the following annotation to the application pod.
+For applications that need to be denied access to the Kubernetes secret store, follow [these instructions]({{< ref kubernetes-overview.md >}}), and add the following annotation to the application pod:
 
 ```yaml
 dapr.io/config: appconfig
@@ -51,7 +55,7 @@ With this defined, the application no longer has access to any secrets in the Ku
 
 ## Scenario 2 : Allow access to only certain secrets in a secret store
 
-This example uses a secret store that is named `vault`. For example this could be a Hashicorp secret store component that has been set on your application. To allow a Dapr application to have access to only certain secrets `secret1` and `secret2` in the `vault` secret store, define the following `appconfig.yaml`:
+This example uses a secret store named `vault`. This could be a Hashicorp secret store component set on your application. To allow a Dapr application to have access to only `secret1` and `secret2` in the `vault` secret store, define the following `appconfig.yaml`:
 
 ```yaml
 apiVersion: dapr.io/v1alpha1
@@ -66,7 +70,7 @@ spec:
         allowedSecrets: ["secret1", "secret2"]
 ```
 
-This example defines configuration for secret store named `vault`. The default access to the secret store is `deny`, whereas some secrets are accessible by the application based on the `allowedSecrets` list. Follow [these instructions]({{< ref configuration-concept.md >}}) to apply configuration to the sidecar.
+The default access to the `vault` secret store is `deny`, while some secrets are accessible by the application, based on the `allowedSecrets` list. [Learn how to apply configuration to the sidecar]]({{< ref configuration-concept.md >}}).
 
 ## Scenario 3: Deny access to certain sensitive secrets in a secret store
 
@@ -85,7 +89,7 @@ spec:
         deniedSecrets: ["secret1", "secret2"]
 ```
 
-This example uses a secret store that is named `vault`. The above configuration explicitly denies access to `secret1` and `secret2` from the secret store named vault while allowing access to all other secrets. Follow [these instructions]({{< ref configuration-concept.md >}}) to apply configuration to the sidecar.
+This example configuration explicitly denies access to `secret1` and `secret2` from the secret store named `vault` while allowing access to all other secrets. [Learn how to apply configuration to the sidecar]]({{< ref configuration-concept.md >}}).
 
 ## Permission priority
 
@@ -101,7 +105,6 @@ Scenarios | defaultAccess | allowedSecrets | deniedSecrets | permission
 6 - Default deny/allow with both lists  | deny/allow | ["s1"] | ["s2"] | only "s1" can be accessed
 
 ## Related links
-* List of [secret stores]({{< ref supported-secret-stores.md >}})
-* Overview of [secret stores]({{< ref setup-secret-store.md >}})
 
-howto-secrets/
+- List of [secret stores]({{< ref supported-secret-stores.md >}})
+- Overview of [secret stores]({{< ref setup-secret-store.md >}})

daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md

@@ -6,8 +6,6 @@ weight: 900
 description: "Overview of the service invocation API building block"
 ---
 
-## Introduction
-
 Using service invocation, your application can reliably and securely communicate with other applications using the standard [gRPC](https://grpc.io) or [HTTP](https://www.w3.org/Protocols/) protocols.
 
 In many microservice-based applications multiple services need the ability to communicate with one another. This inter-service communication requires that application developers handle problems like:
@@ -18,6 +16,8 @@ In many microservice-based applications multiple services need the ability to co
 - **Mitigating request timeouts or failures.** How do I handle retries and transient errors?
 -  **Implementing observability and tracing.** How do I use tracing to see a call graph with metrics to diagnose issues in production?
 
+## Service invocation API
+
 Dapr addresses these challenges by providing a service invocation API that acts similar to a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing, metrics, error handling, encryption and more.
 
 Dapr uses a sidecar architecture. To invoke an application using Dapr:
@@ -25,8 +25,6 @@ Dapr uses a sidecar architecture. To invoke an application using Dapr:
 - Each application communicates with its own instance of Dapr. 
 - The Dapr instances discover and communicate with each other.
 
-### Service invocation diagram
-
 The diagram below is an overview of how Dapr's service invocation works.
 
 <img src="/images/service-invocation-overview.png" width=800 alt="Diagram showing the steps of service invocation">

daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md

@@ -15,7 +15,7 @@ Your application can use Dapr's state management API to save, read, and query ke
 
 ## Features
 
-With state management, your application can leverage features that are typically complicated and error-prone to build, including:
+With the state management API building block, your application can leverage features that are typically complicated and error-prone to build, including:
 
 - Setting the choices on concurrency control and data consistency.
 - Performing bulk update operations [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) including multiple transactional operations.

daprdocs/content/en/getting-started/quickstarts/secrets-quickstart.md

@@ -11,6 +11,9 @@ Dapr provides a dedicated secrets API that allows developers to retrieve secrets
 1. Run a microservice with a secret store component.
 1. Retrieve secrets using the Dapr secrets API in the application code.
 
+<img src="/images/secretsmanagement-quickstart/secrets-mgmt-quickstart.png" width=1000 alt="Diagram showing secrets management of example service.">
+
+
 Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.
 
 {{< tabs "Python" "JavaScript" ".NET" "Java" "Go" >}}