Merge pull request #4069 from hhunter-ms/upmerge_03-05

Upmerge Mar 5: 1.13 --> 1.14

CONTRIBUTING.md

@@ -1,3 +1,3 @@
 # Contributing to Dapr docs
 
-Please see [this docs section](https://docs.dapr.io/contributing/) for general guidance on contributions to the Dapr project as well as specific guidelines on contributions to the docs repo.
+Please see [this docs section](https://docs.dapr.io/contributing/) for general guidance on contributions to the Dapr project as well as specific guidelines on contributions to the docs repo. Learn more about [Dapr bot commands and labels](https://docs.dapr.io/contributing/daprbot/) to improve your docs contributing experience.

README.md

@@ -14,8 +14,8 @@ The following branches are currently maintained:
 
 | Branch                                                       | Website                    | Description                                                                                      |
 | ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
-| [v1.12](https://github.com/dapr/docs) (primary)               | https://docs.dapr.io       | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. |
-| [v1.13](https://github.com/dapr/docs/tree/v1.13) (pre-release) | https://v1-13.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.13+ go here.                |
+| [v1.13](https://github.com/dapr/docs) (primary)               | https://docs.dapr.io       | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. |
+| [v1.14](https://github.com/dapr/docs/tree/v1.14) (pre-release) | https://v1-14.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.14+ go here.                |
 
 For more information visit the [Dapr branch structure](https://docs.dapr.io/contributing/docs-contrib/contributing-docs/#branch-guidance) document.
 

daprdocs/config.toml

@@ -196,7 +196,7 @@ url_latest_version = "https://docs.dapr.io"
   url = "https://docs.dapr.io"
 [[params.versions]]
   version = "v1.12"
-  url = "https://docs.dapr.io"
+  url = "https://v1-12.docs.dapr.io"
 [[params.versions]]
   version = "v1.11"
   url = "https://v1-11.docs.dapr.io"

daprdocs/content/en/contributing/daprbot.md

@@ -12,7 +12,7 @@ Dapr bot is triggered by a list of commands that helps with common tasks in the
 
 | Command          | Target                | Description                                                                                              | Who can use                                                                                     | Repository                             |
 | ---------------- | --------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |
-| `/assign`        | Issue                 | Assigns an issue to a user or group of users                                                             | Anyone                                                                                          | `dapr`, `components-contrib`, `go-sdk` |
+| `/assign`        | Issue                 | Assigns an issue to a user or group of users                                                             | Anyone                                                                                          | `dapr`, `docs`, `quickstarts`, `cli`, `components-contrib`, `go-sdk`, `js-sdk`, `java-sdk`, `python-sdk`, `dotnet-sdk` |
 | `/ok-to-test`    | Pull request          | `dapr`: trigger end to end tests <br/> `components-contrib`: trigger conformance and certification tests | Users listed in the [bot](https://github.com/dapr/dapr/blob/master/.github/scripts/dapr_bot.js) | `dapr`, `components-contrib`           |
 | `/ok-to-perf`    | Pull request          | Trigger performance tests.                                                                               | Users listed in the [bot](https://github.com/dapr/dapr/blob/master/.github/scripts/dapr_bot.js) | `dapr`                                 |
 | `/make-me-laugh` | Issue or pull request | Posts a random joke                                                                                      | Users listed in the [bot](https://github.com/dapr/dapr/blob/master/.github/scripts/dapr_bot.js) | `dapr`, `components-contrib`           |

daprdocs/content/en/developing-applications/building-blocks/actors/actors-features-concepts.md

@@ -14,7 +14,9 @@ Now that you've learned about the [actor building block]({{< ref "actors-overvie
 
 Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actor runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr actor runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor's existence should it need to be reactivated later.
 
-Invocation of actor methods and reminders reset the idle time, e.g. reminder firing will keep the actor active. Actor reminders fire whether an actor is active or inactive, if fired for inactive actor, it will activate the actor first. Actor timers do not reset the idle time, so timer firing will not keep the actor active. Timers only fire while the actor is active.
+Invocation of actor methods, timers, and reminders reset the actor idle time. For example, a reminder firing keeps the actor active. 
+- Actor reminders fire whether an actor is active or inactive. If fired for an inactive actor, it activates the actor first.
+- Actor timers firing reset the idle time; however, timers only fire while the actor is active.
 
 The idle timeout and scan interval Dapr runtime uses to see if an actor can be garbage-collected is configurable. This information can be passed when Dapr runtime calls into the actor service to get supported actor types.
 

daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md

@@ -146,11 +146,41 @@ If an invocation of the method fails, the timer is not removed. Timers are only
 - The executions run out
 - You delete it explicitly
 
+## Reminder data serialization format
+
+Actor reminder data is serialized to JSON by default. Dapr v1.13 onwards supports a protobuf serialization format for reminders data which, depending on throughput and size of the payload, can result in significant performance improvements, giving developers a higher throughput and lower latency. Another benefit is storing smaller data in the actor underlying database, which can result in cost optimizations when using some cloud databases. A restriction with using protobuf serialization is that the reminder data can no longer be queried. 
+
+{{% alert title="Note" color="primary" %}}
+Protobuf serialization will become the default format in Dapr 1.14
+{{% /alert %}}
+
+Reminder data saved in protobuf format cannot be read in Dapr 1.12.x and earlier versions. Its recommended to test this feature in Dapr v1.13 and verify that it works as expected with your database before taking this into production. 
+
+{{% alert title="Note" color="primary" %}}
+If you use protobuf serialization in Dapr v1.13 and need to downgrade to an earlier Dapr version, the reminder data will be incompatible with versions 1.12.x and earlier versions. **Once you save your reminders data in protobuf format, you cannot move it back to JSON format**.
+{{% /alert %}}
+
+### Enabling protobuf serialization on Kubernetes
+
+To use protobuf serialization for actor reminders on Kubernetes, use the following Helm value:
+
+```
+--set dapr_placement.maxActorApiLevel=20
+```
+
+### Enabling protobuf serialization on self-hosted
+
+To use protobuf serialization for actor reminders on self-hosted, use the following `daprd` flag:
+
+```
+--max-api-level=20
+```
+
 ## Next steps
 
 {{< button text="Configure actor runtime behavior >>" page="actors-runtime-config.md" >}}
 
 ## Related links
 
 - [Actors API reference]({{< ref actors_api.md >}})
-- [Actors overview]({{< ref actors-overview.md >}})
+- [Actors overview]({{< ref actors-overview.md >}})

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

@@ -6,16 +6,16 @@ weight: 2000
 description: "Learn how to encrypt and decrypt files"
 ---
 
-Now that you've read about [Cryptography as a Dapr building block]({{< ref cryptography-overview.md >}}), let's walk through using the cryptography APIs with the SDKs.  
+Now that you've read about [Cryptography as a Dapr building block]({{< ref cryptography-overview.md >}}), let's walk through using the cryptography APIs with the SDKs.
 
 {{% alert title="Note" color="primary" %}}
-  Dapr cryptography is currently in alpha.
+Dapr cryptography is currently in alpha.
 
 {{% /alert %}}
 
 ## Encrypt
 
-{{< tabs "JavaScript" "Go" >}}
+{{< tabs "JavaScript" "Go" ".NET" >}}
 
 {{% codetab %}}
 
@@ -136,12 +136,32 @@ if err != nil {
 
 {{% /codetab %}}
 
+{{% codetab %}}
+
+<!-- .NET -->
+Using the Dapr SDK in your project, with the gRPC APIs, you can encrypt data in a string or a byte array:
+
+```csharp
+using var client = new DaprClientBuilder().Build();
+
+const string componentName = "azurekeyvault"; //Change this to match your cryptography component
+const string keyName = "myKey"; //Change this to match the name of the key in your cryptographic store
+
+const string plainText = "This is the value we're going to encrypt today";
+
+//Encode the string to a UTF-8 byte array and encrypt it
+var plainTextBytes = Encoding.UTF8.GetBytes(plainText);
+var encryptedBytesResult = await client.EncryptAsync(componentName, plaintextBytes, keyName, new EncryptionOptions(KeyWrapAlgorithm.Rsa));
+```
+
+{{% /codetab %}}
+
 {{< /tabs >}}
 
 
 ## Decrypt
 
-{{< tabs "JavaScript" "Go" >}}
+{{< tabs "JavaScript" "Go" ".NET" >}}
 
 {{% codetab %}}
 
@@ -186,6 +206,29 @@ out, err := sdkClient.Decrypt(context.Background(), rf, dapr.EncryptOptions{
 
 {{% /codetab %}}
 
+{{% codetab %}}
+
+<!-- .NET -->
+To decrypt a string, use the 'DecryptAsync' gRPC API in your project.
+
+In the following example, we'll take a byte array (such as from the example above) and decrypt it to a UTF-8 encoded string.
+
+```csharp
+public async Task<string> DecryptBytesAsync(byte[] encryptedBytes)
+{
+  using var client = new DaprClientBuilder().Build();
+
+  const string componentName = "azurekeyvault"; //Change this to match your cryptography component
+  const string keyName = "myKey"; //Change this to match the name of the key in your cryptographic store
+
+  var decryptedBytes = await client.DecryptAsync(componentName, encryptedBytes, keyName);
+  var decryptedString = Encoding.UTF8.GetString(decryptedBytes.ToArray());
+  return decryptedString;
+}
+```
+
+{{% /codetab %}}
+
 {{< /tabs >}}
 
 ## Next steps

daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md

@@ -146,6 +146,8 @@ Different state store implementations may implicitly put restrictions on the typ
 
 Similarly, if a state store imposes restrictions on the size of a batch transaction, that may limit the number of parallel actions that can be scheduled by a workflow.
 
+Workflow state can be purged from a state store, including all its history. Each Dapr SDK exposes APIs for purging all metadata related to specific workflow instances.
+
 ## Workflow scalability
 
 Because Dapr Workflows are internally implemented using actors, Dapr Workflows have the same scalability characteristics as actors. The placement service:

daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md

@@ -63,6 +63,8 @@ You can use the following two techniques to write workflows that may need to sch
 
 1. **Use the _continue-as-new_ API**:  
     Each workflow SDK exposes a _continue-as-new_ API that workflows can invoke to restart themselves with a new input and history. The _continue-as-new_ API is especially ideal for implementing "eternal workflows", like monitoring agents, which would otherwise be implemented using a `while (true)`-like construct. Using _continue-as-new_ is a great way to keep the workflow history size small.
+
+    > The _continue-as-new_ API truncates the existing history, replacing it with a new history.
 
 1. **Use child workflows**:  
     Each workflow SDK exposes an API for creating child workflows. A child workflow behaves like any other workflow, except that it's scheduled by a parent workflow. Child workflows have:
@@ -159,6 +161,12 @@ The backend implementation is largely decoupled from the workflow core engine or
 
 In that sense, it's similar to Dapr's state store abstraction, except designed specifically for workflow. All APIs and programming model features are the same, regardless of which backend is used.
 
+## Purging
+
+Workflow state can be purged from a state store, purging all its history and removing all metadata related to a specific workflow instance. The purge capability is used for workflows that have run to a `COMPLETED`, `FAILED`, or `TERMINATED` state. 
+
+Learn more in [the workflow API reference guide]({{< ref workflow_api.md >}}).
+
 ## Limitations
 
 ### Workflow determinism and code restraints 
@@ -211,7 +219,7 @@ const randomString = getRandomString();
 
 ```go
 // DON'T DO THIS!
-
+const currentTime = time.Now()
 ```
 
 {{% /codetab %}}
@@ -254,13 +262,12 @@ const randomString = yield context.callActivity(getRandomString);
 
 {{% /codetab %}}
 
-
 {{% codetab %}}
 
 ```go
-// Do this!!
-
+const currentTime = ctx.CurrentUTCDateTime()
 ```
+
 {{% /codetab %}}
 
 {{< /tabs >}}
@@ -319,10 +326,12 @@ fetch('https://postman-echo.com/get')
 
 ```go
 // DON'T DO THIS!
+resp, err := http.Get("http://example.com/api/data")
 ```
 
 {{% /codetab %}}
 
+
 {{< /tabs >}}
 
 Do this:
@@ -364,6 +373,8 @@ const data = yield ctx.callActivity(makeHttpCall, "https://example.com/api/data"
 
 ```go
 // Do this!!
+err := ctx.CallActivity(MakeHttpCallActivity, workflow.ActivityInput("https://example.com/api/data")).Await(&output)
+
 ```
 
 {{% /codetab %}}
@@ -412,9 +423,16 @@ Don't declare JavaScript workflow as `async`. The Node.js runtime doesn't guaran
 
 ```go
 // DON'T DO THIS!
+go func() {
+  err := ctx.CallActivity(DoSomething).Await(nil)
+}()
+err := ctx.CreateTimer(time.Second).Await(nil)
 ```
+
 {{% /codetab %}}
 
+
+
 {{< /tabs >}}
 
 Do this:
@@ -450,7 +468,9 @@ Since the Node.js runtime doesn't guarantee that asynchronous functions are dete
 {{% codetab %}}
 
 ```go
-// Do this!!
+// Do this!
+task := ctx.CallActivity(DoSomething)
+task.Await(nil)
 ```
 
 {{% /codetab %}}
@@ -489,4 +509,4 @@ To work around these constraints:
    - [JavaScript](https://github.com/dapr/js-sdk/tree/main/examples/workflow)
    - [.NET](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
    - [Java](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)
-   - [Go](https://github.com/dapr/go-sdk/tree/main/examples/workflow/README.md)
+   - [Go](https://github.com/dapr/go-sdk/tree/main/examples/workflow/README.md)

daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-patterns.md

@@ -823,9 +823,8 @@ public class MonitorWorkflow extends Workflow {
       }
 
       // Put the workflow to sleep until the determined time
-      // Note: ctx.createTimer() method is not supported in the Java SDK yet
       try {
-        TimeUnit.SECONDS.sleep(nextSleepInterval.getSeconds());
+        ctx.createTimer(nextSleepInterval);
       } catch (InterruptedException e) {
         throw new RuntimeException(e);
       }

daprdocs/content/en/getting-started/get-started-api.md

@@ -3,10 +3,11 @@ type: docs
 title: "Use the Dapr API"
 linkTitle: "Use the Dapr API"
 weight: 30
-description: "Run a Dapr sidecar and try out the state API"
+description: "Run a Dapr sidecar and try out the state management API"
 ---
 
-In this guide, you'll simulate an application by running the sidecar and calling the API directly. After running Dapr using the Dapr CLI, you'll:
+In this guide, you'll simulate an application by running the sidecar and calling the state management API directly. 
+After running Dapr using the Dapr CLI, you'll:
 
 - Save a state object.
 - Read/get the state object.
@@ -21,7 +22,8 @@ In this guide, you'll simulate an application by running the sidecar and calling
 
 ### Step 1: Run the Dapr sidecar
 
-The [`dapr run`]({{< ref dapr-run.md >}}) command launches an application, together with a sidecar.
+The [`dapr run`]({{< ref dapr-run.md >}}) command normally runs your application and a Dapr sidecar. In this case, 
+it only runs the sidecar since you are interacting with the state management API directly.
 
 Launch a Dapr sidecar that will listen on port 3500 for a blank application named `myapp`:
 

daprdocs/content/en/getting-started/install-dapr-cli.md

@@ -15,6 +15,11 @@ You'll use the Dapr CLI as the main tool for various Dapr-related tasks. You can
 
 The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments.
 
+{{% alert title="Before you begin" color="primary" %}}
+In Docker Desktop's advanced options, verify you've allowed the default Docker socket to be used.
+   <img src="/images/docker-desktop-setting.png" width=800 style="padding-bottom:15px;">
+{{% /alert %}}
+
 ### Step 1: Install the Dapr CLI
 
 {{< tabs Linux Windows MacOS Binaries>}}

daprdocs/content/en/getting-started/install-dapr-selfhost.md

@@ -22,8 +22,12 @@ Dapr initialization includes:
 1. Creating a **default components folder** with component definitions for the above.
 1. Running a **Dapr placement service container instance** for local actor support.
 
+{{% alert title="Kubernetes Development Environment" color="primary" %}}
+To initialize Dapr in your local or remote **Kubernetes** cluster for development (including the Redis and Zipkin containers listed above), see [how to initialize Dapr for development on Kubernetes]({{<ref "kubernetes-deploy.md#install-dapr-from-the-official-dapr-helm-chart-with-development-flag">}})
+{{% /alert %}}
+
 {{% alert title="Docker" color="primary" %}}
-The recommended development environment requires [Docker](https://docs.docker.com/install/). While you can [initialize Dapr without a dependency on Docker]({{< ref self-hosted-no-docker.md >}})), the next steps in this guide assume the recommended Docker development environment.
+The recommended development environment requires [Docker](https://docs.docker.com/install/). While you can [initialize Dapr without a dependency on Docker]({{< ref self-hosted-no-docker.md >}}), the next steps in this guide assume the recommended Docker development environment.
 
 You can also install [Podman](https://podman.io/) in place of Docker. Read more about [initializing Dapr using Podman]({{< ref dapr-init.md >}}).
 {{% /alert %}}
@@ -66,7 +70,7 @@ dapr init
 
 **If you are installing on Mac OS Silicon with Docker,** you may need to perform the following workaround to enable `dapr init` to talk to Docker without using Kubernetes.
 1. Navigate to **Docker Desktop** > **Settings** > **Advanced**.
-1. Select the **Enable default Docker socket** checkbox.
+1. Select the **Allow the default Docker socket to be used (requires password)** checkbox.
 
 {{% /codetab %}}
 
@@ -82,6 +86,7 @@ dapr init
 
 {{< /tabs >}}
 
+[See the troubleshooting guide if you encounter any error messages regarding Docker not being installed or running.]({{< ref "common_issues.md#dapr-cant-connect-to-docker-when-installing-the-dapr-cli" >}})
 
 ### Step 3: Verify Dapr version
 
@@ -135,9 +140,14 @@ ls $HOME/.dapr
 {{% /codetab %}}
 
 {{% codetab %}}
-
+You can verify using either PowerShell or command line. If using PowerShell, run:
 ```powershell
-explorer "%USERPROFILE%\.dapr\"
+explorer "$env:USERPROFILE\.dapr"
+```
+
+If using command line, run: 
+```cmd
+explorer "%USERPROFILE%\.dapr"
 ```
 
 **Result:**