+
diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md
index afc6bd5f1e4..89c31dc5e1b 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md
@@ -116,6 +116,10 @@ Dapr enables states to be:
For more details read [How-To: Share state between applications]({{< ref howto-share-state.md >}}),
+### Enabling the outbox pattern
+
+Dapr enables developers to use the outbox pattern for achieving a single transaction across a transactional state store and any message broker. For more information, read [How to enable transactional outbox messaging]({{< ref howto-outbox.md >}})
+
### Querying state
There are two ways to query the state:
diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md
index 6caa7f3ffc7..98f0df760e9 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md
@@ -6,6 +6,10 @@ weight: 5000
description: "Learn how to develop and author workflows"
---
+{{% alert title="Note" color="primary" %}}
+Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-version cli="true" %}}]({{< ref "workflow-overview.md#limitations" >}}).
+{{% /alert %}}
+
This article provides a high-level overview of how to author workflows that are executed by the Dapr Workflow engine.
{{% alert title="Note" color="primary" %}}
@@ -30,7 +34,25 @@ The Dapr sidecar doesn’t load any workflow definitions. Rather, the sidecar si
[Workflow activities]({{< ref "workflow-features-concepts.md#workflow-activites" >}}) are the basic unit of work in a workflow and are the tasks that get orchestrated in the business process.
-{{< tabs ".NET" Python >}}
+{{< tabs Python ".NET" Java >}}
+
+{{% codetab %}}
+
+
+
+Define the workflow activities you'd like your workflow to perform. Activities are a function definition and can take inputs and outputs. The following example creates a counter (activity) called `hello_act` that notifies users of the current counter value. `hello_act` is a function derived from a class called `WorkflowActivityContext`.
+
+```python
+def hello_act(ctx: WorkflowActivityContext, input):
+ global counter
+ counter += input
+ print(f'New counter value is: {counter}!', flush=True)
+```
+
+[See the `hello_act` workflow activity in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL40C1-L43C59)
+
+
+{{% /codetab %}}
{{% codetab %}}
@@ -102,29 +124,76 @@ public class ProcessPaymentActivity : WorkflowActivity
{{% codetab %}}
-
+
-Define the workflow activities you'd like your workflow to perform. Activities are a function definition and can take inputs and outputs. The following example creates a counter (activity) called `hello_act` that notifies users of the current counter value. `hello_act` is a function derived from a class called `WorkflowActivityContext`.
+Define the workflow activities you'd like your workflow to perform. Activities are wrapped in the public `DemoWorkflowActivity` class, which implements the workflow activities.
-```python
-def hello_act(ctx: WorkflowActivityContext, input):
- global counter
- counter += input
- print(f'New counter value is: {counter}!', flush=True)
-```
+```java
+@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)
+public class DemoWorkflowActivity implements WorkflowActivity {
-[See the `hello_act` workflow activity in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL40C1-L43C59)
+ @Override
+ public DemoActivityOutput run(WorkflowActivityContext ctx) {
+ Logger logger = LoggerFactory.getLogger(DemoWorkflowActivity.class);
+ logger.info("Starting Activity: " + ctx.getName());
+ var message = ctx.getInput(DemoActivityInput.class).getMessage();
+ var newMessage = message + " World!, from Activity";
+ logger.info("Message Received from input: " + message);
+ logger.info("Sending message to output: " + newMessage);
+
+ logger.info("Sleeping for 5 seconds to simulate long running operation...");
+
+ try {
+ TimeUnit.SECONDS.sleep(5);
+ } catch (InterruptedException e) {
+ throw new RuntimeException(e);
+ }
+
+
+ logger.info("Activity finished");
+
+ var output = new DemoActivityOutput(message, newMessage);
+ logger.info("Activity returned: " + output);
+
+ return output;
+ }
+}
+```
+
+[See the Java SDK workflow activity example in context.](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflowActivity.java)
{{% /codetab %}}
+
{{< /tabs >}}
## Write the workflow
Next, register and call the activites in a workflow.
-{{< tabs ".NET" Python >}}
+{{< tabs Python ".NET" Java >}}
+
+{{% codetab %}}
+
+
+
+The `hello_world_wf` function is derived from a class called `DaprWorkflowContext` with input and output parameter types. It also includes a `yield` statement that does the heavy lifting of the workflow and calls the workflow activities.
+
+```python
+def hello_world_wf(ctx: DaprWorkflowContext, input):
+ print(f'{input}')
+ yield ctx.call_activity(hello_act, input=1)
+ yield ctx.call_activity(hello_act, input=10)
+ yield ctx.wait_for_external_event("event1")
+ yield ctx.call_activity(hello_act, input=100)
+ yield ctx.call_activity(hello_act, input=1000)
+```
+
+[See the `hello_world_wf` workflow in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL32C1-L38C51)
+
+
+{{% /codetab %}}
{{% codetab %}}
@@ -171,103 +240,42 @@ The `OrderProcessingWorkflow` class is derived from a base class called `Workflo
{{% codetab %}}
-
+
-The `hello_world_wf` function is derived from a class called `DaprWorkflowContext` with input and output parameter types. It also includes a `yield` statement that does the heavy lifting of the workflow and calls the workflow activities.
-
-```python
-def hello_world_wf(ctx: DaprWorkflowContext, input):
- print(f'{input}')
- yield ctx.call_activity(hello_act, input=1)
- yield ctx.call_activity(hello_act, input=10)
- yield ctx.wait_for_external_event("event1")
- yield ctx.call_activity(hello_act, input=100)
- yield ctx.call_activity(hello_act, input=1000)
-```
-
-[See the `hello_world_wf` workflow in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL32C1-L38C51)
-
-
-{{% /codetab %}}
-
-{{< /tabs >}}
-
-## Write the application
-
-Finally, compose the application using the workflow.
-
-{{< tabs ".NET" Python >}}
-
-{{% codetab %}}
+Next, register the workflow with the `WorkflowRuntimeBuilder` and start the workflow runtime.
-
+```java
+public class DemoWorkflowWorker {
-[In the following `Program.cs` example](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Program.cs), for a basic ASP.NET order processing application using the .NET SDK, your project code would include:
+ public static void main(String[] args) throws Exception {
-- A NuGet package called `Dapr.Workflow` to receive the .NET SDK capabilities
-- A builder with an extension method called `AddDaprWorkflow`
- - This will allow you to register workflows and workflow activities (tasks that workflows can schedule)
-- HTTP API calls
- - One for submitting a new order
- - One for checking the status of an existing order
+ // Register the Workflow with the builder.
+ WorkflowRuntimeBuilder builder = new WorkflowRuntimeBuilder().registerWorkflow(DemoWorkflow.class);
+ builder.registerActivity(DemoWorkflowActivity.class);
-```csharp
-using Dapr.Workflow;
-//...
+ // Build and then start the workflow runtime pulling and executing tasks
+ try (WorkflowRuntime runtime = builder.build()) {
+ System.out.println("Start workflow runtime");
+ runtime.start();
+ }
-// Dapr Workflows are registered as part of the service configuration
-builder.Services.AddDaprWorkflow(options =>
-{
- // Note that it's also possible to register a lambda function as the workflow
- // or activity implementation instead of a class.
- options.RegisterWorkflow();
+ System.exit(0);
+ }
+}
+```
- // These are the activities that get invoked by the workflow(s).
- options.RegisterActivity();
- options.RegisterActivity();
- options.RegisterActivity();
-});
+[See the Java SDK workflow in context.](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflowWorker.java)
-WebApplication app = builder.Build();
-// POST starts new order workflow instance
-app.MapPost("/orders", async (WorkflowEngineClient client, [FromBody] OrderPayload orderInfo) =>
-{
- if (orderInfo?.Name == null)
- {
- return Results.BadRequest(new
- {
- message = "Order data was missing from the request",
- example = new OrderPayload("Paperclips", 99.95),
- });
- }
-
-//...
-});
-
-// GET fetches state for order workflow to report status
-app.MapGet("/orders/{orderId}", async (string orderId, WorkflowEngineClient client) =>
-{
- WorkflowState state = await client.GetWorkflowStateAsync(orderId, true);
- if (!state.Exists)
- {
- return Results.NotFound($"No order with ID = '{orderId}' was found.");
- }
+{{% /codetab %}}
- var httpResponsePayload = new
- {
- details = state.ReadInputAs(),
- status = state.RuntimeStatus.ToString(),
- result = state.ReadOutputAs(),
- };
+{{< /tabs >}}
-//...
-}).WithName("GetOrderInfoEndpoint");
+## Write the application
-app.Run();
-```
+Finally, compose the application using the workflow.
-{{% /codetab %}}
+{{< tabs Python ".NET" Java >}}
{{% codetab %}}
@@ -356,6 +364,124 @@ if __name__ == '__main__':
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+
+[In the following `Program.cs` example](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Program.cs), for a basic ASP.NET order processing application using the .NET SDK, your project code would include:
+
+- A NuGet package called `Dapr.Workflow` to receive the .NET SDK capabilities
+- A builder with an extension method called `AddDaprWorkflow`
+ - This will allow you to register workflows and workflow activities (tasks that workflows can schedule)
+- HTTP API calls
+ - One for submitting a new order
+ - One for checking the status of an existing order
+
+```csharp
+using Dapr.Workflow;
+//...
+
+// Dapr Workflows are registered as part of the service configuration
+builder.Services.AddDaprWorkflow(options =>
+{
+ // Note that it's also possible to register a lambda function as the workflow
+ // or activity implementation instead of a class.
+ options.RegisterWorkflow();
+
+ // These are the activities that get invoked by the workflow(s).
+ options.RegisterActivity();
+ options.RegisterActivity();
+ options.RegisterActivity();
+});
+
+WebApplication app = builder.Build();
+
+// POST starts new order workflow instance
+app.MapPost("/orders", async (DaprWorkflowClient client, [FromBody] OrderPayload orderInfo) =>
+{
+ if (orderInfo?.Name == null)
+ {
+ return Results.BadRequest(new
+ {
+ message = "Order data was missing from the request",
+ example = new OrderPayload("Paperclips", 99.95),
+ });
+ }
+
+//...
+});
+
+// GET fetches state for order workflow to report status
+app.MapGet("/orders/{orderId}", async (string orderId, DaprWorkflowClient client) =>
+{
+ WorkflowState state = await client.GetWorkflowStateAsync(orderId, true);
+ if (!state.Exists)
+ {
+ return Results.NotFound($"No order with ID = '{orderId}' was found.");
+ }
+
+ var httpResponsePayload = new
+ {
+ details = state.ReadInputAs(),
+ status = state.RuntimeStatus.ToString(),
+ result = state.ReadOutputAs(),
+ };
+
+//...
+}).WithName("GetOrderInfoEndpoint");
+
+app.Run();
+```
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+
+[As in the following example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflow.java), a hello-world application using the Java SDK and Dapr Workflow would include:
+
+- A Java package called `io.dapr.workflows.client` to receive the Java SDK client capabilities.
+- An import of `io.dapr.workflows.Workflow`
+- The `DemoWorkflow` class which extends `Workflow`
+- Creating the workflow with input and output.
+- API calls. In the example below, these calls start and call the workflow activities.
+
+```java
+package io.dapr.examples.workflows;
+
+import com.microsoft.durabletask.CompositeTaskFailedException;
+import com.microsoft.durabletask.Task;
+import com.microsoft.durabletask.TaskCanceledException;
+import io.dapr.workflows.Workflow;
+import io.dapr.workflows.WorkflowStub;
+
+import java.time.Duration;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Implementation of the DemoWorkflow for the server side.
+ */
+public class DemoWorkflow extends Workflow {
+ @Override
+ public WorkflowStub create() {
+ return ctx -> {
+ ctx.getLogger().info("Starting Workflow: " + ctx.getName());
+ // ...
+ ctx.getLogger().info("Calling Activity...");
+ var input = new DemoActivityInput("Hello Activity!");
+ var output = ctx.callActivity(DemoWorkflowActivity.class.getName(), input, DemoActivityOutput.class).await();
+ // ...
+ };
+ }
+}
+```
+
+[See the full Java SDK workflow example in context.](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflow.java)
+
{{% /codetab %}}
@@ -377,5 +503,6 @@ Now that you've authored a workflow, learn how to manage it.
- [Workflow overview]({{< ref workflow-overview.md >}})
- [Workflow API reference]({{< ref workflow_api.md >}})
- Try out the full SDK examples:
- - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
- [Python example](https://github.com/dapr/python-sdk/tree/master/examples/demo_workflow)
+ - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
+ - [Java example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)
diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
index 99cb87c9b58..fb7ad9d57c5 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
@@ -6,45 +6,13 @@ weight: 6000
description: Manage and run workflows
---
-Now that you've [authored the workflow and its activities in your application]({{< ref howto-author-workflow.md >}}), you can start, terminate, and get information about the workflow using HTTP API calls. For more information, read the [workflow API reference]({{< ref workflow_api.md >}}).
-
-{{< tabs ".NET" Python HTTP >}}
-
-
-{{% codetab %}}
-
-Manage your workflow within your code. In the `OrderProcessingWorkflow` example from the [Author a workflow]({{< ref "howto-author-workflow.md#write-the-application" >}}) guide, the workflow is registered in the code. You can now start, terminate, and get information about a running workflow:
-
-```csharp
-string orderId = "exampleOrderId";
-string workflowComponent = "dapr";
-string workflowName = "OrderProcessingWorkflow";
-OrderPayload input = new OrderPayload("Paperclips", 99.95);
-Dictionary workflowOptions; // This is an optional parameter
-
-// Start the workflow. This returns back a "StartWorkflowResponse" which contains the instance ID for the particular workflow instance.
-StartWorkflowResponse startResponse = await daprClient.StartWorkflowAsync(orderId, workflowComponent, workflowName, input, workflowOptions);
-
-// Get information on the workflow. This response contains information such as the status of the workflow, when it started, and more!
-GetWorkflowResponse getResponse = await daprClient.GetWorkflowAsync(orderId, workflowComponent, workflowName);
-
-// Terminate the workflow
-await daprClient.TerminateWorkflowAsync(orderId, workflowComponent);
-
-// Raise an event (an incoming purchase order) that your workflow will wait for. This returns the item waiting to be purchased.
-await daprClient.RaiseWorkflowEventAsync(orderId, workflowComponent, workflowName, input);
-
-// Pause
-await daprClient.PauseWorkflowAsync(orderId, workflowComponent);
-
-// Resume
-await daprClient.ResumeWorkflowAsync(orderId, workflowComponent);
+{{% alert title="Note" color="primary" %}}
+Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-version cli="true" %}}]({{< ref "workflow-overview.md#limitations" >}}).
+{{% /alert %}}
-// Purge
-await daprClient.PurgeWorkflowAsync(orderId, workflowComponent);
-```
+Now that you've [authored the workflow and its activities in your application]({{< ref howto-author-workflow.md >}}), you can start, terminate, and get information about the workflow using HTTP API calls. For more information, read the [workflow API reference]({{< ref workflow_api.md >}}).
-{{% /codetab %}}
+{{< tabs Python ".NET" Java HTTP >}}
{{% codetab %}}
@@ -95,6 +63,107 @@ d.terminate_workflow(instance_id=instanceId, workflow_component=workflowComponen
{{% /codetab %}}
+
+{{% codetab %}}
+
+Manage your workflow within your code. In the `OrderProcessingWorkflow` example from the [Author a workflow]({{< ref "howto-author-workflow.md#write-the-application" >}}) guide, the workflow is registered in the code. You can now start, terminate, and get information about a running workflow:
+
+```csharp
+string orderId = "exampleOrderId";
+string workflowComponent = "dapr";
+string workflowName = "OrderProcessingWorkflow";
+OrderPayload input = new OrderPayload("Paperclips", 99.95);
+Dictionary workflowOptions; // This is an optional parameter
+
+// Start the workflow. This returns back a "StartWorkflowResponse" which contains the instance ID for the particular workflow instance.
+StartWorkflowResponse startResponse = await daprClient.StartWorkflowAsync(orderId, workflowComponent, workflowName, input, workflowOptions);
+
+// Get information on the workflow. This response contains information such as the status of the workflow, when it started, and more!
+GetWorkflowResponse getResponse = await daprClient.GetWorkflowAsync(orderId, workflowComponent, eventName);
+
+// Terminate the workflow
+await daprClient.TerminateWorkflowAsync(orderId, workflowComponent);
+
+// Raise an event (an incoming purchase order) that your workflow will wait for. This returns the item waiting to be purchased.
+await daprClient.RaiseWorkflowEventAsync(orderId, workflowComponent, workflowName, input);
+
+// Pause
+await daprClient.PauseWorkflowAsync(orderId, workflowComponent);
+
+// Resume
+await daprClient.ResumeWorkflowAsync(orderId, workflowComponent);
+
+// Purge the workflow, removing all inbox and history information from associated instance
+await daprClient.PurgeWorkflowAsync(orderId, workflowComponent);
+```
+
+{{% /codetab %}}
+
+
+{{% codetab %}}
+
+Manage your workflow within your code. [In the workflow example from the Java SDK](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflowClient.java), the workflow is registered in the code using the following APIs:
+
+- **scheduleNewWorkflow**: Starts a new workflow instance
+- **getInstanceState**: Get information on the status of the workflow
+- **waitForInstanceStart**: Pauses or suspends a workflow instance that can later be resumed
+- **raiseEvent**: Raises events/tasks for the running workflow instance
+- **waitForInstanceCompletion**: Waits for the workflow to complete its tasks
+- **purgeInstance**: Removes all metadata related to a specific workflow instance
+- **terminateWorkflow**: Terminates the workflow
+- **purgeInstance**: Removes all metadata related to a specific workflow
+
+```java
+package io.dapr.examples.workflows;
+
+import io.dapr.workflows.client.DaprWorkflowClient;
+import io.dapr.workflows.client.WorkflowInstanceStatus;
+
+// ...
+public class DemoWorkflowClient {
+
+ // ...
+ public static void main(String[] args) throws InterruptedException {
+ DaprWorkflowClient client = new DaprWorkflowClient();
+
+ try (client) {
+ // Start a workflow
+ String instanceId = client.scheduleNewWorkflow(DemoWorkflow.class, "input data");
+
+ // Get status information on the workflow
+ WorkflowInstanceStatus workflowMetadata = client.getInstanceState(instanceId, true);
+
+ // Wait or pause for the workflow instance start
+ try {
+ WorkflowInstanceStatus waitForInstanceStartResult =
+ client.waitForInstanceStart(instanceId, Duration.ofSeconds(60), true);
+ }
+
+ // Raise an event for the workflow; you can raise several events in parallel
+ client.raiseEvent(instanceId, "TestEvent", "TestEventPayload");
+ client.raiseEvent(instanceId, "event1", "TestEvent 1 Payload");
+ client.raiseEvent(instanceId, "event2", "TestEvent 2 Payload");
+ client.raiseEvent(instanceId, "event3", "TestEvent 3 Payload");
+
+ // Wait for workflow to complete running through tasks
+ try {
+ WorkflowInstanceStatus waitForInstanceCompletionResult =
+ client.waitForInstanceCompletion(instanceId, Duration.ofSeconds(60), true);
+ }
+
+ // Purge the workflow instance, removing all metadata associated with it
+ boolean purgeResult = client.purgeInstance(instanceId);
+
+ // Terminate the workflow instance
+ client.terminateWorkflow(instanceToTerminateId, null);
+
+ System.exit(0);
+ }
+}
+```
+
+{{% /codetab %}}
+
{{% codetab %}}
@@ -106,7 +175,7 @@ Manage your workflow using HTTP calls. The example below plugs in the properties
To start your workflow with an ID `12345678`, run:
```http
-POST http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678
+POST http://localhost:3500/v1.0-beta1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678
```
Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
@@ -116,7 +185,7 @@ Note that workflow instance IDs can only contain alphanumeric characters, unders
To terminate your workflow with an ID `12345678`, run:
```http
-POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/terminate
+POST http://localhost:3500/v1.0-beta1/workflows/dapr/12345678/terminate
```
### Raise an event
@@ -124,7 +193,7 @@ POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/terminate
For workflow components that support subscribing to external events, such as the Dapr Workflow engine, you can use the following "raise event" API to deliver a named event to a specific workflow instance.
```http
-POST http://localhost:3500/v1.0-alpha1/workflows///raiseEvent/
+POST http://localhost:3500/v1.0-beta1/workflows///raiseEvent/
```
> An `eventName` can be any function.
@@ -134,13 +203,13 @@ POST http://localhost:3500/v1.0-alpha1/workflows//}}).
@@ -172,6 +241,8 @@ Learn more about these HTTP calls in the [workflow API reference guide]({{< ref
## Next steps
- [Try out the Workflow quickstart]({{< ref workflow-quickstart.md >}})
- Try out the full SDK examples:
- - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
- [Python example](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py)
+ - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
+ - [Java example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)
+
- [Workflow API reference]({{< ref workflow_api.md >}})
diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md
index da8bf0a44e1..18ec9110b30 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md
@@ -6,6 +6,10 @@ weight: 4000
description: "The Dapr Workflow engine architecture"
---
+{{% alert title="Note" color="primary" %}}
+Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-version cli="true" %}}]({{< ref "workflow-overview.md#limitations" >}}).
+{{% /alert %}}
+
[Dapr Workflows]({{< ref "workflow-overview.md" >}}) allow developers to define workflows using ordinary code in a variety of programming languages. The workflow engine runs inside of the Dapr sidecar and orchestrates workflow code deployed as part of your application. This article describes:
- The architecture of the Dapr Workflow engine
@@ -189,4 +193,7 @@ See the [Reminder usage and execution guarantees section]({{< ref "workflow-arch
- [Workflow overview]({{< ref workflow-overview.md >}})
- [Workflow API reference]({{< ref workflow_api.md >}})
- [Try out the Workflow quickstart]({{< ref workflow-quickstart.md >}})
-- [Try out the .NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
+- Try out the following examples:
+ - [Python](https://github.com/dapr/python-sdk/tree/master/examples/demo_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)
\ No newline at end of file
diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md
index c8e3de13187..ce39d4bac96 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-features-concepts.md
@@ -6,6 +6,10 @@ weight: 2000
description: "Learn more about the Dapr Workflow features and concepts"
---
+{{% alert title="Note" color="primary" %}}
+Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-version cli="true" %}}]({{< ref "workflow-overview.md#limitations" >}}).
+{{% /alert %}}
+
Now that you've learned about the [workflow building block]({{< ref workflow-overview.md >}}) at a high level, let's deep dive into the features and concepts included with the Dapr Workflow engine and SDKs. Dapr Workflow exposes several core features and concepts which are common across all supported languages.
{{% alert title="Note" color="primary" %}}
@@ -158,7 +162,7 @@ APIs that generate random numbers, random UUIDs, or the current date are _non-de
For example, instead of this:
-{{< tabs ".NET" >}}
+{{< tabs ".NET" Java >}}
{{% codetab %}}
@@ -171,11 +175,22 @@ string randomString = GetRandomString();
{{% /codetab %}}
+{{% codetab %}}
+
+```java
+// DON'T DO THIS!
+Instant currentTime = Instant.now();
+UUID newIdentifier = UUID.randomUUID();
+string randomString = GetRandomString();
+```
+
+{{% /codetab %}}
+
{{< /tabs >}}
Do this:
-{{< tabs ".NET" >}}
+{{< tabs ".NET" Java >}}
{{% codetab %}}
@@ -188,6 +203,17 @@ string randomString = await context.CallActivityAsync("GetRandomString")
{{% /codetab %}}
+{{% codetab %}}
+
+```java
+// Do this!!
+Instant currentTime = context.getCurrentInstant();
+Guid newIdentifier = context.NewGuid();
+String randomString = context.callActivity(GetRandomString.class.getName(), String.class).await();
+```
+
+{{% /codetab %}}
+
{{< /tabs >}}
@@ -198,20 +224,58 @@ Instead, workflows should interact with external state _indirectly_ using workfl
For example, instead of this:
+{{< tabs ".NET" Java >}}
+
+{{% codetab %}}
+
```csharp
// DON'T DO THIS!
string configuration = Environment.GetEnvironmentVariable("MY_CONFIGURATION")!;
string data = await new HttpClient().GetStringAsync("https://example.com/api/data");
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+```java
+// DON'T DO THIS!
+String configuration = System.getenv("MY_CONFIGURATION");
+
+HttpRequest request = HttpRequest.newBuilder().uri(new URI("https://postman-echo.com/post")).GET().build();
+HttpResponse response = HttpClient.newBuilder().build().send(request, HttpResponse.BodyHandlers.ofString());
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
Do this:
+{{< tabs ".NET" Java >}}
+
+{{% codetab %}}
+
```csharp
// Do this!!
string configuation = workflowInput.Configuration; // imaginary workflow input argument
string data = await context.CallActivityAsync("MakeHttpCall", "https://example.com/api/data");
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+```java
+// Do this!!
+String configuation = ctx.getInput(InputType.class).getConfiguration(); // imaginary workflow input argument
+String data = ctx.callActivity(MakeHttpCall.class, "https://example.com/api/data", String.class).await();
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
#### Workflow functions must execute only on the workflow dispatch thread.
The implementation of each language SDK requires that all workflow function operations operate on the same thread (goroutine, etc.) that the function was scheduled on. Workflow functions must never:
- Schedule background threads, or
@@ -221,20 +285,58 @@ Failure to follow this rule could result in undefined behavior. Any background p
For example, instead of this:
+{{< tabs ".NET" Java >}}
+
+{{% codetab %}}
+
```csharp
// DON'T DO THIS!
Task t = Task.Run(() => context.CallActivityAsync("DoSomething"));
await context.CreateTimer(5000).ConfigureAwait(false);
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+```java
+// DON'T DO THIS!
+new Thread(() -> {
+ ctx.callActivity(DoSomethingActivity.class.getName()).await();
+}).start();
+ctx.createTimer(Duration.ofSeconds(5)).await();
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
Do this:
+{{< tabs ".NET" Java >}}
+
+{{% codetab %}}
+
```csharp
// Do this!!
Task t = context.CallActivityAsync("DoSomething");
await context.CreateTimer(5000).ConfigureAwait(true);
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+```java
+// Do this!!
+ctx.callActivity(DoSomethingActivity.class.getName()).await();
+ctx.createTimer(Duration.ofSeconds(5)).await();
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
### Updating workflow code
Make sure updates you make to the workflow code maintain its determinism. A couple examples of code updates that can break workflow determinism:
diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-overview.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-overview.md
index 9f70500c01f..923bc37947e 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-overview.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-overview.md
@@ -7,7 +7,7 @@ description: "Overview of Dapr Workflow"
---
{{% alert title="Note" color="primary" %}}
-Dapr Workflow is currently in alpha.
+Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-version cli="true" %}}]({{< ref "#limitations" >}}).
{{% /alert %}}
Dapr workflow makes it easy for developers to write business logic and integrations in a reliable way. Since Dapr workflows are stateful, they support long-running and fault-tolerant applications, ideal for orchestrating microservices. Dapr workflow works seamlessly with other Dapr building blocks, such as service invocation, pub/sub, state management, and bindings.
@@ -83,9 +83,9 @@ You can use the following SDKs to author a workflow.
| Language stack | Package |
| - | - |
-| .NET | [Dapr.Workflow](https://www.nuget.org/profiles/dapr.io) |
| Python | [dapr-ext-workflow](https://github.com/dapr/python-sdk/tree/master/ext/dapr-ext-workflow) |
-
+| .NET | [Dapr.Workflow](https://www.nuget.org/profiles/dapr.io) |
+| Java | [io.dapr.workflows](https://dapr.github.io/java-sdk/io/dapr/workflows/package-summary.html) |
## Try out workflows
@@ -95,15 +95,23 @@ Want to put workflows to the test? Walk through the following quickstart and tut
| Quickstart/tutorial | Description |
| ------------------- | ----------- |
-| [Workflow quickstart]({{< ref workflow-quickstart.md >}}) | Run a .NET workflow application with four workflow activities to see Dapr Workflow in action |
-| [Workflow .NET SDK example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow) | Learn how to create a Dapr Workflow and invoke it using ASP.NET Core web APIs. |
+| [Workflow quickstart]({{< ref workflow-quickstart.md >}}) | Run a workflow application with four workflow activities to see Dapr Workflow in action |
| [Workflow Python SDK example](https://github.com/dapr/python-sdk/tree/master/examples/demo_workflow) | Learn how to create a Dapr Workflow and invoke it using the Python `DaprClient` package. |
+| [Workflow .NET SDK example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow) | Learn how to create a Dapr Workflow and invoke it using ASP.NET Core web APIs. |
+| [Workflow Java SDK example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows) | Learn how to create a Dapr Workflow and invoke it using the Java `io.dapr.workflows` package. |
### Start using workflows directly in your app
Want to skip the quickstarts? Not a problem. You can try out the workflow building block directly in your application. After [Dapr is installed]({{< ref install-dapr-cli.md >}}), you can begin using workflows, starting with [how to author a workflow]({{< ref howto-author-workflow.md >}}).
+## Limitations
+
+With Dapr Workflow in beta stage comes the following limitation(s):
+
+- **State stores:** For the {{% dapr-latest-version cli="true" %}} beta release of Dapr Workflow, you're not able to use NoSQL databases. Only SQL databases are supported in the latest release.
+- **Application instances:** For the {{% dapr-latest-version cli="true" %}} beta release of Dapr Workflow, only a maximum of 2 application instances is supported.
+
## Watch the demo
Watch [this video for an overview on Dapr Workflow](https://youtu.be/s1p9MNl4VGo?t=131):
@@ -120,3 +128,4 @@ Watch [this video for an overview on Dapr Workflow](https://youtu.be/s1p9MNl4VGo
- Try out the full SDK examples:
- [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
- [Python example](https://github.com/dapr/python-sdk/tree/master/examples/demo_workflow)
+ - [Java example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)
diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-patterns.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-patterns.md
index 4ff10782be4..9d23a64062f 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-patterns.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-patterns.md
@@ -25,42 +25,7 @@ While the pattern is simple, there are many complexities hidden in the implement
Dapr Workflow solves these complexities by allowing you to implement the task chaining pattern concisely as a simple function in the programming language of your choice, as shown in the following example.
-{{< tabs ".NET" Python >}}
-
-{{% codetab %}}
-
-
-```csharp
-// Expotential backoff retry policy that survives long outages
-var retryOptions = new WorkflowTaskOptions
-{
- RetryPolicy = new WorkflowRetryPolicy(
- firstRetryInterval: TimeSpan.FromMinutes(1),
- backoffCoefficient: 2.0,
- maxRetryInterval: TimeSpan.FromHours(1),
- maxNumberOfAttempts: 10),
-};
-
-try
-{
- var result1 = await context.CallActivityAsync("Step1", wfInput, retryOptions);
- var result2 = await context.CallActivityAsync("Step2", result1, retryOptions);
- var result3 = await context.CallActivityAsync("Step3", result2, retryOptions);
- return string.Join(", ", result4);
-}
-catch (TaskFailedException) // Task failures are surfaced as TaskFailedException
-{
- // Retries expired - apply custom compensation logic
- await context.CallActivityAsync("MyCompensation", options: retryOptions);
- throw;
-}
-```
-
-{{% alert title="Note" color="primary" %}}
-In the example above, `"Step1"`, `"Step2"`, `"Step3"`, and `"MyCompensation"` represent workflow activities, which are functions in your code that actually implement the steps of the workflow. For brevity, these activity implementations are left out of this example.
-{{% /alert %}}
-
-{{% /codetab %}}
+{{< tabs Python ".NET" Java >}}
{{% codetab %}}
@@ -103,9 +68,63 @@ def error_handler(ctx, error):
# Do some compensating work
```
-{{% alert title="Note" color="primary" %}}
-Workflow retry policies will be available in a future version of the Python SDK.
-{{% /alert %}}
+> **Note** Workflow retry policies will be available in a future version of the Python SDK.
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```csharp
+// Expotential backoff retry policy that survives long outages
+var retryOptions = new WorkflowTaskOptions
+{
+ RetryPolicy = new WorkflowRetryPolicy(
+ firstRetryInterval: TimeSpan.FromMinutes(1),
+ backoffCoefficient: 2.0,
+ maxRetryInterval: TimeSpan.FromHours(1),
+ maxNumberOfAttempts: 10),
+};
+
+try
+{
+ var result1 = await context.CallActivityAsync("Step1", wfInput, retryOptions);
+ var result2 = await context.CallActivityAsync("Step2", result1, retryOptions);
+ var result3 = await context.CallActivityAsync("Step3", result2, retryOptions);
+ return string.Join(", ", result4);
+}
+catch (TaskFailedException) // Task failures are surfaced as TaskFailedException
+{
+ // Retries expired - apply custom compensation logic
+ await context.CallActivityAsync("MyCompensation", options: retryOptions);
+ throw;
+}
+```
+
+> **Note** In the example above, `"Step1"`, `"Step2"`, `"Step3"`, and `"MyCompensation"` represent workflow activities, which are functions in your code that actually implement the steps of the workflow. For brevity, these activity implementations are left out of this example.
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```java
+public static void main(String[] args) throws InterruptedException {
+ DaprWorkflowClient client = new DaprWorkflowClient();
+
+ try (client) {
+ client.raiseEvent(instanceId, "TestEvent", "TestEventPayload");
+
+ System.out.println(separatorStr);
+ System.out.println("** Registering parallel Events to be captured by allOf(t1,t2,t3) **");
+ client.raiseEvent(instanceId, "event1", "TestEvent 1 Payload");
+ client.raiseEvent(instanceId, "event2", "TestEvent 2 Payload");
+ client.raiseEvent(instanceId, "event3", "TestEvent 3 Payload");
+ System.out.printf("Events raised for workflow with instanceId: %s\n", instanceId);
+
+ }
+}
+```
{{% /codetab %}}
@@ -135,32 +154,7 @@ In addition to the challenges mentioned in [the previous pattern]({{< ref "workf
Dapr Workflows provides a way to express the fan-out/fan-in pattern as a simple function, as shown in the following example:
-{{< tabs ".NET" Python >}}
-
-{{% codetab %}}
-
-
-```csharp
-// Get a list of N work items to process in parallel.
-object[] workBatch = await context.CallActivityAsync("GetWorkBatch", null);
-
-// Schedule the parallel tasks, but don't wait for them to complete yet.
-var parallelTasks = new List>(workBatch.Length);
-for (int i = 0; i < workBatch.Length; i++)
-{
- Task task = context.CallActivityAsync("ProcessWorkItem", workBatch[i]);
- parallelTasks.Add(task);
-}
-
-// Everything is scheduled. Wait here until all parallel tasks have completed.
-await Task.WhenAll(parallelTasks);
-
-// Aggregate all N outputs and publish the result.
-int sum = parallelTasks.Sum(t => t.Result);
-await context.CallActivityAsync("PostResults", sum);
-```
-
-{{% /codetab %}}
+{{< tabs Python ".NET" Java >}}
{{% codetab %}}
@@ -202,6 +196,80 @@ def process_results(ctx, final_result: int):
{{% /codetab %}}
+{{% codetab %}}
+
+
+```csharp
+// Get a list of N work items to process in parallel.
+object[] workBatch = await context.CallActivityAsync("GetWorkBatch", null);
+
+// Schedule the parallel tasks, but don't wait for them to complete yet.
+var parallelTasks = new List>(workBatch.Length);
+for (int i = 0; i < workBatch.Length; i++)
+{
+ Task task = context.CallActivityAsync("ProcessWorkItem", workBatch[i]);
+ parallelTasks.Add(task);
+}
+
+// Everything is scheduled. Wait here until all parallel tasks have completed.
+await Task.WhenAll(parallelTasks);
+
+// Aggregate all N outputs and publish the result.
+int sum = parallelTasks.Sum(t => t.Result);
+await context.CallActivityAsync("PostResults", sum);
+```
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```java
+public static void main(String[] args) throws InterruptedException {
+ DaprWorkflowClient client = new DaprWorkflowClient();
+
+ try (client) {
+
+ System.out.println(separatorStr);
+ System.out.println("**SendExternalMessage**");
+ client.raiseEvent(instanceId, "TestEvent", "TestEventPayload");
+
+ // Get events to process in parallel
+ System.out.println(separatorStr);
+ System.out.println("** Registering parallel Events to be captured by allOf(t1,t2,t3) **");
+ client.raiseEvent(instanceId, "event1", "TestEvent 1 Payload");
+ client.raiseEvent(instanceId, "event2", "TestEvent 2 Payload");
+ client.raiseEvent(instanceId, "event3", "TestEvent 3 Payload");
+ System.out.printf("Events raised for workflow with instanceId: %s\n", instanceId);
+
+ // Register the raised events to be captured
+ System.out.println(separatorStr);
+ System.out.println("** Registering Event to be captured by anyOf(t1,t2,t3) **");
+ client.raiseEvent(instanceId, "e2", "event 2 Payload");
+ System.out.printf("Event raised for workflow with instanceId: %s\n", instanceId);
+
+ // Wait for all tasks to complete and aggregate results
+ System.out.println(separatorStr);
+ System.out.println("**WaitForInstanceCompletion**");
+ try {
+ WorkflowInstanceStatus waitForInstanceCompletionResult =
+ client.waitForInstanceCompletion(instanceId, Duration.ofSeconds(60), true);
+ System.out.printf("Result: %s%n", waitForInstanceCompletionResult);
+ } catch (TimeoutException ex) {
+ System.out.printf("waitForInstanceCompletion has an exception:%s%n", ex);
+ }
+
+ System.out.println(separatorStr);
+ System.out.println("**purgeInstance**");
+ boolean purgeResult = client.purgeInstance(instanceId);
+ System.out.printf("purgeResult: %s%n", purgeResult);
+
+ }
+}
+```
+
+{{% /codetab %}}
+
{{< /tabs >}}
The key takeaways from this example are:
@@ -233,7 +301,7 @@ The Dapr workflow HTTP API supports the asynchronous request-reply pattern out-o
The following `curl` commands illustrate how the workflow APIs support this pattern.
```bash
-curl -X POST http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678 -d '{"Name":"Paperclips","Quantity":1,"TotalCost":9.95}'
+curl -X POST http://localhost:3500/v1.0-beta1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678 -d '{"Name":"Paperclips","Quantity":1,"TotalCost":9.95}'
```
The previous command will result in the following response JSON:
@@ -245,7 +313,7 @@ The previous command will result in the following response JSON:
The HTTP client can then construct the status query URL using the workflow instance ID and poll it repeatedly until it sees the "COMPLETE", "FAILURE", or "TERMINATED" status in the payload.
```bash
-curl http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678
+curl http://localhost:3500/v1.0-beta1/workflows/dapr/12345678
```
The following is an example of what an in-progress workflow status might look like.
@@ -302,7 +370,54 @@ Depending on the business needs, there may be a single monitor or there may be m
Dapr Workflow supports this pattern natively by allowing you to implement _eternal workflows_. Rather than writing infinite while-loops ([which is an anti-pattern]({{< ref "workflow-features-concepts.md#infinite-loops-and-eternal-workflows" >}})), Dapr Workflow exposes a _continue-as-new_ API that workflow authors can use to restart a workflow function from the beginning with a new input.
-{{< tabs ".NET" Python >}}
+{{< tabs Python ".NET" Java >}}
+
+{{% codetab %}}
+
+
+```python
+from dataclasses import dataclass
+from datetime import timedelta
+import random
+import dapr.ext.workflow as wf
+
+
+@dataclass
+class JobStatus:
+ job_id: str
+ is_healthy: bool
+
+
+def status_monitor_workflow(ctx: wf.DaprWorkflowContext, job: JobStatus):
+ # poll a status endpoint associated with this job
+ status = yield ctx.call_activity(check_status, input=job)
+ if not ctx.is_replaying:
+ print(f"Job '{job.job_id}' is {status}.")
+
+ if status == "healthy":
+ job.is_healthy = True
+ next_sleep_interval = 60 # check less frequently when healthy
+ else:
+ if job.is_healthy:
+ job.is_healthy = False
+ ctx.call_activity(send_alert, input=f"Job '{job.job_id}' is unhealthy!")
+ next_sleep_interval = 5 # check more frequently when unhealthy
+
+ yield ctx.create_timer(fire_at=ctx.current_utc_datetime + timedelta(seconds=next_sleep_interval))
+
+ # restart from the beginning with a new JobStatus input
+ ctx.continue_as_new(job)
+
+
+def check_status(ctx, _) -> str:
+ return random.choice(["healthy", "unhealthy"])
+
+
+def send_alert(ctx, message: str):
+ print(f'*** Alert: {message}')
+```
+
+{{% /codetab %}}
{{% codetab %}}
@@ -346,48 +461,44 @@ public override async Task RunAsync(WorkflowContext context, MyEntitySta
{{% /codetab %}}
{{% codetab %}}
-
-
-```python
-from dataclasses import dataclass
-from datetime import timedelta
-import random
-import dapr.ext.workflow as wf
-
-
-@dataclass
-class JobStatus:
- job_id: str
- is_healthy: bool
-
+
-def status_monitor_workflow(ctx: wf.DaprWorkflowContext, job: JobStatus):
- # poll a status endpoint associated with this job
- status = yield ctx.call_activity(check_status, input=job)
- if not ctx.is_replaying:
- print(f"Job '{job.job_id}' is {status}.")
-
- if status == "healthy":
- job.is_healthy = True
- next_sleep_interval = 60 # check less frequently when healthy
- else:
- if job.is_healthy:
- job.is_healthy = False
- ctx.call_activity(send_alert, input=f"Job '{job.job_id}' is unhealthy!")
- next_sleep_interval = 5 # check more frequently when unhealthy
+```java
+public class MonitorWorkflow extends Workflow {
- yield ctx.create_timer(fire_at=ctx.current_utc_datetime + timedelta(seconds=next_sleep_interval))
+ @Override
+ public WorkflowStub create() {
+ return ctx -> {
- # restart from the beginning with a new JobStatus input
- ctx.continue_as_new(job)
+ Duration nextSleepInterval;
+ var status = ctx.callActivity(DemoWorkflowStatusActivity.class.getName(), DemoStatusActivityOutput.class).await();
+ var isHealthy = status.getIsHealthy();
-def check_status(ctx, _) -> str:
- return random.choice(["healthy", "unhealthy"])
+ if (isHealthy) {
+ // Check less frequently when in a healthy state
+ nextSleepInterval = Duration.ofMinutes(60);
+ } else {
+ ctx.callActivity(DemoWorkflowAlertActivity.class.getName()).await();
-def send_alert(ctx, message: str):
- print(f'*** Alert: {message}')
+ // Check more frequently when in an unhealthy state
+ nextSleepInterval = Duration.ofMinutes(5);
+ }
+
+ // 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());
+ } catch (InterruptedException e) {
+ throw new RuntimeException(e);
+ }
+
+ // Restart from the beginning with the updated state
+ ctx.continueAsNew();
+ }
+ }
+}
```
{{% /codetab %}}
@@ -420,53 +531,7 @@ The following diagram illustrates this flow.
The following example code shows how this pattern can be implemented using Dapr Workflow.
-{{< tabs ".NET" Python >}}
-
-{{% codetab %}}
-
-
-```csharp
-public override async Task RunAsync(WorkflowContext context, OrderPayload order)
-{
- // ...(other steps)...
-
- // Require orders over a certain threshold to be approved
- if (order.TotalCost > OrderApprovalThreshold)
- {
- try
- {
- // Request human approval for this order
- await context.CallActivityAsync(nameof(RequestApprovalActivity), order);
-
- // Pause and wait for a human to approve the order
- ApprovalResult approvalResult = await context.WaitForExternalEventAsync(
- eventName: "ManagerApproval",
- timeout: TimeSpan.FromDays(3));
- if (approvalResult == ApprovalResult.Rejected)
- {
- // The order was rejected, end the workflow here
- return new OrderResult(Processed: false);
- }
- }
- catch (TaskCanceledException)
- {
- // An approval timeout results in automatic order cancellation
- return new OrderResult(Processed: false);
- }
- }
-
- // ...(other steps)...
-
- // End the workflow with a success result
- return new OrderResult(Processed: true);
-}
-```
-
-{{% alert title="Note" color="primary" %}}
-In the example above, `RequestApprovalActivity` is the name of a workflow activity to invoke and `ApprovalResult` is an enumeration defined by the workflow app. For brevity, these definitions were left out of the example code.
-{{% /alert %}}
-
-{{% /codetab %}}
+{{< tabs Python ".NET" Java >}}
{{% codetab %}}
@@ -527,26 +592,101 @@ def place_order(_, order: Order) -> None:
{{% /codetab %}}
-{{< /tabs >}}
+{{% codetab %}}
+
-The code that delivers the event to resume the workflow execution is external to the workflow. Workflow events can be delivered to a waiting workflow instance using the [raise event]({{< ref "howto-manage-workflow.md#raise-an-event" >}}) workflow management API, as shown in the following example:
+```csharp
+public override async Task RunAsync(WorkflowContext context, OrderPayload order)
+{
+ // ...(other steps)...
+
+ // Require orders over a certain threshold to be approved
+ if (order.TotalCost > OrderApprovalThreshold)
+ {
+ try
+ {
+ // Request human approval for this order
+ await context.CallActivityAsync(nameof(RequestApprovalActivity), order);
+
+ // Pause and wait for a human to approve the order
+ ApprovalResult approvalResult = await context.WaitForExternalEventAsync(
+ eventName: "ManagerApproval",
+ timeout: TimeSpan.FromDays(3));
+ if (approvalResult == ApprovalResult.Rejected)
+ {
+ // The order was rejected, end the workflow here
+ return new OrderResult(Processed: false);
+ }
+ }
+ catch (TaskCanceledException)
+ {
+ // An approval timeout results in automatic order cancellation
+ return new OrderResult(Processed: false);
+ }
+ }
-{{< tabs ".NET" Python >}}
+ // ...(other steps)...
+
+ // End the workflow with a success result
+ return new OrderResult(Processed: true);
+}
+```
+
+> **Note** In the example above, `RequestApprovalActivity` is the name of a workflow activity to invoke and `ApprovalResult` is an enumeration defined by the workflow app. For brevity, these definitions were left out of the example code.
+
+{{% /codetab %}}
{{% codetab %}}
-
+
+
+```java
+public static void main(String[] args) throws InterruptedException {
+ DaprWorkflowClient client = new DaprWorkflowClient();
+
+ try (client) {
+ String eventInstanceId = client.scheduleNewWorkflow(DemoWorkflow.class);
+ System.out.printf("Started new workflow instance with random ID: %s%n", eventInstanceId);
+ client.raiseEvent(eventInstanceId, "TestException", null);
+ System.out.printf("Event raised for workflow with instanceId: %s\n", eventInstanceId);
+
+ System.out.println(separatorStr);
+ String instanceToTerminateId = "terminateMe";
+ client.scheduleNewWorkflow(DemoWorkflow.class, null, instanceToTerminateId);
+ System.out.printf("Started new workflow instance with specified ID: %s%n", instanceToTerminateId);
+
+ TimeUnit.SECONDS.sleep(5);
+ System.out.println("Terminate this workflow instance manually before the timeout is reached");
+ client.terminateWorkflow(instanceToTerminateId, null);
+ System.out.println(separatorStr);
+
+ String restartingInstanceId = "restarting";
+ client.scheduleNewWorkflow(DemoWorkflow.class, null, restartingInstanceId);
+ System.out.printf("Started new workflow instance with ID: %s%n", restartingInstanceId);
+ System.out.println("Sleeping 30 seconds to restart the workflow");
+ TimeUnit.SECONDS.sleep(30);
+
+ System.out.println("**SendExternalMessage: RestartEvent**");
+ client.raiseEvent(restartingInstanceId, "RestartEvent", "RestartEventPayload");
+
+ System.out.println("Sleeping 30 seconds to terminate the eternal workflow");
+ TimeUnit.SECONDS.sleep(30);
+ client.terminateWorkflow(restartingInstanceId, null);
+ }
-```csharp
-// Raise the workflow event to the waiting workflow
-await daprClient.RaiseWorkflowEventAsync(
- instanceId: orderId,
- workflowComponent: "dapr",
- eventName: "ManagerApproval",
- eventData: ApprovalResult.Approved);
+ System.out.println("Exiting DemoWorkflowClient.");
+ System.exit(0);
+
+}
```
{{% /codetab %}}
+{{< /tabs >}}
+
+The code that delivers the event to resume the workflow execution is external to the workflow. Workflow events can be delivered to a waiting workflow instance using the [raise event]({{< ref "howto-manage-workflow.md#raise-an-event" >}}) workflow management API, as shown in the following example:
+
+{{< tabs Python ".NET" Java >}}
+
{{% codetab %}}
@@ -564,6 +704,30 @@ with DaprClient() as d:
{{% /codetab %}}
+{{% codetab %}}
+
+
+```csharp
+// Raise the workflow event to the waiting workflow
+await daprClient.RaiseWorkflowEventAsync(
+ instanceId: orderId,
+ workflowComponent: "dapr",
+ eventName: "ManagerApproval",
+ eventData: ApprovalResult.Approved);
+```
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```java
+System.out.println("**SendExternalMessage: RestartEvent**");
+client.raiseEvent(restartingInstanceId, "RestartEvent", "RestartEventPayload");
+```
+
+{{% /codetab %}}
+
{{< /tabs >}}
External events don't have to be directly triggered by humans. They can also be triggered by other systems. For example, a workflow may need to pause and wait for a payment to be received. In this case, a payment system might publish an event to a pub/sub topic on receipt of a payment, and a listener on that topic can raise an event to the workflow using the raise event workflow API.
@@ -577,4 +741,7 @@ External events don't have to be directly triggered by humans. They can also be
- [Try out Dapr Workflows using the quickstart]({{< ref workflow-quickstart.md >}})
- [Workflow overview]({{< ref workflow-overview.md >}})
- [Workflow API reference]({{< ref workflow_api.md >}})
-- [Try out the .NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
+- Try out the following examples:
+ - [Python](https://github.com/dapr/python-sdk/tree/master/examples/demo_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)
\ No newline at end of file
diff --git a/daprdocs/content/en/developing-applications/develop-components/pluggable-components/develop-pluggable.md b/daprdocs/content/en/developing-applications/develop-components/pluggable-components/develop-pluggable.md
index d25ff95d7a1..5868eabffd0 100644
--- a/daprdocs/content/en/developing-applications/develop-components/pluggable-components/develop-pluggable.md
+++ b/daprdocs/content/en/developing-applications/develop-components/pluggable-components/develop-pluggable.md
@@ -14,19 +14,21 @@ In order to implement a pluggable component, you need to implement a gRPC servic
### Find the proto definition file
-Proto definitions are provided for each supported service interface (state store, pub/sub, bindings).
+Proto definitions are provided for each supported service interface (state store, pub/sub, bindings, secret stores).
Currently, the following component APIs are supported:
- State stores
- Pub/sub
- Bindings
+- Secret stores
| Component | Type | gRPC definition | Built-in Reference Implementation | Docs |
| :---------: | :--------: | :--------------: | :----------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| State Store | `state` | [state.proto] | [Redis](https://github.com/dapr/components-contrib/tree/master/state/redis) | [concept]({{< ref "state-management-overview" >}}), [howto]({{< ref "howto-get-save-state" >}}), [api spec]({{< ref "state_api" >}}) |
-| Pub/sub | `pubsub` | [pubsub.proto] | [Redis](https://github.com/dapr/components-contrib/tree/master/pubsub/redis) | [concept]({{< ref "pubsub-overview" >}}), [howto]({{< ref "howto-publish-subscribe" >}}), [api spec]({{< ref "pubsub_api" >}}) |
-| Bindings | `bindings` | [bindings.proto] | [Kafka](https://github.com/dapr/components-contrib/tree/master/bindings/kafka) | [concept]({{< ref "bindings-overview" >}}), [input howto]({{< ref "howto-triggers" >}}), [output howto]({{< ref "howto-bindings" >}}), [api spec]({{< ref "bindings_api" >}}) |
+| State Store | `state` | [state.proto](https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/state.proto) | [Redis](https://github.com/dapr/components-contrib/tree/master/state/redis) | [concept]({{< ref "state-management-overview" >}}), [howto]({{< ref "howto-get-save-state" >}}), [api spec]({{< ref "state_api" >}}) |
+| Pub/sub | `pubsub` | [pubsub.proto](https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/pubsub.proto) | [Redis](https://github.com/dapr/components-contrib/tree/master/pubsub/redis) | [concept]({{< ref "pubsub-overview" >}}), [howto]({{< ref "howto-publish-subscribe" >}}), [api spec]({{< ref "pubsub_api" >}}) |
+| Bindings | `bindings` | [bindings.proto](https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/bindings.proto) | [Kafka](https://github.com/dapr/components-contrib/tree/master/bindings/kafka) | [concept]({{< ref "bindings-overview" >}}), [input howto]({{< ref "howto-triggers" >}}), [output howto]({{< ref "howto-bindings" >}}), [api spec]({{< ref "bindings_api" >}}) |
+| Secret Store | `secretstores` | [secretstore.proto](https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/secretstore.proto) | [Hashicorp/Vault](https://github.com/dapr/components-contrib/blob/master/secretstores/hashicorp/vault/vault.go) | [concept]({{< ref "secrets-overview" >}}), [howto-secrets]({{< ref "howto-secrets" >}}), [api spec]({{< ref "secrets_api" >}}) |
Below is a snippet of the gRPC service definition for pluggable component state stores ([state.proto]):
@@ -95,11 +97,15 @@ Provide a concrete implementation of the desired service. Each component has a g
- **Pub/sub**
- Pluggable pub/sub components only have a single core service interface defined ([pubsub.proto]). They have no optional service interfaces.
+ Pluggable pub/sub components only have a single core service interface defined [pubsub.proto](https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/pubsub.proto). They have no optional service interfaces.
- **Bindings**
- Pluggable input and output bindings have a single core service definition on [bindings.proto]. They have no optional service interfaces.
+ Pluggable input and output bindings have a single core service definition on [bindings.proto](https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/bindings.proto). They have no optional service interfaces.
+
+- **Secret Store**
+
+ Pluggable Secret store have a single core service definition on [secretstore.proto](https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/secretstore.proto). They have no optional service interfaces.
After generating the above state store example's service scaffolding code using gRPC and protocol buffers tools, you can define concrete implementations for the 9 methods defined under `service StateStore`, along with code to initialize and communicate with your dependencies.
diff --git a/daprdocs/content/en/developing-applications/develop-components/pluggable-components/pluggable-components-overview.md b/daprdocs/content/en/developing-applications/develop-components/pluggable-components/pluggable-components-overview.md
index 96b1260cc41..bdee6b540d6 100644
--- a/daprdocs/content/en/developing-applications/develop-components/pluggable-components/pluggable-components-overview.md
+++ b/daprdocs/content/en/developing-applications/develop-components/pluggable-components/pluggable-components-overview.md
@@ -63,7 +63,3 @@ In contrast, pluggable components require additional steps before they can commu
- [Implement a pluggable component]({{< ref develop-pluggable.md >}})
- [Pluggable component registration]({{< ref "pluggable-components-registration" >}})
-
-[state.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/state.proto
-[pubsub.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/pubsub.proto
-[bindings.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/bindings.proto
diff --git a/daprdocs/content/en/developing-applications/integrations/Azure/azure-functions.md b/daprdocs/content/en/developing-applications/integrations/Azure/azure-functions.md
index 7fe9dd013ad..0de36d3eb4e 100644
--- a/daprdocs/content/en/developing-applications/integrations/Azure/azure-functions.md
+++ b/daprdocs/content/en/developing-applications/integrations/Azure/azure-functions.md
@@ -7,12 +7,13 @@ weight: 3000
---
{{% alert title="Note" color="primary" %}}
-The Dapr Functions extension is currently in preview.
+The Dapr extension for Azure Functions is currently in preview.
{{% /alert %}}
+Dapr integrates with the [Azure Functions runtime](https://learn.microsoft.com/azure/azure-functions/functions-overview) via an extension that lets a function seamlessly interact with Dapr.
+- **Azure Functions** provides an event-driven programming model.
+- **Dapr** provides cloud-native building blocks.
-Dapr integrates with the [Azure Functions runtime](https://learn.microsoft.com/azure/azure-functions/functions-overview) via an extension that lets a function seamlessly interact with Dapr. Azure Functions provides an event-driven programming model and Dapr provides cloud-native building blocks. The extension combines the two for serverless and event-driven apps.
+The extension combines the two for serverless and event-driven apps.
-Try out the [Dapr Functions extension](https://github.com/dapr/azure-functions-extension) samples.
-
-{{< button text="Learn more about the Dapr Function extension in preview" link="https://cloudblogs.microsoft.com/opensource/2020/07/01/announcing-azure-functions-extension-for-dapr/" >}}
+{{< button text="Try out the Dapr extension for Azure Functions" link="https://learn.microsoft.com/azure/azure-functions/functions-bindings-dapr" >}}
diff --git a/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-overview.md b/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-overview.md
index 5fac41131e7..4e48d8a09e4 100644
--- a/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-overview.md
+++ b/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-overview.md
@@ -7,23 +7,24 @@ description: Run multiple applications with one CLI command
---
{{% alert title="Note" color="primary" %}}
- Multi-App Run is currently a preview feature only supported in Linux/MacOS.
+ Multi-App Run for **Kubernetes** is currently a preview feature.
{{% /alert %}}
-Let's say you want to run several applications locally to test them together, similar to a production scenario. With a local Kubernetes cluster, you'd be able to do this with helm/deployment YAML files. You'd also have to build them as containers and set up Kubernetes, which can add some complexity.
+Let's say you want to run several applications locally to test them together, similar to a production scenario. Multi-App Run allows you to start and stop a set of applications simultaneously, either:
+- Locally/self-hosted with processes, or
+- By building container images and deploying to a Kubernetes cluster
+ - You can use a local Kubernetes cluster (KiND) or one deploy to a Cloud (AKS, EKS, and GKE).
-Instead, you simply want to run them as local executables in self-hosted mode. However, self-hosted mode requires you to:
+The Multi-App Run template file describes how to start multiple applications as if you had run many separate CLI `run` commands. By default, this template file is called `dapr.yaml`.
-- Run multiple `dapr run` commands
-- Keep track of all ports opened (you cannot have duplicate ports for different applications).
-- Remember the resources folders and configuration files that each application refers to.
-- Recall all of the additional flags you used to tweak the `dapr run` command behavior (`--app-health-check-path`, `--dapr-grpc-port`, `--unix-domain-socket`, etc.)
+{{< tabs Self-hosted Kubernetes>}}
-With Multi-App Run, you can start multiple applications in self-hosted mode using a single `dapr run -f` command using a template file. The template file describes how to start multiple applications as if you had run many separate CLI `run`commands. By default, this template file is called `dapr.yaml`.
+{{% codetab %}}
+
## Multi-App Run template file
-When you execute `dapr run -f .`, it uses the multi-app template file (named `dapr.yaml`) present in the current directory to run all the applications.
+When you execute `dapr run -f .`, it starts the multi-app template file (named `dapr.yaml`) present in the current directory to run all the applications.
You can name template file with preferred name other than the default. For example `dapr run -f ./.yaml`.
@@ -40,7 +41,7 @@ apps:
- appID: emit-metrics
appDirPath: ../apps/emit-metrics/
daprHTTPPort: 3511
- env:
+ env:
DAPR_HOST_ADD: localhost
command: ["go","run", "app.go"]
```
@@ -49,7 +50,7 @@ For a more in-depth example and explanation of the template properties, see [Mul
## Locations for resources and configuration files
-You have options on where to place your applications' resources and configuration files when using Multi-App Run.
+You have options on where to place your applications' resources and configuration files when using Multi-App Run.
### Point to one file location (with convention)
@@ -71,9 +72,9 @@ The run template provides two log destination fields for each application and it
1. `appLogDestination` : This field configures the log destination for the application. The possible values are `console`, `file` and `fileAndConsole`. The default value is `fileAndConsole` where application logs are written to both console and to a file by default.
-2. `daprdLogDestination` : This field configures the log destination for the `daprd` process. The possible values are `console`, `file` and `fileAndConsole`. The default value is `file` where the `daprd` logs are written to a file by default.
+1. `daprdLogDestination` : This field configures the log destination for the `daprd` process. The possible values are `console`, `file` and `fileAndConsole`. The default value is `file` where the `daprd` logs are written to a file by default.
-#### Log file format
+### Log file format
Logs for application and `daprd` are captured in separate files. These log files are created automatically under `.dapr/logs` directory under each application directory (`appDirPath` in the template). These log file names follow the pattern seen below:
@@ -82,14 +83,90 @@ Logs for application and `daprd` are captured in separate files. These log files
Even if you've decided to rename your resources folder to something other than `.dapr`, the log files are written only to the `.dapr/logs` folder (created in the application directory).
-
## Watch the demo
Watch [this video for an overview on Multi-App Run](https://youtu.be/s1p9MNl4VGo?t=2456):
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+## Multi-App Run template file
+
+When you execute `dapr run -k -f .` or `dapr run -k -f dapr.yaml`, the applications defined in the `dapr.yaml` Multi-App Run template file starts in Kubernetes default namespace.
+
+> **Note:** Currently, the Multi-App Run template can only start applications in the default Kubernetes namespace.
+
+The necessary default service and deployment definitions for Kubernetes are generated within the `.dapr/deploy` folder for each app in the `dapr.yaml` template.
+
+If the `createService` field is set to `true` in the `dapr.yaml` template for an app, then the `service.yaml` file is generated in the `.dapr/deploy` folder of the app.
+
+Otherwise, only the `deployment.yaml` file is generated for each app that has the `containerImage` field set.
+
+The files `service.yaml` and `deployment.yaml` are used to deploy the applications in `default` namespace in Kubernetes. This feature is specifically targeted only for running multiple apps in a dev/test environment in Kubernetes.
+
+You can name the template file with any preferred name other than the default. For example:
+
+```bash
+dapr run -k -f ./.yaml
+```
+
+The following example includes some of the template properties you can customize for your applications. In the example, you can simultaneously launch 2 applications with app IDs of `nodeapp` and `pythonapp`.
+
+```yaml
+version: 1
+common:
+apps:
+ - appID: nodeapp
+ appDirPath: ./nodeapp/
+ appPort: 3000
+ containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest
+ createService: true
+ env:
+ APP_PORT: 3000
+ - appID: pythonapp
+ appDirPath: ./pythonapp/
+ containerImage: ghcr.io/dapr/samples/hello-k8s-python:latest
+```
+
+> **Note:**
+> - If the `containerImage` field is not specified, `dapr run -k -f` produces an error.
+> - The `createService` field defines a basic service in Kubernetes (ClusterIP or LoadBalancer) that targets the `--app-port` specified in the template. If `createService` isn't specified, the application is not accessible from outside the cluster.
+
+For a more in-depth example and explanation of the template properties, see [Multi-app template]({{< ref multi-app-template.md >}}).
+
+## Logs
+
+The run template provides two log destination fields for each application and its associated daprd process:
+
+1. `appLogDestination` : This field configures the log destination for the application. The possible values are `console`, `file` and `fileAndConsole`. The default value is `fileAndConsole` where application logs are written to both console and to a file by default.
+
+2. `daprdLogDestination` : This field configures the log destination for the `daprd` process. The possible values are `console`, `file` and `fileAndConsole`. The default value is `file` where the `daprd` logs are written to a file by default.
+
+### Log file format
+
+Logs for application and `daprd` are captured in separate files. These log files are created automatically under `.dapr/logs` directory under each application directory (`appDirPath` in the template). These log file names follow the pattern seen below:
+
+- `_app_.log` (file name format for `app` log)
+- `_daprd_.log` (file name format for `daprd` log)
+
+Even if you've decided to rename your resources folder to something other than `.dapr`, the log files are written only to the `.dapr/logs` folder (created in the application directory).
+
+## Watch the demo
+
+Watch [this video for an overview on Multi-App Run in Kubernetes](https://youtu.be/nWatANwaAik?si=O8XR-TUaiY0gclgO&t=1024):
+
+
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
## Next steps
- [Learn the Multi-App Run template file structure and its properties]({{< ref multi-app-template.md >}})
-- [Try out the Multi-App Run template with the Service Invocation quickstart]({{< ref serviceinvocation-quickstart.md >}})
\ No newline at end of file
+- [Try out the self-hosted Multi-App Run template with the Service Invocation quickstart]({{< ref serviceinvocation-quickstart.md >}})
+- [Try out the Kubernetes Multi-App Run template with the `hello-kubernetes` tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-kubernetes)
\ No newline at end of file
diff --git a/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md b/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md
index 8bca3008036..350ef0f4219 100644
--- a/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md
+++ b/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md
@@ -7,7 +7,7 @@ description: Unpack the Multi-App Run template file and its properties
---
{{% alert title="Note" color="primary" %}}
- Multi-App Run is currently a preview feature only supported in Linux/MacOS.
+ Multi-App Run for **Kubernetes** is currently a preview feature.
{{% /alert %}}
The Multi-App Run template file is a YAML file that you can use to run multiple applications at once. In this guide, you'll learn how to:
@@ -26,20 +26,53 @@ When you provide a directory path, the CLI will try to locate the Multi-App Run
Execute the following CLI command to read the Multi-App Run template file, named `dapr.yaml` by default:
+{{< tabs Self-hosted Kubernetes>}}
+
+{{% codetab %}}
+
+
```cmd
# the template file needs to be called `dapr.yaml` by default if a directory path is given
dapr run -f
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```cmd
+dapr run -f -k
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
### Execute by providing a file path
If the Multi-App Run template file is named something other than `dapr.yaml`, then you can provide the relative or absolute file path to the command:
+{{< tabs Self-hosted Kubernetes>}}
+
+{{% codetab %}}
+
+
```cmd
dapr run -f ./path/to/.yaml
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```cmd
+dapr run -f -k ./path/to/.yaml
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
## View the started applications
Once the multi-app template is running, you can view the started applications with the following command:
@@ -52,6 +85,11 @@ dapr list
Stop the multi-app run template anytime with either of the following commands:
+{{< tabs Self-hosted Kubernetes>}}
+
+{{% codetab %}}
+
+
```cmd
# the template file needs to be called `dapr.yaml` by default if a directory path is given
@@ -63,10 +101,36 @@ or:
dapr stop -f ./path/to/.yaml
```
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```cmd
+# the template file needs to be called `dapr.yaml` by default if a directory path is given
+
+dapr stop -f -k
+```
+or:
+
+```cmd
+dapr stop -f -k ./path/to/.yaml
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
## Template file structure
The Multi-App Run template file can include the following properties. Below is an example template showing two applications that are configured with some of the properties.
+{{< tabs Self-hosted Kubernetes>}}
+
+{{% codetab %}}
+
+
```yaml
version: 1
common: # optional section for variables shared across apps
@@ -92,23 +156,65 @@ apps:
appPort: 3000
unixDomainSocket: "/tmp/test-socket"
env:
- - DEBUG: false
+ DEBUG: false
command: ["./backend"]
```
-{{% alert title="Important" color="warning" %}}
The following rules apply for all the paths present in the template file:
- If the path is absolute, it is used as is.
- - All relative paths under comman section should be provided relative to the template file path.
+ - All relative paths under command section should be provided relative to the template file path.
- `appDirPath` under apps section should be provided relative to the template file path.
- - All relative paths under app section should be provided relative to the appDirPath.
+ - All relative paths under app section should be provided relative to the `appDirPath`.
-{{% /alert %}}
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+```yaml
+version: 1
+common: # optional section for variables shared across apps
+ env: # any environment variable shared across apps
+ DEBUG: true
+apps:
+ - appID: webapp # optional
+ appDirPath: .dapr/webapp/ # REQUIRED
+ appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention.
+ appProtocol: http
+ appPort: 8080
+ appHealthCheckPath: "/healthz"
+ appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole.
+ daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file.
+ containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest # (optional) URI of the container image to be used when deploying to Kubernetes dev/test environment.
+ createService: true # (optional) Create a Kubernetes service for the application when deploying to dev/test environment.
+ - appID: backend # optional
+ appDirPath: .dapr/backend/ # REQUIRED
+ appProtocol: grpc
+ appPort: 3000
+ unixDomainSocket: "/tmp/test-socket"
+ env:
+ DEBUG: false
+```
+
+The following rules apply for all the paths present in the template file:
+ - If the path is absolute, it is used as is.
+ - `appDirPath` under apps section should be provided relative to the template file path.
+ - All relative paths under app section should be provided relative to the `appDirPath`.
+
+{{% /codetab %}}
+
+{{< /tabs >}}
## Template properties
+{{< tabs Self-hosted Kubernetes>}}
+
+{{% codetab %}}
+
+
The properties for the Multi-App Run template align with the `dapr run` CLI flags, [listed in the CLI reference documentation]({{< ref "dapr-run.md#flags" >}}).
+{{< table "table table-white table-striped table-bordered" >}}
| Properties | Required | Details | Example |
|--------------------------|:--------:|--------|---------|
@@ -146,8 +252,66 @@ The properties for the Multi-App Run template align with the `dapr run` CLI flag
| `appLogDestination` | N | Log destination for outputting app logs; Its value can be file, console or fileAndConsole. Default is fileAndConsole | `file`, `console`, `fileAndConsole` |
| `daprdLogDestination` | N | Log destination for outputting daprd logs; Its value can be file, console or fileAndConsole. Default is file | `file`, `console`, `fileAndConsole` |
+{{< /table >}}
+
## Next steps
Watch [this video for an overview on Multi-App Run](https://youtu.be/s1p9MNl4VGo?t=2456):
+{{% /codetab %}}
+
+{{% codetab %}}
+
+
+The properties for the Multi-App Run template align with the `dapr run -k` CLI flags, [listed in the CLI reference documentation]({{< ref "dapr-run.md#flags" >}}).
+
+{{< table "table table-white table-striped table-bordered" >}}
+
+| Properties | Required | Details | Example |
+|--------------------------|:--------:|--------|---------|
+| `appDirPath` | Y | Path to the your application code | `./webapp/`, `./backend/` |
+| `appID` | N | Application's app ID. If not provided, will be derived from `appDirPath` | `webapp`, `backend` |
+| `appChannelAddress` | N | The network address the application listens on. Can be left to the default value by convention. | `127.0.0.1` | `localhost` |
+| `appProtocol` | N | The protocol Dapr uses to talk to the application. | `http`, `grpc` |
+| `appPort` | N | The port your application is listening on | `8080`, `3000` |
+| `daprHTTPPort` | N | Dapr HTTP port | |
+| `daprGRPCPort` | N | Dapr GRPC port | |
+| `daprInternalGRPCPort` | N | gRPC port for the Dapr Internal API to listen on; used when parsing the value from a local DNS component | |
+| `metricsPort` | N | The port that Dapr sends its metrics information to | |
+| `unixDomainSocket` | N | Path to a unix domain socket dir mount. If specified, communication with the Dapr sidecar uses unix domain sockets for lower latency and greater throughput when compared to using TCP ports. Not available on Windows. | `/tmp/test-socket` |
+| `profilePort` | N | The port for the profile server to listen on | |
+| `enableProfiling` | N | Enable profiling via an HTTP endpoint | |
+| `apiListenAddresses` | N | Dapr API listen addresses | |
+| `logLevel` | N | The log verbosity. | |
+| `appMaxConcurrency` | N | The concurrency level of the application; default is unlimited | |
+| `placementHostAddress` | N | | |
+| `appSSL` | N | Enable https when Dapr invokes the application | |
+| `daprHTTPMaxRequestSize` | N | Max size of the request body in MB. | |
+| `daprHTTPReadBufferSize` | N | Max size of the HTTP read buffer in KB. This also limits the maximum size of HTTP headers. The default 4 KB | |
+| `enableAppHealthCheck` | N | Enable the app health check on the application | `true`, `false` |
+| `appHealthCheckPath` | N | Path to the health check file | `/healthz` |
+| `appHealthProbeInterval` | N | Interval to probe for the health of the app in seconds
+ | |
+| `appHealthProbeTimeout` | N | Timeout for app health probes in milliseconds | |
+| `appHealthThreshold` | N | Number of consecutive failures for the app to be considered unhealthy | |
+| `enableApiLogging` | N | Enable the logging of all API calls from application to Dapr | |
+| `env` | N | Map to environment variable; environment variables applied per application will overwrite environment variables shared across applications | `DEBUG`, `DAPR_HOST_ADD` |
+| `appLogDestination` | N | Log destination for outputting app logs; Its value can be file, console or fileAndConsole. Default is fileAndConsole | `file`, `console`, `fileAndConsole` |
+| `daprdLogDestination` | N | Log destination for outputting daprd logs; Its value can be file, console or fileAndConsole. Default is file | `file`, `console`, `fileAndConsole` |
+| `containerImage`| N | URI of the container image to be used when deploying to Kubernetes dev/test environment. | `ghcr.io/dapr/samples/hello-k8s-python:latest`
+| `createService`| N | Create a Kubernetes service for the application when deploying to dev/test environment. | `true`, `false` |
+
+{{< /table >}}
+
+## Next steps
+
+Watch [this video for an overview on Multi-App Run in Kubernetes](https://youtu.be/nWatANwaAik?si=O8XR-TUaiY0gclgO&t=1024):
+
+
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
diff --git a/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md
index b818c434836..cbfa248c94b 100644
--- a/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md
+++ b/daprdocs/content/en/getting-started/quickstarts/bindings-quickstart.md
@@ -11,7 +11,7 @@ Let's take a look at Dapr's [Bindings building block]({{< ref bindings >}}). Usi
- Trigger your app with events coming in from external systems.
- Interface with external systems.
-In this Quickstart, you will schedule a batch script to run every 10 seconds using an input [Cron]({{< ref cron.md >}}) binding. The script processes a JSON file and outputs data to a SQL database using the [PostgreSQL]({{< ref postgresql.md >}}) Dapr binding.
+In this Quickstart, you schedule a batch script to run every 10 seconds using an input [Cron]({{< ref cron.md >}}) binding. The script processes a JSON file and outputs data to a SQL database using the [PostgreSQL]({{< ref postgresql.md >}}) Dapr binding.
getCheckout(@RequestBody(required = false) CloudEvent cloudEvent) {
+ return Mono.fromSupplier(() -> {
+ try {
+ logger.info("Subscriber received: " + cloudEvent.getData().getOrderId());
+ return ResponseEntity.ok("SUCCESS");
+ } catch (Exception e) {
+ throw new RuntimeException(e);
+ }
+ });
+}
+```
+
+##### `checkout` publisher
+
+In the `checkout` publisher, you publish the orderId message to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop:
+
+```java
+DaprClient client = new DaprClientBuilder().build();
+client.publishEvent(
+ PUBSUB_NAME,
+ TOPIC_NAME,
+ order).block();
+logger.info("Published data: " + order.getOrderId());
+```
+
+{{% /codetab %}}
+
+
+{{% codetab %}}
+
+### Step 1: Pre-requisites
+
+For this example, you will need:
+
+- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
+- [Latest version of Go](https://go.dev/dl/).
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop)
+
+
+### Step 2: Set up the environment
+
+Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/pub_sub).
+
+```bash
+git clone https://github.com/dapr/quickstarts.git
+```
+
+From the root of the Quickstarts directory, navigate into the pub/sub directory:
+
+```bash
+cd pub_sub/go/sdk
+```
+
+### Step 3: Run the publisher and subscriber
+
+With the following command, simultaneously run the following services alongside their own Dapr sidecars:
+- The `order-processor` subscriber
+- The `checkout` publisher
+
+```bash
+dapr run -f .
+```
+
+**Expected output**
+
+```
+== APP - checkout-sdk == Published data: Order { OrderId = 1 }
+== APP - order-processor == Subscriber received : Order { OrderId = 1 }
+== APP - checkout-sdk == Published data: Order { OrderId = 2 }
+== APP - order-processor == Subscriber received : Order { OrderId = 2 }
+== APP - checkout-sdk == Published data: Order { OrderId = 3 }
+== APP - order-processor == Subscriber received : Order { OrderId = 3 }
+== APP - checkout-sdk == Published data: Order { OrderId = 4 }
+== APP - order-processor == Subscriber received : Order { OrderId = 4 }
+== APP - checkout-sdk == Published data: Order { OrderId = 5 }
+== APP - order-processor == Subscriber received : Order { OrderId = 5 }
+== APP - checkout-sdk == Published data: Order { OrderId = 6 }
+== APP - order-processor == Subscriber received : Order { OrderId = 6 }
+== APP - checkout-sdk == Published data: Order { OrderId = 7 }
+== APP - order-processor == Subscriber received : Order { OrderId = 7 }
+== APP - checkout-sdk == Published data: Order { OrderId = 8 }
+== APP - order-processor == Subscriber received : Order { OrderId = 8 }
+== APP - checkout-sdk == Published data: Order { OrderId = 9 }
+== APP - order-processor == Subscriber received : Order { OrderId = 9 }
+== APP - checkout-sdk == Published data: Order { OrderId = 10 }
+== APP - order-processor == Subscriber received : Order { OrderId = 10 }
+Exited App successfully
+```
+
+### What happened?
+
+When you ran `dapr init` during Dapr install, the following YAML files were generated in the `.dapr/components` directory:
+- [`dapr.yaml` Multi-App Run template file]({{< ref "#dapryaml-multi-app-run-template-file" >}})
+- [`pubsub.yaml` component file]({{< ref "#pubsubyaml-component-file" >}})
+
+Running `dapr run -f .` in this Quickstart started both the [subscriber]({{< ref "#order-processor-subscriber" >}}) and [publisher]({{< ref "#checkout-publisher" >}}) applications.
+
+##### `dapr.yaml` Multi-App Run template file
+
+Running the [Multi-App Run template file]({{< ref multi-app-dapr-run >}}) with `dapr run -f .` starts all applications in your project. In this Quickstart, the `dapr.yaml` file contains the following:
+
+```yml
+version: 1
+common:
+ resourcesPath: ../../components/
+apps:
+ - appID: order-processor
+ appDirPath: ./order-processor/
+ appPort: 6005
+ command: ["go", "run", "."]
+ - appID: checkout-sdk
+ appDirPath: ./checkout/
+ command: ["go", "run", "."]
+```
+
+##### `pubsub.yaml` component file
+
+With the `pubsub.yaml` component, you can easily swap out underlying components without application code changes.
+
+The Redis `pubsub.yaml` file included for this Quickstart contains the following:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: orderpubsub
+spec:
+ type: pubsub.redis
+ version: v1
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""
+```
+
+In the component YAML file:
+
+- `metadata/name` is how your application talks to the component.
+- `spec/metadata` defines the connection to the instance of the component.
+- `scopes` specify which application can use the component.
+
+##### `order-processor` subscriber
+
+In the `order-processor` subscriber, you subscribe to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar.
+
+```go
+func eventHandler(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
+ fmt.Println("Subscriber received: ", e.Data)
+ return false, nil
+}
+```
+
+##### `checkout` publisher
+
+In the `checkout` publisher, you publish the orderId message to the Redis instance called `orderpubsub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop:
+
+```go
+client, err := dapr.NewClient()
+
+if err := client.PublishEvent(ctx, PUBSUB_NAME, PUBSUB_TOPIC, []byte(order)); err != nil {
+ panic(err)
+}
+
+fmt.Println("Published data: ", order)
+```
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Run one application at a time
+
Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.
{{< tabs "Python" "JavaScript" ".NET" "Java" "Go" >}}
@@ -157,7 +908,7 @@ Subscriber output:
== APP == INFO:root:Subscriber received: {"orderId": 10}
```
-#### `pubsub.yaml` component file
+##### `pubsub.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
@@ -315,7 +1066,7 @@ Subscriber output:
```
-#### `pubsub.yaml` component file
+##### `pubsub.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
@@ -468,7 +1219,7 @@ Subscriber output:
== APP == Subscriber received: Order { OrderId = 10 }
```
-#### `pubsub.yaml` component file
+##### `pubsub.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
@@ -630,7 +1381,7 @@ Subscriber output:
== APP == 2022-03-07 13:31:37.919 INFO 43512 --- [nio-8080-exec-2] c.s.c.OrderProcessingServiceController : Subscriber received: 10
```
-#### `pubsub.yaml` component file
+##### `pubsub.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
@@ -788,7 +1539,7 @@ Subscriber output:
Note: the order in which they are received may vary.
-#### `pubsub.yaml` component file
+##### `pubsub.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
diff --git a/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md
index fc61df703cf..c33c529f952 100644
--- a/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md
+++ b/daprdocs/content/en/getting-started/quickstarts/serviceinvocation-quickstart.md
@@ -10,10 +10,678 @@ With [Dapr's Service Invocation building block](https://docs.dapr.io/developing-
response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+System.out.println("Order passed: "+ orderId)
+```
+
+{{% /codetab %}}
+
+
+{{% codetab %}}
+
+### Step 1: Pre-requisites
+
+For this example, you will need:
+
+- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
+- [Latest version of Go](https://go.dev/dl/).
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop)
+
+
+### Step 2: Set up the environment
+
+Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/service_invocation).
+
+
+```bash
+git clone https://github.com/dapr/quickstarts.git
+```
+
+From the root of the Quickstart clone directory, navigate to the quickstart directory.
+
+```bash
+cd service_invocation/go/http
+```
+
+### Step 3: Run the `order-processor` and `checkout` services
+
+With the following command, simultaneously run the following services alongside their own Dapr sidecars:
+- The `order-processor` service
+- The `checkout` service
+
+```bash
+dapr run -f .
+```
+
+**Expected output**
+
+```
+== APP - order-processor == Order received : Order { orderId = 1 }
+== APP - checkout == Order passed: Order { OrderId = 1 }
+== APP - order-processor == Order received : Order { orderId = 2 }
+== APP - checkout == Order passed: Order { OrderId = 2 }
+== APP - order-processor == Order received : Order { orderId = 3 }
+== APP - checkout == Order passed: Order { OrderId = 3 }
+== APP - order-processor == Order received : Order { orderId = 4 }
+== APP - checkout == Order passed: Order { OrderId = 4 }
+== APP - order-processor == Order received : Order { orderId = 5 }
+== APP - checkout == Order passed: Order { OrderId = 5 }
+== APP - order-processor == Order received : Order { orderId = 6 }
+== APP - checkout == Order passed: Order { OrderId = 6 }
+== APP - order-processor == Order received : Order { orderId = 7 }
+== APP - checkout == Order passed: Order { OrderId = 7 }
+== APP - order-processor == Order received : Order { orderId = 8 }
+== APP - checkout == Order passed: Order { OrderId = 8 }
+== APP - order-processor == Order received : Order { orderId = 9 }
+== APP - checkout == Order passed: Order { OrderId = 9 }
+== APP - order-processor == Order received : Order { orderId = 10 }
+== APP - checkout == Order passed: Order { OrderId = 10 }
+== APP - order-processor == Order received : Order { orderId = 11 }
+== APP - checkout == Order passed: Order { OrderId = 11 }
+== APP - order-processor == Order received : Order { orderId = 12 }
+== APP - checkout == Order passed: Order { OrderId = 12 }
+== APP - order-processor == Order received : Order { orderId = 13 }
+== APP - checkout == Order passed: Order { OrderId = 13 }
+== APP - order-processor == Order received : Order { orderId = 14 }
+== APP - checkout == Order passed: Order { OrderId = 14 }
+== APP - order-processor == Order received : Order { orderId = 15 }
+== APP - checkout == Order passed: Order { OrderId = 15 }
+== APP - order-processor == Order received : Order { orderId = 16 }
+== APP - checkout == Order passed: Order { OrderId = 16 }
+== APP - order-processor == Order received : Order { orderId = 17 }
+== APP - checkout == Order passed: Order { OrderId = 17 }
+== APP - order-processor == Order received : Order { orderId = 18 }
+== APP - checkout == Order passed: Order { OrderId = 18 }
+== APP - order-processor == Order received : Order { orderId = 19 }
+== APP - checkout == Order passed: Order { OrderId = 19 }
+== APP - order-processor == Order received : Order { orderId = 20 }
+== APP - checkout == Order passed: Order { OrderId = 20 }
+Exited App successfully
+```
+
+### What happened?
+
+Running `dapr run -f .` in this Quickstart started both the [subscriber]({{< ref "#order-processor-service" >}}) and [publisher]({{< ref "#checkout-service" >}}) applications using the `dapr.yaml` Multi-App Run template file.
+
+##### `dapr.yaml` Multi-App Run template file
+
+Running the [Multi-App Run template file]({{< ref multi-app-dapr-run >}}) with `dapr run -f .` starts all applications in your project. In this Quickstart, the `dapr.yaml` file contains the following:
+
+```yml
+version: 1
+apps:
+ - appDirPath: ./order-processor/
+ appID: order-processor
+ appPort: 6006
+ command: ["go", "run", "."]
+ - appID: checkout
+ appDirPath: ./checkout/
+ command: ["go", "run", "."]
+```
+
+##### `order-processor` service
+
+In the `order-processor` service, each order is received via an HTTP POST request and processed by the `getOrder` function.
+
+```go
+func getOrder(w http.ResponseWriter, r *http.Request) {
+ data, err := ioutil.ReadAll(r.Body)
+ if err != nil {
+ log.Fatal(err)
+ }
+ log.Printf("Order received : %s", string(data))
+}
+```
+
+##### `checkout` service
+
+In the `checkout` service, you'll notice there's no need to rewrite your app code to use Dapr's service invocation. You can enable service invocation by simply adding the `dapr-app-id` header, which specifies the ID of the target service.
+
+```go
+req.Header.Add("dapr-app-id", "order-processor")
+
+response, err := client.Do(req)
+```
+
+{{% /codetab %}}
+
+{{% /tabs %}}
+
+## Run one application at a time
+
Select your preferred language before proceeding with the Quickstart.
{{< tabs "Python" "JavaScript" ".NET" "Java" "Go" >}}
diff --git a/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md
index f73aa37f494..4d1224c4eb7 100644
--- a/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md
+++ b/daprdocs/content/en/getting-started/quickstarts/statemanagement-quickstart.md
@@ -6,10 +6,652 @@ weight: 72
description: "Get started with Dapr's State Management building block"
---
-Let's take a look at Dapr's [State Management building block]({{< ref state-management >}}). In this Quickstart, you will save, get, and delete state using a Redis state store, but you can swap this out for any one of the [supported state stores]({{< ref supported-state-stores.md >}}).
+Let's take a look at Dapr's [State Management building block]({{< ref state-management >}}). In this Quickstart, you will save, get, and delete state using a Redis state store by either:
+- [Running all applications simultaneously with the Multi-App Run template file]({{< ref "#run-using-multi-app-run" >}}), or
+- [Running a single application at a time]({{< ref "#run-one-application-at-a-time" >}})
(DAPR_STORE_NAME, orderId.ToString());
+Console.WriteLine("Getting Order: " + result);
+
+// Delete state from the state store
+await client.DeleteStateAsync(DAPR_STORE_NAME, orderId.ToString());
+Console.WriteLine("Deleting Order: " + order);
+```
+### Step 3: View the order-processor outputs
+
+Notice, as specified in the code above, the code saves application state in the Dapr state store, reads it, then deletes it.
+
+Order-processor output:
+```
+== APP == Saving Order: Order { orderId = 1 }
+== APP == Getting Order: Order { orderId = 1 }
+== APP == Deleting Order: Order { orderId = 1 }
+== APP == Saving Order: Order { orderId = 2 }
+== APP == Getting Order: Order { orderId = 2 }
+== APP == Deleting Order: Order { orderId = 2 }
+== APP == Saving Order: Order { orderId = 3 }
+== APP == Getting Order: Order { orderId = 3 }
+== APP == Deleting Order: Order { orderId = 3 }
+== APP == Saving Order: Order { orderId = 4 }
+== APP == Getting Order: Order { orderId = 4 }
+== APP == Deleting Order: Order { orderId = 4 }
+== APP == Saving Order: Order { orderId = 5 }
+== APP == Getting Order: Order { orderId = 5 }
+== APP == Deleting Order: Order { orderId = 5 }
+```
+
+##### `dapr.yaml` Multi-App Run template file
+
+When you run `dapr init`, Dapr creates a default Multi-App Run template file named `dapr.yaml`. Running `dapr run -f` starts all applications in your project. In this sample, the `dapr.yaml` file contains the following:
+
+```yml
+version: 1
+common:
+ resourcesPath: ../../../resources/
+apps:
+ - appID: order-processor
+ appDirPath: ./order-processor/
+ command: ["dotnet", "run"]
+```
+
+##### `statestore.yaml` component file
+
+When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
+
+- On Windows, under `%UserProfile%\.dapr\components\statestore.yaml`
+- On Linux/MacOS, under `~/.dapr/components/statestore.yaml`
+
+With the `statestore.yaml` component, you can easily swap out the [state store](/reference/components-reference/supported-state-stores/) without making code changes.
+
+The Redis `statestore.yaml` file included for this quickstart contains the following:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: statestore
+spec:
+ type: state.redis
+ version: v1
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""
+ - name: actorStateStore
+ value: "true"
+```
+
+In the YAML file:
+
+- `metadata/name` is how your application talks to the component (called `DAPR_STORE_NAME` in the code sample).
+- `spec/metadata` defines the connection to the Redis instance used by the component.
+
+{{% /codetab %}}
+
+
+{{% codetab %}}
+
+### Pre-requisites
+
+For this example, you will need:
+
+- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
+- Java JDK 11 (or greater):
+ - [Oracle JDK](https://www.oracle.com/java/technologies/downloads), or
+ - OpenJDK
+- [Apache Maven](https://maven.apache.org/install.html), version 3.x.
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop)
+
+
+### Step 1: Set up the environment
+
+Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/state_management).
+
+```bash
+git clone https://github.com/dapr/quickstarts.git
+```
+
+### Step 2: Manipulate service state
+
+In a terminal window, navigate to the `order-processor` directory.
+
+```bash
+cd state_management/java/sdk/order-processor
+```
+
+Run the `order-processor` service alongside a Dapr sidecar.
+
+```bash
+dapr run -f
+```
+
+The `order-processor` service writes, reads, and deletes an `orderId` key/value pair to the `statestore` instance [defined in the `statestore.yaml` component]({{< ref "#statestoreyaml-component-file" >}}). As soon as the service starts, it performs a loop.
+
+```java
+try (DaprClient client = new DaprClientBuilder().build()) {
+ for (int i = 1; i <= 10; i++) {
+ int orderId = i;
+ Order order = new Order();
+ order.setOrderId(orderId);
+
+ // Save state into the state store
+ client.saveState(DAPR_STATE_STORE, String.valueOf(orderId), order).block();
+ LOGGER.info("Saving Order: " + order.getOrderId());
+
+ // Get state from the state store
+ State response = client.getState(DAPR_STATE_STORE, String.valueOf(orderId), Order.class).block();
+ LOGGER.info("Getting Order: " + response.getValue().getOrderId());
+
+ // Delete state from the state store
+ client.deleteState(DAPR_STATE_STORE, String.valueOf(orderId)).block();
+ LOGGER.info("Deleting Order: " + orderId);
+ TimeUnit.MILLISECONDS.sleep(1000);
+ }
+```
+### Step 3: View the order-processor outputs
+
+Notice, as specified in the code above, the code saves application state in the Dapr state store, reads it, then deletes it.
+
+Order-processor output:
+```
+== APP == INFO:root:Saving Order: {'orderId': '1'}
+== APP == INFO:root:Result after get: b"{'orderId': '1'}"
+== APP == INFO:root:Deleting Order: {'orderId': '1'}
+== APP == INFO:root:Saving Order: {'orderId': '2'}
+== APP == INFO:root:Result after get: b"{'orderId': '2'}"
+== APP == INFO:root:Deleting Order: {'orderId': '2'}
+== APP == INFO:root:Saving Order: {'orderId': '3'}
+== APP == INFO:root:Result after get: b"{'orderId': '3'}"
+== APP == INFO:root:Deleting Order: {'orderId': '3'}
+== APP == INFO:root:Saving Order: {'orderId': '4'}
+== APP == INFO:root:Result after get: b"{'orderId': '4'}"
+== APP == INFO:root:Deleting Order: {'orderId': '4'}
+```
+
+##### `dapr.yaml` Multi-App Run template file
+
+When you run `dapr init`, Dapr creates a default Multi-App Run template file named `dapr.yaml`. Running `dapr run -f` starts all applications in your project. In this sample, the `dapr.yaml` file contains the following:
+
+```yml
+version: 1
+common:
+ resourcesPath: ../../resources/
+apps:
+ - appID: order-processor
+ appDirPath: ./order-processor/
+ command: ["java", "-jar", "target/OrderProcessingService-0.0.1-SNAPSHOT.jar"]
+```
+
+##### `statestore.yaml` component file
+
+When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
+
+- On Windows, under `%UserProfile%\.dapr\components\statestore.yaml`
+- On Linux/MacOS, under `~/.dapr/components/statestore.yaml`
+
+With the `statestore.yaml` component, you can easily swap out the [state store](/reference/components-reference/supported-state-stores/) without making code changes.
+
+The Redis `statestore.yaml` file included for this Quickstart contains the following:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: statestore
+spec:
+ type: state.redis
+ version: v1
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""
+ - name: actorStateStore
+ value: "true"
+```
+
+In the YAML file:
+
+- `metadata/name` is how your application talks to the component (called `DAPR_STORE_NAME` in the code sample).
+- `spec/metadata` defines the connection to the Redis instance used by the component.
+
+{{% /codetab %}}
+
+
+{{% codetab %}}
+
+### Pre-requisites
+
+For this example, you will need:
+
+- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
+- [Latest version of Go](https://go.dev/dl/).
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop)
+
+
+### Step 1: Set up the environment
+
+Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/state_management).
+
+```bash
+git clone https://github.com/dapr/quickstarts.git
+```
+
+### Step 2: Manipulate service state
+
+In a terminal window, navigate to the `order-processor` directory.
+
+```bash
+cd state_management/go/sdk/order-processor
+```
+
+Run the `order-processor` service alongside a Dapr sidecar.
+
+```bash
+dapr run -f
+```
+
+The `order-processor` service writes, reads, and deletes an `orderId` key/value pair to the `statestore` instance [defined in the `statestore.yaml` component]({{< ref "#statestoreyaml-component-file" >}}). As soon as the service starts, it performs a loop.
+
+```go
+ client, err := dapr.NewClient()
+
+ // Save state into the state store
+ _ = client.SaveState(ctx, STATE_STORE_NAME, strconv.Itoa(orderId), []byte(order))
+ log.Print("Saving Order: " + string(order))
+
+ // Get state from the state store
+ result, _ := client.GetState(ctx, STATE_STORE_NAME, strconv.Itoa(orderId))
+ fmt.Println("Getting Order: " + string(result.Value))
+
+ // Delete state from the state store
+ _ = client.DeleteState(ctx, STATE_STORE_NAME, strconv.Itoa(orderId))
+ log.Print("Deleting Order: " + string(order))
+```
+
+### Step 3: View the order-processor outputs
+
+Notice, as specified in the code above, the code saves application state in the Dapr state store, reads it, then deletes it.
+
+Order-processor output:
+```
+== APP == dapr client initializing for: 127.0.0.1:53689
+== APP == 2022/04/01 09:16:03 Saving Order: {"orderId":1}
+== APP == Getting Order: {"orderId":1}
+== APP == 2022/04/01 09:16:03 Deleting Order: {"orderId":1}
+== APP == 2022/04/01 09:16:03 Saving Order: {"orderId":2}
+== APP == Getting Order: {"orderId":2}
+== APP == 2022/04/01 09:16:03 Deleting Order: {"orderId":2}
+== APP == 2022/04/01 09:16:03 Saving Order: {"orderId":3}
+== APP == Getting Order: {"orderId":3}
+== APP == 2022/04/01 09:16:03 Deleting Order: {"orderId":3}
+== APP == 2022/04/01 09:16:03 Saving Order: {"orderId":4}
+== APP == Getting Order: {"orderId":4}
+== APP == 2022/04/01 09:16:03 Deleting Order: {"orderId":4}
+== APP == 2022/04/01 09:16:03 Saving Order: {"orderId":5}
+== APP == Getting Order: {"orderId":5}
+== APP == 2022/04/01 09:16:03 Deleting Order: {"orderId":5}
+```
+
+##### `dapr.yaml` Multi-App Run template file
+
+When you run `dapr init`, Dapr creates a default Multi-App Run template file named `dapr.yaml`. Running `dapr run -f` starts all applications in your project. In this sample, the `dapr.yaml` file contains the following:
+
+```yml
+version: 1
+common:
+ resourcesPath: ../../resources/
+apps:
+ - appID: order-processor
+ appDirPath: ./order-processor/
+ command: ["go", "run", "."]
+```
+
+##### `statestore.yaml` component file
+
+When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
+
+- On Windows, under `%UserProfile%\.dapr\components\statestore.yaml`
+- On Linux/MacOS, under `~/.dapr/components/statestore.yaml`
+
+With the `statestore.yaml` component, you can easily swap out the [state store](/reference/components-reference/supported-state-stores/) without making code changes.
+
+The Redis `statestore.yaml` file included for this Quickstart contains the following:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: statestore
+spec:
+ type: state.redis
+ version: v1
+ metadata:
+ - name: redisHost
+ value: localhost:6379
+ - name: redisPassword
+ value: ""
+ - name: actorStateStore
+ value: "true"
+```
+
+In the YAML file:
+
+- `metadata/name` is how your application talks to the component (called `DAPR_STORE_NAME` in the code sample).
+- `spec/metadata` defines the connection to the Redis instance used by the component.
+
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+
+## Run one application at a time
+
Select your preferred language-specific Dapr SDK before proceeding with the Quickstart.
{{< tabs "Python" "JavaScript" ".NET" "Java" "Go" >}}
@@ -94,7 +736,7 @@ Order-processor output:
== APP == INFO:root:Deleting Order: {'orderId': '4'}
```
-#### `statestore.yaml` component file
+##### `statestore.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
@@ -216,7 +858,7 @@ Order-processor output:
== APP == Deleting Order: { orderId: 5 }
```
-#### `statestore.yaml` component file
+##### `statestore.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
@@ -333,7 +975,7 @@ Order-processor output:
== APP == Deleting Order: Order { orderId = 5 }
```
-#### `statestore.yaml` component file
+##### `statestore.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
@@ -455,7 +1097,7 @@ Order-processor output:
== APP == INFO:root:Deleting Order: {'orderId': '4'}
```
-#### `statestore.yaml` component file
+##### `statestore.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
@@ -573,7 +1215,7 @@ Order-processor output:
== APP == 2022/04/01 09:16:03 Deleting Order: {"orderId":5}
```
-#### `statestore.yaml` component file
+##### `statestore.yaml` component file
When you run `dapr init`, Dapr creates a default Redis `statestore.yaml` and runs a Redis container on your local machine, located:
diff --git a/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md b/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md
index d139561cb04..0a1f2e77900 100644
--- a/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md
+++ b/daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md
@@ -7,10 +7,10 @@ description: Get started with the Dapr Workflow building block
---
{{% alert title="Note" color="primary" %}}
-The workflow building block is currently in **alpha**.
+Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-version cli="true" %}}]({{< ref "workflow-overview.md#limitations" >}}).
{{% /alert %}}
-Let's take a look at the Dapr [Workflow building block]({{< ref workflow >}}). In this Quickstart, you'll create a simple console application to demonstrate Dapr's workflow programming model and the workflow management APIs.
+Let's take a look at the Dapr [Workflow building block]({{< ref workflow-overview.md >}}). In this Quickstart, you'll create a simple console application to demonstrate Dapr's workflow programming model and the workflow management APIs.
In this guide, you'll:
@@ -21,7 +21,251 @@ In this guide, you'll:
[}})| v1.9 |
-| **Multi-App Run** | Configure multiple Dapr applications from a single configuration file and run from a single command | `dapr run -f` | [Multi-App Run]({{< ref multi-app-dapr-run.md >}}) | v1.10 |
+| **Multi-App Run for Kubernetes** | Configure multiple Dapr applications from a single configuration file and run from a single command on Kubernetes | `dapr run -k -f` | [Multi-App Run]({{< ref multi-app-dapr-run.md >}}) | v1.12 |
| **Workflows** | Author workflows as code to automate and orchestrate tasks within your application, like messaging, state management, and failure handling | N/A | [Workflows concept]({{< ref "components-concept#workflows" >}})| v1.10 |
| **Cryptography** | Encrypt or decrypt data without having to manage secrets keys | N/A | [Cryptography concept]({{< ref "components-concept#cryptography" >}})| v1.11 |
| **Service invocation for non-Dapr endpoints** | Allow the invocation of non-Dapr endpoints by Dapr using the [Service invocation API]({{< ref service_invocation_api.md >}}). Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. | N/A | [Service invocation API]({{< ref service_invocation_api.md >}}) | v1.11 |
| **Actor State TTL** | Allow actors to save records to state stores with Time To Live (TTL) set to automatically clean up old data. In its current implementation, actor state with TTL may not be reflected correctly by clients, read [Actor State Transactions]({{< ref actors_api.md >}}) for more information. | `ActorStateTTL` | [Actor State Transactions]({{< ref actors_api.md >}}) | v1.11 |
+| **Transactional Outbox** | Allows state operations for inserts and updates to be published to a configured pub/sub topic using a single transaction across the state store and the pub/sub | N/A | [Transactional Outbox Feature]({{< ref howto-outbox.md >}}) | v1.12 |
-### Streaming for HTTP service invocation
-
-Running Dapr with the `ServiceInvocationStreaming` feature flag enables partial support for handling data as a stream in HTTP service invocation. This can offer improvements in performance and memory utilization when using Dapr to invoke another service using HTTP with large request or response bodies.
-
-The table below summarizes the current state of support for streaming in HTTP service invocation in Dapr, including the impact of enabling `ServiceInvocationStreaming`, in the example where "app A" is invoking "app B" using Dapr. There are six steps in the data flow, with various levels of support for handling data as a stream:
-
-]❌ | ❌ |
-| 2 | Request: "Dapr sidecar A" to "Dapr sidecar B | ❌ | ✅ |
-| 3 | Request: "Dapr sidecar B" to "App B" | ✅ | ✅ |
-| 4 | Response: "App B" to "Dapr sidecar B" | ✅ | ✅ |
-| 5 | Response: "Dapr sidecar B" to "Dapr sidecar A | ❌ | ✅ |
-| 6 | Response: "Dapr sidecar A" to "App A | ❌ | ❌ |
-
-Important notes:
-
-- `ServiceInvocationStreaming` needs to be applied on caller sidecars only.
- In the example above, streams are used for HTTP service invocation if `ServiceInvocationStreaming` is applied to the configuration of "app A" and its Dapr sidecar, regardless of whether the feature flag is enabled for "app B" and its sidecar.
-- When `ServiceInvocationStreaming` is enabled, you should make sure that all services your app invokes using Dapr ("app B") are updated to Dapr 1.10 or higher, even if `ServiceInvocationStreaming` is not enabled for those sidecars.
- Invoking an app using Dapr 1.9 or older is still possible, but those calls may fail unless you have applied a Dapr Resiliency policy with retries enabled.
-
-> Full support for streaming for HTTP service invocation will be completed in a future Dapr version.
diff --git a/daprdocs/content/en/operations/support/support-release-policy.md b/daprdocs/content/en/operations/support/support-release-policy.md
index 915042374eb..8dd71a45723 100644
--- a/daprdocs/content/en/operations/support/support-release-policy.md
+++ b/daprdocs/content/en/operations/support/support-release-policy.md
@@ -45,10 +45,11 @@ The table below shows the versions of Dapr releases that have been tested togeth
| Release date | Runtime | CLI | SDKs | Dashboard | Status | Release notes |
|--------------------|:--------:|:--------|---------|---------|---------|------------|
-| August 31st 2023 | 1.11.3 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported (current) | [v1.11.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.3) |
-| July 20th 2023 | 1.11.2 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported (current) | [v1.11.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.2) |
-| June 22nd 2023 | 1.11.1 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported (current) | [v1.11.1 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.1) |
-| June 12th 2023 | 1.11.0 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported (current) | [v1.11.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.0) |
+| October 11th 2023 | 1.12.0 | 1.12.0 | Java 1.10.0 Go 1.9.0 PHP 1.1.0 Python 1.11.0 .NET 1.12.0 JS 3.1.2 | 0.13.0 | Supported (current) | [v1.12.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.12.0) |
+| August 31st 2023 | 1.11.3 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported | [v1.11.3 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.3) |
+| July 20th 2023 | 1.11.2 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported | [v1.11.2 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.2) |
+| June 22nd 2023 | 1.11.1 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported | [v1.11.1 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.1) |
+| June 12th 2023 | 1.11.0 | 1.11.0 | Java 1.9.0 Go 1.8.0 PHP 1.1.0 Python 1.10.0 .NET 1.11.0 JS 3.1.0 | 0.13.0 | Supported | [v1.11.0 release notes](https://github.com/dapr/dapr/releases/tag/v1.11.0) |
| July 20th 2023 | 1.10.9 | 1.10.0 | Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0 | 0.11.0 | Supported | [v1.10.9 release notes](https://github.com/dapr/dapr/releases/tag/v1.10.9) |
| June 22nd 2023 | 1.10.8 | 1.10.0 | Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0 | 0.11.0 | Supported | [v1.10.8 release notes](https://github.com/dapr/dapr/releases/tag/v1.10.8) |
| May 15th 2023 | 1.10.7 | 1.10.0 | Java 1.8.0 Go 1.7.0 PHP 1.1.0 Python 1.9.0 .NET 1.10.0 JS 3.0.0 | 0.11.0 | Supported | |
@@ -81,16 +82,6 @@ The table below shows the versions of Dapr releases that have been tested togeth
| Apr 20th 2022 | 1.6.2 | 1.6.0 | Java 1.4.0 Go 1.3.1 PHP 1.1.0 Python 1.5.0 .NET 1.6.0 JS 2.0.0 | 0.9.0 | Unsupported | |
| Mar 25th 2022 | 1.6.1 | 1.6.0 | Java 1.4.0 Go 1.3.1 PHP 1.1.0 Python 1.5.0 .NET 1.6.0 JS 2.0.0 | 0.9.0 | Unsupported | |
| Jan 25th 2022 | 1.6.0 | 1.6.0 | Java 1.4.0 Go 1.3.1 PHP 1.1.0 Python 1.5.0 .NET 1.6.0 JS 2.0.0 | 0.9.0 | Unsupported | |
-| Mar 25th 2022 | 1.5.2 | 1.6.0 | Java 1.3.0 Go 1.3.0 PHP 1.1.0 Python 1.4.0 .NET 1.5.0 JS 1.0.2 | 0.9.0 | Unsupported | |
-| Dec 6th 2021 | 1.5.1 | 1.5.1 | Java 1.3.0 Go 1.3.0 PHP 1.1.0 Python 1.4.0 .NET 1.5.0 JS 1.0.2 | 0.9.0 | Unsupported | |
-| Nov 11th 2021 | 1.5.0 | 1.5.0 | Java 1.3.0 Go 1.3.0 PHP 1.1.0 Python 1.4.0 .NET 1.5.0 JS 1.0.2 | 0.9.0 | Unsupported | |
-| Dev 6th 2021 | 1.4.4 | 1.4.0 | Java 1.3.0 Go 1.2.0 PHP 1.1.0 Python 1.3.0 .NET 1.4.0 | 0.8.0 | Unsupported | |
-| Oct 7th 2021 | 1.4.3 | 1.4.0 | Java 1.3.0 Go 1.2.0 PHP 1.1.0 Python 1.3.0 .NET 1.4.0 | 0.8.0 | Unsupported | |
-| Sep 24th 2021 | 1.4.2 | 1.4.0 | Java 1.3.0 Go 1.2.0 PHP 1.1.0 Python 1.3.0 .NET 1.4.0 | 0.8.0 | Unsupported | |
-| Sep 22nd 2021 | 1.4.1 | 1.4.0 | Java 1.3.0 Go 1.2.0 PHP 1.1.0 Python 1.3.0 .NET 1.4.0 | 0.8.0 | Unsupported | |
-| Sep 15th 2021 | 1.4 | 1.4.0 | Java 1.3.0 Go 1.2.0 PHP 1.1.0 Python 1.3.0 .NET 1.4.0 | 0.8.0 | Unsupported | |
-| Sep 14th 2021 | 1.3.1 | 1.3.0 | Java 1.2.0 Go 1.2.0 PHP 1.1.0 Python 1.2.0 .NET 1.3.0 | 0.7.0 | Unsupported | |
-| Jul 26th 2021 | 1.3 | 1.3.0 | Java 1.2.0 Go 1.2.0 PHP 1.1.0 Python 1.2.0 .NET 1.3.0 | 0.7.0 | Unsupported | |
## Upgrade paths
@@ -122,7 +113,8 @@ General guidance on upgrading can be found for [self hosted mode]({{< ref self-h
| 1.8.0 to 1.8.6 | N/A | 1.9.6 |
| 1.9.0 | N/A | 1.9.6 |
| 1.10.0 | N/A | 1.10.8 |
-| 1.11.0 | N/A | 1.11.3 |
+| 1.11.0 | N/A | 1.11.4 |
+| 1.12.0 | N/A | 1.12.0 |
## Upgrade on Hosting platforms
diff --git a/daprdocs/content/en/reference/api/error_codes.md b/daprdocs/content/en/reference/api/error_codes.md
index d93bc0f1188..7de8c0a2c3c 100644
--- a/daprdocs/content/en/reference/api/error_codes.md
+++ b/daprdocs/content/en/reference/api/error_codes.md
@@ -3,7 +3,7 @@ type: docs
title: "Error codes returned by APIs"
linkTitle: "Error codes"
description: "Detailed reference of the Dapr API error codes"
-weight: 1200
+weight: 1300
---
For http calls made to Dapr runtime, when an error is encountered, an error json is returned in http response body. The json contains an error code and an descriptive error message, e.g.
diff --git a/daprdocs/content/en/reference/api/placement_api.md b/daprdocs/content/en/reference/api/placement_api.md
new file mode 100644
index 00000000000..a882eb8618e
--- /dev/null
+++ b/daprdocs/content/en/reference/api/placement_api.md
@@ -0,0 +1,79 @@
+---
+type: docs
+title: "Placement API reference"
+linkTitle: "Placement API"
+description: "Detailed documentation on the Placement API"
+weight: 1200
+---
+
+Dapr has an HTTP API `/placement/state` for placement service that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default.
+
+To enable the placement metadata in self-hosted mode you can either set`DAPR_PLACEMENT_METADATA_ENABLED` environment variable or `metadata-enabled` command line args on the Placement service to `true` to. See [how to run the Placement service in self-hosted mode]({{< ref "self-hosted-no-docker.md#enable-actors" >}}).
+
+If you are using Helm for deployment of the Placement service on Kubernetes then to enable the placement metadata, set `dapr_placement.metadataEnabled` to `true`.
+
+## Usecase
+
+The placement table API can be used for retrieving the current placement table, which contains all the actors registered. This can be helpful for debugging and allows tools to extract and present information about actors.
+
+## HTTP Request
+
+```
+GET http://localhost:/placement/state
+```
+
+## HTTP Response Codes
+
+Code | Description
+---- | -----------
+200 | Placement tables information returned
+500 | Placement could not return the placement tables information
+
+## HTTP Response Body
+
+**Placement tables API Response Object**
+
+Name | Type | Description
+---- | ---- | -----------
+tableVersion | int | The placement table version
+hostList | [Actor Host Info](#actorhostinfo)[] | A json array of registered actors host info.
+
+//start[?instanceID=]
+POST http://localhost:3500/v1.0-beta1/workflows///start[?instanceID=]
```
Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
@@ -53,7 +57,7 @@ The API call will provide a response similar to this:
Terminate a running workflow instance with the given name and instance ID.
```
-POST http://localhost:3500/v1.0-alpha1/workflows///terminate
+POST http://localhost:3500/v1.0-beta1/workflows///terminate
```
### URL parameters
@@ -80,7 +84,7 @@ This API does not return any content.
For workflow components that support subscribing to external events, such as the Dapr Workflow engine, you can use the following "raise event" API to deliver a named event to a specific workflow instance.
```
-POST http://localhost:3500/v1.0-alpha1/workflows///raiseEvent/
+POST http://localhost:3500/v1.0-beta1/workflows///raiseEvent/
```
{{% alert title="Note" color="primary" %}}
@@ -113,7 +117,7 @@ None.
Pause a running workflow instance.
```
-POST http://localhost:3500/v1.0-alpha1/workflows///pause
+POST http://localhost:3500/v1.0-beta1/workflows///pause
```
### URL parameters
@@ -140,7 +144,7 @@ None.
Resume a paused workflow instance.
```
-POST http://localhost:3500/v1.0-alpha1/workflows///resume
+POST http://localhost:3500/v1.0-beta1/workflows///resume
```
### URL parameters
@@ -167,7 +171,7 @@ None.
Purge the workflow state from your state store with the workflow's instance ID.
```
-POST http://localhost:3500/v1.0-alpha1/workflows///purge
+POST http://localhost:3500/v1.0-beta1/workflows///purge
```
### URL parameters
@@ -194,7 +198,7 @@ None.
Get information about a given workflow instance.
```
-GET http://localhost:3500/v1.0-alpha1/workflows//
+GET http://localhost:3500/v1.0-beta1/workflows//
```
### URL parameters
diff --git a/daprdocs/content/en/reference/arguments-annotations-overview.md b/daprdocs/content/en/reference/arguments-annotations-overview.md
index a1c044a68d8..68eab9812c3 100644
--- a/daprdocs/content/en/reference/arguments-annotations-overview.md
+++ b/daprdocs/content/en/reference/arguments-annotations-overview.md
@@ -39,7 +39,7 @@ This table is meant to help users understand the equivalent options for running
| `--profiling-port` | `--profiling-port` | | not supported | The port for the profile server (default `7777`) |
| `--app-protocol` | `--app-protocol` | `-P` | `dapr.io/app-protocol` | Configures the protocol Dapr uses to communicate with your app. Valid options are `http`, `grpc`, `https` (HTTP with TLS), `grpcs` (gRPC with TLS), `h2c` (HTTP/2 Cleartext). Note that Dapr does not validate TLS certificates presented by the app. Default is `http` |
| `--enable-app-health-check` | `--enable-app-health-check` | | `dapr.io/enable-app-health-check` | Boolean that enables the [health checks]({{< ref "app-health.md#configuring-app-health-checks" >}}). Default is `false`. |
-| `--app-health-check-path` | `--app-health-check-path` | | `dapr.io/app-health-check-path` | Path that Dapr invokes for health probes when the app channel is HTTP (this value is ignored if the app channel is using gRPC). Requires [app health checks to be enabled]({{< ref "app-health.md#configuring-app-health-checks" >}}). Default is `/health`. |
+| `--app-health-check-path` | `--app-health-check-path` | | `dapr.io/app-health-check-path` | Path that Dapr invokes for health probes when the app channel is HTTP (this value is ignored if the app channel is using gRPC). Requires [app health checks to be enabled]({{< ref "app-health.md#configuring-app-health-checks" >}}). Default is `/healthz`. |
| `--app-health-probe-interval` | `--app-health-probe-interval` | | `dapr.io/app-health-probe-interval` | Number of *seconds* between each health probe. Requires [app health checks to be enabled]({{< ref "app-health.md#configuring-app-health-checks" >}}). Default is `5` |
| `--app-health-probe-timeout` | `--app-health-probe-timeout` | | `dapr.io/app-health-probe-timeout` | Timeout in *milliseconds* for health probe requests. Requires [app health checks to be enabled]({{< ref "app-health.md#configuring-app-health-checks" >}}). Default is `500` |
| `--app-health-threshold` | `--app-health-threshold` | | `dapr.io/app-health-threshold"` | Max number of consecutive failures before the app is considered unhealthy. Requires [app health checks to be enabled]({{< ref "app-health.md#configuring-app-health-checks" >}}). Default is `3` |
diff --git a/daprdocs/content/en/reference/cli/dapr-init.md b/daprdocs/content/en/reference/cli/dapr-init.md
index a94c3e19a40..bdb93bf5d15 100644
--- a/daprdocs/content/en/reference/cli/dapr-init.md
+++ b/daprdocs/content/en/reference/cli/dapr-init.md
@@ -44,6 +44,9 @@ dapr init [flags]
| N/A | DAPR_HELM_REPO_USERNAME | A username for a private Helm chart | The username required to access the private Dapr Helm chart. If it can be accessed publicly, this env variable does not need to be set|
| N/A | DAPR_HELM_REPO_PASSWORD | A password for a private Helm chart |The password required to access the private Dapr Helm chart. If it can be accessed publicly, this env variable does not need to be set| |
| `--container-runtime` | | `docker` | Used to pass in a different container runtime other than Docker. Supported container runtimes are: `docker`, `podman` |
+| `--dev` | | | Creates Redis and Zipkin deployments when run in Kubernetes. |
+
+
### Examples
#### Self hosted environment
diff --git a/daprdocs/content/en/reference/cli/dapr-run.md b/daprdocs/content/en/reference/cli/dapr-run.md
index 9a519f98c72..b6fed8a8265 100644
--- a/daprdocs/content/en/reference/cli/dapr-run.md
+++ b/daprdocs/content/en/reference/cli/dapr-run.md
@@ -50,6 +50,7 @@ dapr run [flags] [command]
| `--unix-domain-socket`, `-u` | | | Path to a unix domain socket dir mount. If specified, communication with the Dapr sidecar uses unix domain sockets for lower latency and greater throughput when compared to using TCP ports. Not available on Windows. |
| `--dapr-http-max-request-size` | | `4` | Max size of the request body in MB. |
| `--dapr-http-read-buffer-size` | | `4` | Max size of the HTTP read buffer in KB. This also limits the maximum size of HTTP headers. The default 4 KB |
+| `--kubernetes`, `-k` | | | Running Dapr on Kubernetes, and used for [Multi-App Run template files on Kubernetes]({{< ref multi-app-dapr-run >}}). |
| `--components-path`, `-d` | | Linux/Mac: `$HOME/.dapr/components` , or
- - name: MTLSClientCert
- value: "/Users/somepath/client.pem" # OPTIONAL Secret store ref, , or
- - name: MTLSClientKey
- value: "/Users/somepath/client.key" # OPTIONAL Secret store ref, , or
- - name: MTLSRenegotiation
- value: "RenegotiateOnceAsClient" # OPTIONAL one of: RenegotiateNever, RenegotiateOnceAsClient, RenegotiateFreelyAsClient
- - name: securityToken # OPTIONAL
- secretKeyRef:
- name: mysecret
- key: "mytoken"
- - name: securityTokenHeader
- value: "Authorization: Bearer" # OPTIONAL
- - name: direction
- value: "output"
+ - name: url
+ value: "http://something.com"
+ #- name: maxResponseBodySize
+ # value: "100Mi" # OPTIONAL maximum amount of data to read from a response
+ #- name: MTLSRootCA
+ # value: "/Users/somepath/root.pem" # OPTIONAL path to root CA or PEM-encoded string
+ #- name: MTLSClientCert
+ # value: "/Users/somepath/client.pem" # OPTIONAL path to client cert or PEM-encoded string
+ #- name: MTLSClientKey
+ # value: "/Users/somepath/client.key" # OPTIONAL path to client key or PEM-encoded string
+ #- name: MTLSRenegotiation
+ # value: "RenegotiateOnceAsClient" # OPTIONAL one of: RenegotiateNever, RenegotiateOnceAsClient, RenegotiateFreelyAsClient
+ #- name: securityToken # OPTIONAL
+ # secretKeyRef:
+ # name: mysecret
+ # key: "mytoken"
+ #- name: securityTokenHeader
+ # value: "Authorization: Bearer" # OPTIONAL
+ #- name: direction
+ # value: "output"
```
## Spec metadata fields
| Field | Required | Binding support | Details | Example |
|--------------------|:--------:|--------|--------|---------|
-| `url` | Y | Output |The base URL of the HTTP endpoint to invoke | `http://host:port/path`, `http://myservice:8000/customers`
-| `MTLSRootCA` | N | Output |Secret store reference, path to root ca certificate, or pem encoded string |
-| `MTLSClientCert` | N | Output |Secret store reference, path to client certificate, or pem encoded string |
-| `MTLSClientKey` | N | Output |Secret store reference, path client private key, or pem encoded string |
-| `MTLSRenegotiation` | N | Output |Type of TLS renegotiation to be used | `RenegotiateOnceAsClient`
-| `securityToken` | N | Output |The value of a token to be added to an HTTP request as a header. Used together with `securityTokenHeader` |
-| `securityTokenHeader`| N | Output |The name of the header for `securityToken` on an HTTP request that |
-| `direction`| N | Output |The direction of the binding | `"output"`
-
-### How to configure MTLS related fields in Metadata
+| `url` | Y | Output | The base URL of the HTTP endpoint to invoke | `http://host:port/path`, `http://myservice:8000/customers` |
+| `maxResponseBodySize`| N | Output | Maximum length of the response to read. A whole number is interpreted as bytes; units such as `Ki, Mi, Gi` (SI) or `k | M | G` (decimal) can be added for convenience. The default value is `100Mi` | "1Gi", "100Mi", "20Ki", "200" (bytes) |
+| `MTLSRootCA` | N | Output | Path to root CA certificate or PEM-encoded string |
+| `MTLSClientCert` | N | Output | Path to client certificate or PEM-encoded string |
+| `MTLSClientKey` | N | Output | Path client private key or PEM-encoded string |
+| `MTLSRenegotiation` | N | Output | Type of mTLS renegotiation to be used | `RenegotiateOnceAsClient`
+| `securityToken` | N | Output | The value of a token to be added to a HTTP request as a header. Used together with `securityTokenHeader` |
+| `securityTokenHeader` | N | Output | The name of the header for `securityToken` on a HTTP request |
+| `direction` | N | Output |The direction of the binding | `"output"`
+
+### How to configure mTLS-related fields in metadata
+
The values for **MTLSRootCA**, **MTLSClientCert** and **MTLSClientKey** can be provided in three ways:
-1. Secret store reference
-```yaml
-apiVersion: dapr.io/v1alpha1
-kind: Component
-metadata:
- name:
-spec:
- type: bindings.http
- version: v1
- metadata:
- - name: url
- value: http://something.com
- - name: MTLSRootCA
- secretKeyRef:
- name: mysecret
- key: myrootca
-auth:
- secretStore:
-```
-2. Path to the file: The absolute path to the file can be provided as a value for the field.
-3. PEM encoded string: The PEM encoded string can also be provided as a value for the field.
+
+- Secret store reference:
+
+ ```yaml
+ apiVersion: dapr.io/v1alpha1
+ kind: Component
+ metadata:
+ name:
+ spec:
+ type: bindings.http
+ version: v1
+ metadata:
+ - name: url
+ value: http://something.com
+ - name: MTLSRootCA
+ secretKeyRef:
+ name: mysecret
+ key: myrootca
+ auth:
+ secretStore:
+ ```
+
+- Path to the file: the absolute path to the file can be provided as a value for the field.
+- PEM encoded string: the PEM-encoded string can also be provided as a value for the field.
{{% alert title="Note" color="primary" %}}
-Metadata fields **MTLSRootCA**, **MTLSClientCert** and **MTLSClientKey** are used to configure TLS(m) authentication.
-To use mTLS authentication, you must provide all three fields. See [mTLS]({{< ref "#using-mtls-or-enabling-client-tls-authentication-along-with-https" >}}) for more details. You can also provide only **MTLSRootCA**, to enable **HTTPS** connection. See [HTTPS]({{< ref "#install-the-ssl-certificate-in-the-sidecar" >}}) section for more details.
+Metadata fields **MTLSRootCA**, **MTLSClientCert** and **MTLSClientKey** are used to configure (m)TLS authentication.
+To use mTLS authentication, you must provide all three fields. See [mTLS]({{< ref "#using-mtls-or-enabling-client-tls-authentication-along-with-https" >}}) for more details. You can also provide only **MTLSRootCA**, to enable **HTTPS** connection with a certificate signed by a custom CA. See [HTTPS]({{< ref "#install-the-ssl-certificate-in-the-sidecar" >}}) section for more details.
{{% /alert %}}
@@ -107,8 +114,8 @@ All of the operations above support the following metadata fields
| Field | Required | Details | Example |
|--------------------|:--------:|---------|---------|
-| path | N | The path to append to the base URL. Used for accessing specific URIs | `"/1234"`, `"/search?lastName=Jones"`
-| Headers* | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"`, `"Accept"`
+| `path` | N | The path to append to the base URL. Used for accessing specific URIs. | `"/1234"`, `"/search?lastName=Jones"`
+| Field with a capitalized first letter | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"`, `"Accept"`
#### Retrieving data
@@ -137,9 +144,9 @@ The response body contains the data returned by the HTTP endpoint. The `data` f
| Field | Required | Details | Example |
|--------------------|:--------:|---------|---------|
-| statusCode | Y | The [HTTP status code](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) | `200`, `404`, `503`
-| status | Y | The status description | `"200 OK"`, `"201 Created"`
-| Headers* | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"`
+| `statusCode` | Y | The [HTTP status code](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) | `200`, `404`, `503` |
+| `status` | Y | The status description | `"200 OK"`, `"201 Created"` |
+| Field with a capitalized first letter | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"` |
#### Example
@@ -168,14 +175,14 @@ curl -d '{ "operation": "get" }' \
{{< tabs Windows Linux >}}
{{% codetab %}}
-```bash
+```sh
curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \
http://localhost:/v1.0/bindings/
```
{{% /codetab %}}
{{% codetab %}}
-```bash
+```sh
curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
http://localhost:/v1.0/bindings/
```
@@ -210,14 +217,14 @@ For example, the default content type is `application/json; charset=utf-8`. This
{{< tabs Windows Linux >}}
{{% codetab %}}
-```bash
+```sh
curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
http://localhost:/v1.0/bindings/
```
{{% /codetab %}}
{{% codetab %}}
-```bash
+```sh
curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
http://localhost:/v1.0/bindings/
```
@@ -229,9 +236,8 @@ curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "p
The HTTP binding can also be used with HTTPS endpoints by configuring the Dapr sidecar to trust the server's SSL certificate.
-
1. Update the binding URL to use `https` instead of `http`.
-1. Refer [How-To: Install certificates in the Dapr sidecar]({{< ref install-certificates >}}), to install the SSL certificate in the sidecar.
+1. If you need to add a custom TLS certificate, refer [How-To: Install certificates in the Dapr sidecar]({{< ref install-certificates >}}), to install the TLS certificates in the sidecar.
### Example
@@ -251,13 +257,12 @@ spec:
value: https://my-secured-website.com # Use HTTPS
```
-#### Install the SSL certificate in the sidecar
-
+#### Install the TLS certificate in the sidecar
{{< tabs Self-Hosted Kubernetes >}}
{{% codetab %}}
-When the sidecar is not running inside a container, the SSL certificate can be directly installed on the host operating system.
+When the sidecar is not running inside a container, the TLS certificate can be directly installed on the host operating system.
Below is an example when the sidecar is running as a container. The SSL certificate is located on the host computer at `/tmp/ssl/cert.pem`.
@@ -286,7 +291,7 @@ services:
{{% codetab %}}
-The sidecar can read the SSL certificate from a variety of sources. See [How-to: Mount Pod volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts >}}) for more. In this example, we store the SSL certificate as a Kubernetes secret.
+The sidecar can read the TLS certificate from a variety of sources. See [How-to: Mount Pod volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts >}}) for more. In this example, we store the TLS certificate as a Kubernetes secret.
```bash
kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem
@@ -354,24 +359,26 @@ HTTPS binding support can also be configured using the **MTLSRootCA** metadata o
{{% /alert %}}
## Using mTLS or enabling client TLS authentication along with HTTPS
+
You can configure the HTTP binding to use mTLS or client TLS authentication along with HTTPS by providing the `MTLSRootCA`, `MTLSClientCert`, and `MTLSClientKey` metadata fields in the binding component.
-These fields can be passed as a file path or as a pem encoded string.
+These fields can be passed as a file path or as a pem encoded string:
+
- If the file path is provided, the file is read and the contents are used.
-- If the pem encoded string is provided, the string is used as is.
+- If the PEM-encoded string is provided, the string is used as is.
+
When these fields are configured, the Dapr sidecar uses the provided certificate to authenticate itself with the server during the TLS handshake process.
-If the remote server is enforcing TLS renegotiation, you also need to set the metadata field `MTLSRenegotiation`. This field accepts one of following options:
+If the remote server is enforcing TLS renegotiation, you also need to set the metadata field `MTLSRenegotiation`. This field accepts one of following options:
+
- `RenegotiateNever`
- `RenegotiateOnceAsClient`
-- `RenegotiateFreelyAsClient`.
+- `RenegotiateFreelyAsClient`
For more details see [the Go `RenegotiationSupport` documentation](https://pkg.go.dev/crypto/tls#RenegotiationSupport).
-### When to use:
You can use this when the server with which the HTTP binding is configured to communicate requires mTLS or client TLS authentication.
-
## Related links
- [Basic schema for a Dapr component]({{< ref component-schema >}})
diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/kafka.md b/daprdocs/content/en/reference/components-reference/supported-bindings/kafka.md
index 38afe3c503a..7029b546bd8 100644
--- a/daprdocs/content/en/reference/components-reference/supported-bindings/kafka.md
+++ b/daprdocs/content/en/reference/components-reference/supported-bindings/kafka.md
@@ -74,6 +74,7 @@ spec:
| `oidcScopes` | N | Input/Output | Comma-delimited list of OAuth2/OIDC scopes to request with the access token. Recommended when `authType` is set to `oidc`. Defaults to `"openid"` | `"openid,kafka-prod"` |
| `version` | N | Input/Output | Kafka cluster version. Defaults to 2.0.0. Please note that this needs to be mandatorily set to `1.0.0` for EventHubs with Kafka. | `"1.0.0"` |
| `direction` | N | Input/Output | The direction of the binding. | `"input"`, `"output"`, `"input, output"` |
+| `oidcExtensions` | N | Input/Output | String containing a JSON-encoded dictionary of OAuth2/OIDC extensions to request with the access token | `{"cluster":"kafka","poolid":"kafkapool"}` |
#### Note
The metadata `version` must be set to `1.0.0` when using Azure EventHubs with Kafka.
diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/kubernetes-binding.md b/daprdocs/content/en/reference/components-reference/supported-bindings/kubernetes-binding.md
index 25391a7748d..ee6389e0009 100644
--- a/daprdocs/content/en/reference/components-reference/supported-bindings/kubernetes-binding.md
+++ b/daprdocs/content/en/reference/components-reference/supported-bindings/kubernetes-binding.md
@@ -36,6 +36,7 @@ spec:
| `namespace` | Y | Input | The Kubernetes namespace to read events from | `"default"` |
| `resyncPeriodInSec` | N | Input | The period of time to refresh event list from Kubernetes API server. Defaults to `"10"` | `"15"`
| `direction` | N | Input | The direction of the binding | `"input"`
+| `kubeconfigPath` | N | Input | The path to the kubeconfig file. If not specified, the binding uses the default in-cluster config value | `"/path/to/kubeconfig"`
## Binding support
diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/mysql.md b/daprdocs/content/en/reference/components-reference/supported-bindings/mysql.md
index d03dcfcab89..3c44b53a84c 100644
--- a/daprdocs/content/en/reference/components-reference/supported-bindings/mysql.md
+++ b/daprdocs/content/en/reference/components-reference/supported-bindings/mysql.md
@@ -60,16 +60,23 @@ Note that you can not use secret just for username/password. If you use secret,
### SSL connection
If your server requires SSL your connection string must end of `&tls=custom` for example:
+
```bash
":@tcp(:3306)/?allowNativePasswords=true&tls=custom"
```
- You must replace the `` with a full path to the PEM file. If you are using [MySQL on Azure](http://bit.ly/AzureMySQLSSL) see the Azure [documentation on SSL database connections](http://bit.ly/MySQLSSL), for information on how to download the required certificate. The connection to MySQL will require a minimum TLS version of 1.2.
-Also note that by default [MySQL go driver](https://github.com/go-sql-driver/mysql) only supports one SQL statement per query/command.
+> You must replace the `` with a full path to the PEM file. If you are using Azure Database for MySQL see the Azure [documentation on SSL database connections](https://learn.microsoft.com/azure/mysql/single-server/how-to-configure-ssl), for information on how to download the required certificate. The connection to MySQL requires a minimum TLS version of 1.2.
+
+### Multiple statements
+
+By default, the [MySQL Go driver](https://github.com/go-sql-driver/mysql) only supports one SQL statement per query/command.
+
To allow multiple statements in one query you need to add `multiStatements=true` to a query string, for example:
+
```bash
":@tcp(:3306)/?multiStatements=true"
```
+
While this allows batch queries, it also greatly increases the risk of SQL injections. Only the result of the first query is returned,
all other results are silently discarded.
@@ -81,17 +88,35 @@ This component supports **output binding** with the following operations:
- `query`
- `close`
+### Parametrized queries
+
+This binding supports parametrized queries, which allow separating the SQL query itself from user-supplied values. The usage of parametrized queries is **strongly recommended** for security reasons, as they prevent [SQL Injection attacks](https://owasp.org/www-community/attacks/SQL_Injection).
+
+For example:
+
+```sql
+-- ❌ WRONG! Includes values in the query and is vulnerable to SQL Injection attacks.
+SELECT * FROM mytable WHERE user_key = 'something';
+
+-- ✅ GOOD! Uses parametrized queries.
+-- This will be executed with parameters ["something"]
+SELECT * FROM mytable WHERE user_key = ?;
+```
+
### exec
The `exec` operation can be used for DDL operations (like table creation), as well as `INSERT`, `UPDATE`, `DELETE` operations which return only metadata (e.g. number of affected rows).
+The `params` property is a string containing a JSON-encoded array of parameters.
+
**Request**
```json
{
"operation": "exec",
"metadata": {
- "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
+ "sql": "INSERT INTO foo (id, c1, ts) VALUES (?, ?, ?)",
+ "params": "[1, \"demo\", \"2020-09-24T11:45:05Z07:00\"]"
}
}
```
@@ -106,7 +131,7 @@ The `exec` operation can be used for DDL operations (like table creation), as we
"start-time": "2020-09-24T11:13:46.405097Z",
"end-time": "2020-09-24T11:13:46.414519Z",
"rows-affected": "1",
- "sql": "INSERT INTO foo (id, c1, ts) VALUES (1, 'demo', '2020-09-24T11:45:05Z07:00')"
+ "sql": "INSERT INTO foo (id, c1, ts) VALUES (?, ?, ?)"
}
}
```
@@ -115,13 +140,16 @@ The `exec` operation can be used for DDL operations (like table creation), as we
The `query` operation is used for `SELECT` statements, which returns the metadata along with data in a form of an array of row values.
+The `params` property is a string containing a JSON-encoded array of parameters.
+
**Request**
```json
{
"operation": "query",
"metadata": {
- "sql": "SELECT * FROM foo WHERE id < 3"
+ "sql": "SELECT * FROM foo WHERE id < $1",
+ "params": "[3]"
}
}
```
@@ -135,7 +163,7 @@ The `query` operation is used for `SELECT` statements, which returns the metadat
"duration": "432µs",
"start-time": "2020-09-24T11:13:46.405097Z",
"end-time": "2020-09-24T11:13:46.420566Z",
- "sql": "SELECT * FROM foo WHERE id < 3"
+ "sql": "SELECT * FROM foo WHERE id < ?"
},
"data": [
{column_name: value, column_name: value, ...},
@@ -150,7 +178,7 @@ or numbers (language specific data type)
### close
-Finally, the `close` operation can be used to explicitly close the DB connection and return it to the pool. This operation doesn't have any response.
+The `close` operation can be used to explicitly close the DB connection and return it to the pool. This operation doesn't have any response.
**Request**
@@ -160,8 +188,6 @@ Finally, the `close` operation can be used to explicitly close the DB connection
}
```
-> Note, the MySQL binding itself doesn't prevent SQL injection, like with any database application, validate the input before executing query.
-
## Related links
- [Basic schema for a Dapr component]({{< ref component-schema >}})
diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/postgresql.md b/daprdocs/content/en/reference/components-reference/supported-bindings/postgresql.md
index 31c9f230cff..cfaf92ad37c 100644
--- a/daprdocs/content/en/reference/components-reference/supported-bindings/postgresql.md
+++ b/daprdocs/content/en/reference/components-reference/supported-bindings/postgresql.md
@@ -22,10 +22,11 @@ spec:
type: bindings.postgresql
version: v1
metadata:
- - name: url # Required
- value: ""
- - name: direction
- value: ""
+ # Connection string
+ - name: connectionString
+ value: ""
+ - name: direction
+ value: ""
```
{{% alert title="Warning" color="warning" %}}
@@ -34,25 +35,48 @@ The above example uses secrets as plain strings. It is recommended to use a secr
## Spec metadata fields
-| Field | Required | Binding support | Details | Example |
-|--------------------|:--------:|------------|-----|---------|
-| `url` | Y | Output | PostgreSQL connection string See [here](#url-format) for more details | `"user=dapr password=secret host=dapr.example.com port=5432 dbname=dapr sslmode=verify-ca"` |
-| `direction` | N | Output | The direction of the binding | `"output"` |
+### Authenticate using a connection string
+
+The following metadata options are **required** to authenticate using a PostgreSQL connection string.
+
+| Field | Required | Details | Example |
+|--------|:--------:|---------|---------|
+| `connectionString` | Y | The connection string for the PostgreSQL database. See the PostgreSQL [documentation on database connections](https://www.postgresql.org/docs/current/libpq-connect.html) for information on how to define a connection string. | `"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=my_db"`
+
+### Authenticate using Azure AD
+
+Authenticating with Azure AD is supported with Azure Database for PostgreSQL. All authentication methods supported by Dapr can be used, including client credentials ("service principal") and Managed Identity.
+
+| Field | Required | Details | Example |
+|--------|:--------:|---------|---------|
+| `useAzureAD` | Y | Must be set to `true` to enable the component to retrieve access tokens from Azure AD. | `"true"` |
+| `connectionString` | Y | The connection string for the PostgreSQL database.:/configuration/mypostgresql/subscribe?key=&key=&metadata.pgNotifyChannel='
+Example of subscribe HTTP API:
+
+```sh
+curl -l 'http://:/configuration/mypostgresql/subscribe?key=&key=&metadata.pgNotifyChannel='
```
{{% /alert %}}
## Related links
+
- [Basic schema for a Dapr component]({{< ref component-schema >}})
- [Configuration building block]({{< ref configuration-api-overview >}})
diff --git a/daprdocs/content/en/reference/components-reference/supported-cryptography/kubernetes-secrets.md b/daprdocs/content/en/reference/components-reference/supported-cryptography/kubernetes-secrets.md
index 2e0ebc6f742..0471bd2c143 100644
--- a/daprdocs/content/en/reference/components-reference/supported-cryptography/kubernetes-secrets.md
+++ b/daprdocs/content/en/reference/components-reference/supported-cryptography/kubernetes-secrets.md
@@ -33,7 +33,11 @@ The above example uses secrets as plain strings. It is recommended to use a secr
## Spec metadata fields
-For the Kubernetes secret store component, there are no metadata attributes.
+| Field | Required | Details | Example |
+|--------------------|:--------:|------------|-----|---------|
+| `defaultNamespace` | N | Default namespace to retrieve secrets from. If unset, the namespace must be specified for each key, as `namespace/secretName/key` | `"default-ns"` |
+| `kubeconfigPath` | N | The path to the kubeconfig file. If not specified, the component uses the default in-cluster config value | `"/path/to/kubeconfig"`
+
## Related links
[Cryptography building block]({{< ref cryptography >}})
\ No newline at end of file
diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-routeralias.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-routeralias.md
index 5b125be48f7..62d3083cf8d 100644
--- a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-routeralias.md
+++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-routeralias.md
@@ -7,12 +7,10 @@ aliases:
- /developing-applications/middleware/supported-middleware/middleware-routeralias/
---
-The router alias HTTP [middleware]({{< ref middleware.md >}}) component allows you to convert arbitrary HTTP routes arriving to Dapr to valid Dapr API endpoints.
+The router alias HTTP [middleware]({{< ref middleware.md >}}) component allows you to convert arbitrary HTTP routes arriving into Dapr to valid Dapr API endpoints.
## Component format
-The router alias middleware metadata contains name/value pairs, where the name describes the HTTP route to expect, and the value describes the corresponding Dapr API the request should be sent to.
-
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
@@ -22,17 +20,24 @@ spec:
type: middleware.http.routeralias
version: v1
metadata:
- - name: "/v1.0/mall/activity/info"
- value: "/v1.0/invoke/srv.default/method/mall/activity/info"
- - name: "/v1.0/hello/activity/{id}/info"
- value: "/v1.0/invoke/srv.default/method/hello/activity/info"
- - name: "/v1.0/hello/activity/{id}/user"
- value: "/v1.0/invoke/srv.default/method/hello/activity/user"
+ # String containing a JSON-encoded or YAML-encoded dictionary
+ # Each key in the dictionary is the incoming path, and the value is the path it's converted to
+ - name: "routes"
+ value: |
+ {
+ "/mall/activity/info": "/v1.0/invoke/srv.default/method/mall/activity/info",
+ "/hello/activity/{id}/info": "/v1.0/invoke/srv.default/method/hello/activity/info",
+ "/hello/activity/{id}/user": "/v1.0/invoke/srv.default/method/hello/activity/user"
+ }
```
-Example:
+In the example above, an incoming HTTP request for `/mall/activity/info?id=123` is transformed into `/v1.0/invoke/srv.default/method/mall/activity/info?id=123`.
+
+# Spec metadata fields
-An incoming HTTP request for `/v1.0/mall/activity/info?id=123` is transformed into `/v1.0/invoke/srv.default/method/mall/activity/info?id=123`.
+| Field | Details | Example |
+|-------|---------|---------|
+| `routes` | String containing a JSON-encoded or YAML-encoded dictionary. Each key in the dictionary is the incoming path, and the value is the path it's converted to. | See example above |
## Dapr configuration
diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md
index 15f22643ff2..0f36aaacf2a 100644
--- a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md
+++ b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md
@@ -7,7 +7,22 @@ description: Detailed information on the Kubernetes DNS name resolution componen
## Configuration format
-Kubernetes DNS name resolution is configured automatically in [Kubernetes mode]({{< ref kubernetes >}}) by Dapr. There is no configuration needed to use Kubernetes DNS as your name resolution provider.
+Generally, Kubernetes DNS name resolution is configured automatically in [Kubernetes mode]({{< ref kubernetes >}}) by Dapr. There is no configuration needed to use Kubernetes DNS as your name resolution provider unless some overrides are necessary for the Kubernetes name resolution component.
+
+In the scenario that an override is required, within a [Dapr Configuration]({{< ref configuration-overview.md >}}) CRD, add a `nameResolution` spec and set the `component` field to `"kubernetes"`. The other configuration fields can be set as needed in a `configuration` map, as seen below.
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+ name: appconfig
+spec:
+ nameResolution:
+ component: "kubernetes"
+ configuration:
+ clusterDomain: "cluster.local" # Mutually exclusive with the template field
+ template: "{{.ID}}-{{.Data.region}}.internal:{{.Port}}" # Mutually exclusive with the clusterDomain field
+```
## Behaviour
@@ -15,7 +30,13 @@ The component resolves target apps by using the Kubernetes cluster's DNS provide
## Spec configuration fields
-Not applicable, as Kubernetes DNS is configured by Dapr when running in Kubernetes mode.
+The configuration spec is fixed to v1.3.0 of the Consul API
+
+| Field | Required | Type | Details | Examples |
+|--------------|:--------:|-----:|:---------|----------|
+| clusterDomain | N | `string` | The cluster domain to be used for resolved addresses. This field is mutually exclusive with the `template` file.| `cluster.local`
+| template | N | `string` | A template string to be parsed when addresses are resolved using [text/template](https://pkg.go.dev/text/template#Template) . The template will be populated by the fields in the [ResolveRequest](https://github.com/dapr/components-contrib/blob/release-{{% dapr-latest-version short="true" %}}/nameresolution/requests.go#L20) struct. This field is mutually exclusive with `clusterDomain` field. | `{{.ID}}-{{.Data.region}}.{{.Namespace}}.internal:{{.Port}}`
+
## Related links
diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md
index 48e2876c2d1..431a7bc5406 100644
--- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md
+++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md
@@ -80,6 +80,7 @@ spec:
| oidcClientID | N | The OAuth2 client ID that has been provisioned in the identity provider. Required when `authType` is set to `oidc` | `dapr-kafka` |
| oidcClientSecret | N | The OAuth2 client secret that has been provisioned in the identity provider: Required when `authType` is set to `oidc` | `"KeFg23!"` |
| oidcScopes | N | Comma-delimited list of OAuth2/OIDC scopes to request with the access token. Recommended when `authType` is set to `oidc`. Defaults to `"openid"` | `"openid,kafka-prod"` |
+| oidcExtensions | N | Input/Output | String containing a JSON-encoded dictionary of OAuth2/OIDC extensions to request with the access token | `{"cluster":"kafka","poolid":"kafkapool"}` |
The `secretKeyRef` above is referencing a [kubernetes secrets store]({{< ref kubernetes-secret-store.md >}}) to access the tls information. Visit [here]({{< ref setup-secret-store.md >}}) to learn more about how to configure a secret store component.
diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md
index 24aee2d4c1b..40d63bdfe75 100644
--- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md
+++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md
@@ -117,14 +117,60 @@ spec:
value: "myeventhubstoragecontainer"
```
-## Sending multiple messages
+## Sending and receiving multiple messages
-Azure Event Hubs supports sending multiple messages in a single operation. To set the metadata for bulk operations, set the query parameters on the HTTP request or the gRPC metadata as documented [here]({{< ref pubsub_api >}})
+Azure Eventhubs supports sending and receiving multiple messages in a single operation using the bulk pub/sub API.
+
+### Configuring bulk publish
+
+To set the metadata for bulk publish operation, set the query parameters on the HTTP request or the gRPC metadata, [as documented in the API reference]({{< ref pubsub_api >}}).
| Metadata | Default |
|----------|---------|
| `metadata.maxBulkPubBytes` | `1000000` |
+### Configuring bulk subscribe
+
+When subscribing to a topic, you can configure `bulkSubscribe` options. Refer to [Subscribing messages in bulk]({{< ref "pubsub-bulk#subscribing-messages-in-bulk" >}}) for more details and to learn more about [the bulk subscribe API]({{< ref pubsub-bulk.md >}}).
+
+| Configuration | Default |
+|---------------|---------|
+| `maxMessagesCount` | `100` |
+| `maxAwaitDurationMs` | `10000` |
+
+## Configuring checkpoint frequency
+
+When subscribing to a topic, you can configure the checkpointing frequency in a partition by [setting the metadata in the HTTP or gRPC subscribe request ]({{< ref "pubsub_api.md#http-request-2" >}}). This metadata enables checkpointing after the configured number of events within a partition event sequence. Disable checkpointing by setting the frequency to `0`.
+
+[Learn more about checkpointing](https://learn.microsoft.com/azure/event-hubs/event-hubs-features#checkpointing).
+
+| Metadata | Default |
+| -------- | ------- |
+| `metadata.checkPointFrequencyPerPartition` | `1` |
+
+Following example shows a sample subscription file for [Declarative subscription]({{< ref "subscription-methods.md#declarative-subscriptions" >}}) using `checkPointFrequencyPerPartition` metadata. Similarly, you can also pass the metadata in [Programmatic subscriptions]({{< ref "subscription-methods.md#programmatic-subscriptions" >}}) as well.
+
+```yaml
+apiVersion: dapr.io/v2alpha1
+kind: Subscription
+metadata:
+ name: order-pub-sub
+spec:
+ topic: orders
+ routes:
+ default: /checkout
+ pubsubname: order-pub-sub
+ metadata:
+ checkPointFrequencyPerPartition: 1
+scopes:
+- orderprocessing
+- checkout
+```
+
+{{% alert title="Note" color="primary" %}}
+When subscribing to a topic using `BulkSubscribe`, you configure the checkpointing to occur after the specified number of _batches,_ instead of events, where _batch_ means the collection of events received in a single request.
+{{% /alert %}}
+
## Create an Azure Event Hub
Follow the instructions on the [documentation](https://docs.microsoft.com/azure/event-hubs/event-hubs-create) to set up Azure Event Hubs.
diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-servicebus-queues.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-servicebus-queues.md
index 8ff7dbd5615..e98df4814f3 100644
--- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-servicebus-queues.md
+++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-servicebus-queues.md
@@ -11,7 +11,7 @@ aliases:
To set up Azure Service Bus Queues pub/sub, create a component of type `pubsub.azure.servicebus.queues`. See the [pub/sub broker component file]({{< ref setup-pubsub.md >}}) to learn how ConsumerID is automatically generated. Read the [How-to: Publish and Subscribe guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pub/sub configuration.
-> This component uses queues on Azure Service Bus; see the official documentation for the differences between [topics and queues](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions).
+> This component uses queues on Azure Service Bus; see the official documentation for the differences between [topics and queues](https://learn.microsoft.com/azure/service-bus-messaging/service-bus-queues-topics-subscriptions).
> For using topics, see the [Azure Service Bus Topics pubsub component]({{< ref "setup-azure-servicebus-topics" >}}).
### Connection String Authentication
@@ -122,7 +122,7 @@ Azure Service Bus messages extend the Dapr message format with additional contex
### Sending a message with metadata
-To set Azure Service Bus metadata when sending a message, set the query parameters on the HTTP request or the gRPC metadata as documented [here](https://docs.dapr.io/reference/api/pubsub_api/#metadata).
+To set Azure Service Bus metadata when sending a message, set the query parameters on the HTTP request or the gRPC metadata as documented [here]({{< ref "pubsub_api.md#metadata" >}}).
- `metadata.MessageId`
- `metadata.CorrelationId`
@@ -135,13 +135,14 @@ To set Azure Service Bus metadata when sending a message, set the query paramete
- `metadata.ScheduledEnqueueTimeUtc`
- `metadata.ReplyToSessionId`
-> **Note:** The `metadata.MessageId` property does not set the `id` property of the cloud event returned by Dapr and should be treated in isolation.
-
-> **Note:** The `metadata.ScheduledEnqueueTimeUtc` property supports the [RFC1123](https://www.rfc-editor.org/rfc/rfc1123) and [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp formats.
+{{% alert title="Note" color="primary" %}}
+- The `metadata.MessageId` property does not set the `id` property of the cloud event returned by Dapr and should be treated in isolation.
+- The `metadata.ScheduledEnqueueTimeUtc` property supports the [RFC1123](https://www.rfc-editor.org/rfc/rfc1123) and [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp formats.
+{{% /alert %}}
### Receiving a message with metadata
-When Dapr calls your application, it will attach Azure Service Bus message metadata to the request using either HTTP headers or gRPC metadata.
+When Dapr calls your application, it attaches Azure Service Bus message metadata to the request using either HTTP headers or gRPC metadata.
In addition to the [settable metadata listed above](#sending-a-message-with-metadata), you can also access the following read-only message metadata.
- `metadata.DeliveryCount`
@@ -152,7 +153,9 @@ In addition to the [settable metadata listed above](#sending-a-message-with-meta
To find out more details on the purpose of any of these metadata properties, please refer to [the official Azure Service Bus documentation](https://docs.microsoft.com/rest/api/servicebus/message-headers-and-properties#message-headers).
-> Note: that all times are populated by the server and are not adjusted for clock skews.
+{{% alert title="Note" color="primary" %}}
+All times are populated by the server and are not adjusted for clock skews.
+{{% /alert %}}
## Sending and receiving multiple messages
diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md
index c966f69885a..56c2a26836f 100644
--- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md
+++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-rabbitmq.md
@@ -62,6 +62,10 @@ spec:
value: false
- name: ttlInSeconds
value: 60
+ - name: clientName
+ value: {podName}
+ - name: heartBeat
+ value: 10s
```
{{% alert title="Warning" color="warning" %}}
@@ -96,6 +100,8 @@ The above example uses secrets as plain strings. It is recommended to use a secr
| caCert | Required for using TLS | Certificate Authority (CA) certificate in PEM format for verifying server TLS certificates. | `"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"`
| clientCert | Required for using TLS | TLS client certificate in PEM format. Must be used with `clientKey`. | `"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"`
| clientKey | Required for using TLS | TLS client key in PEM format. Must be used with `clientCert`. Can be `secretKeyRef` to use a secret reference. | `"-----BEGIN RSA PRIVATE KEY-----\n\n-----END RSA PRIVATE KEY-----"`
+| clientName | N | This RabbitMQ [client-provided connection name](https://www.rabbitmq.com/connections.html#client-provided-names) is a custom identifier. If set, the identifier is mentioned in RabbitMQ server log entries and management UI. Can be set to {uuid}, {podName}, or {appID}, which is replaced by Dapr runtime to the real value. | `"app1"`, `{uuid}`, `{podName}`, `{appID}`
+| heartBeat | N | Defines the heartbeat interval with the server, detecting the aliveness of the peer TCP connection with the RabbitMQ server. Defaults to `10s` . | `"10s"`
## Communication using TLS
diff --git a/daprdocs/content/en/reference/components-reference/supported-secret-stores/kubernetes-secret-store.md b/daprdocs/content/en/reference/components-reference/supported-secret-stores/kubernetes-secret-store.md
index b629503d827..a44a6de9a60 100644
--- a/daprdocs/content/en/reference/components-reference/supported-secret-stores/kubernetes-secret-store.md
+++ b/daprdocs/content/en/reference/components-reference/supported-secret-stores/kubernetes-secret-store.md
@@ -32,7 +32,12 @@ spec:
```
## Spec metadata fields
-For the Kubernetes secret store component, there are no metadata attributes.
+
+| Field | Required | Details | Example |
+|--------------------|:--------:|------------|-----|---------|
+| `defaultNamespace` | N | Default namespace to retrieve secrets from. If unset, the `namespace` must be specified in each request metadata or via environment variable `NAMESPACE` | `"default-ns"` |
+| `kubeconfigPath` | N | The path to the kubeconfig file. If not specified, the store uses the default in-cluster config value | `"/path/to/kubeconfig"`
+
## Optional per-request metadata properties
diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md
index 6e1bfad9216..0d5c682422e 100644
--- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md
+++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md
@@ -7,13 +7,7 @@ aliases:
- "/operations/components/setup-state-store/supported-state-stores/setup-postgresql/"
---
-This component allows using PostgreSQL (Postgres) as state store for Dapr.
-
-## Create a Dapr component
-
-Create a file called `postgresql.yaml`, paste the following and replace the `` value with your connection string. The connection string is a standard PostgreSQL connection string. For example, `"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=dapr_test"`. See the PostgreSQL [documentation on database connections](https://www.postgresql.org/docs/current/libpq-connect.html) for information on how to define a connection string.
-
-If you want to also configure PostgreSQL to store actors, add the `actorStateStore` option as in the example below.
+This component allows using PostgreSQL (Postgres) as state store for Dapr. See [this guide]({{< ref "howto-get-save-state.md#step-1-setup-a-state-store" >}}) on how to create and apply a state store configuration.
```yaml
apiVersion: dapr.io/v1alpha1
@@ -24,42 +18,72 @@ spec:
type: state.postgresql
version: v1
metadata:
- # Connection string
- - name: connectionString
- value: ""
- # Timeout for database operations, in seconds (optional)
- #- name: timeoutInSeconds
- # value: 20
- # Name of the table where to store the state (optional)
- #- name: tableName
- # value: "state"
- # Name of the table where to store metadata used by Dapr (optional)
- #- name: metadataTableName
- # value: "dapr_metadata"
- # Cleanup interval in seconds, to remove expired rows (optional)
- #- name: cleanupIntervalInSeconds
- # value: 3600
- # Max idle time for connections before they're closed (optional)
- #- name: connectionMaxIdleTime
- # value: 0
- # Uncomment this if you wish to use PostgreSQL as a state store for actors (optional)
- #- name: actorStateStore
- # value: "true"
+ # Connection string
+ - name: connectionString
+ value: ""
+ # Timeout for database operations, in seconds (optional)
+ #- name: timeoutInSeconds
+ # value: 20
+ # Name of the table where to store the state (optional)
+ #- name: tableName
+ # value: "state"
+ # Name of the table where to store metadata used by Dapr (optional)
+ #- name: metadataTableName
+ # value: "dapr_metadata"
+ # Cleanup interval in seconds, to remove expired rows (optional)
+ #- name: cleanupIntervalInSeconds
+ # value: 3600
+ # Maximum number of connections pooled by this component (optional)
+ #- name: maxConns
+ # value: 0
+ # Max idle time for connections before they're closed (optional)
+ #- name: connectionMaxIdleTime
+ # value: 0
+ # Controls the default mode for executing queries. (optional)
+ #- name: queryExecMode
+ # value: ""
+ # Uncomment this if you wish to use PostgreSQL as a state store for actors (optional)
+ #- name: actorStateStore
+ # value: "true"
```
+
{{% alert title="Warning" color="warning" %}}
The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
{{% /alert %}}
## Spec metadata fields
+### Authenticate using a connection string
+
+The following metadata options are **required** to authenticate using a PostgreSQL connection string.
+
+| Field | Required | Details | Example |
+|--------|:--------:|---------|---------|
+| `connectionString` | Y | The connection string for the PostgreSQL database. See the PostgreSQL [documentation on database connections](https://www.postgresql.org/docs/current/libpq-connect.html) for information on how to define a connection string. | `"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=my_db"`
+
+### Authenticate using Azure AD
+
+Authenticating with Azure AD is supported with Azure Database for PostgreSQL. All authentication methods supported by Dapr can be used, including client credentials ("service principal") and Managed Identity.
+
+| Field | Required | Details | Example |
+|--------|:--------:|---------|---------|
+| `useAzureAD` | Y | Must be set to `true` to enable the component to retrieve access tokens from Azure AD. | `"true"` |
+| `connectionString` | Y | The connection string for the PostgreSQL database.
key:
+ clientTLS:
+ rootCA:
+ secretKeyRef:
+ name:
+ key:
+ certificate:
+ secretKeyRef:
+ name:
+ key:
+ privateKey:
+ secretKeyRef:
+ name:
+ key:
scopes: # Optional
-
auth: # Optional
@@ -39,6 +52,7 @@ auth: # Optional
|--------------------|:--------:|---------|---------|
| baseUrl | Y | Base URL of the non-Dapr endpoint | `"https://api.github.com"`, `"http://api.github.com"`
| headers | N | HTTP request headers for service invocation | `name: "Accept-Language" value: "en-US"` 
+
+1. Request: "App A" to "Dapr sidecar A"
+1. Request: "Dapr sidecar A" to "Dapr sidecar B"
+1. Request: "Dapr sidecar B" to "App B"
+1. Response: "App B" to "Dapr sidecar B"
+1. Response: "Dapr sidecar B" to "Dapr sidecar A"
+1. Response: "Dapr sidecar A" to "App A"
+
## Example Architecture
Following the above call sequence, suppose you have the applications as described in the [Hello World tutorial](https://github.com/dapr/quickstarts/blob/master/tutorials/hello-world/README.md), where a python app invokes a node.js app. In such a scenario, the python app would be "Service A" , and a Node.js app would be "Service B".
diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-outbox.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-outbox.md
new file mode 100644
index 00000000000..c53930f2acd
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-outbox.md
@@ -0,0 +1,112 @@
+---
+type: docs
+title: "How-To: Enable the transactional outbox pattern"
+linkTitle: "How-To: Enable the transactional outbox pattern"
+weight: 400
+description: "Commit a single transaction across a state store and pub/sub message broker"
+---
+
+The transactional outbox pattern is a well known design pattern for sending notifications regarding changes in an application's state. The transactional outbox pattern uses a single transaction that spans across the database and the message broker delivering the notification.
+
+Developers are faced with many difficult technical challenges when trying to implement this pattern on their own, which often involves writing error-prone central coordination managers that, at most, support a combination of one or two databases and message brokers.
+
+For example, you can use the outbox pattern to:
+1. Write a new user record to an account database.
+1. Send a notification message that the account was successfully created.
+
+With Dapr's outbox support, you can notify subscribers when an application's state is created or updated when calling Dapr's [transactions API]({{< ref "state_api.md#state-transactions" >}}).
+
+The diagram below is an overview of how the outbox feature works:
+
+1) Service A saves/updates state to the state store using a transaction.
+2) A message is written to the broker under the same transaction. When the message is successfully delivered to the message broker, the transaction completes, ensuring the state and message are transacted together.
+3) The message broker delivers the message topic to any subscribers - in this case, Service B.
+
+
+
+## Requirements
+
+The outbox feature can be used with using any [transactional state store]({{< ref supported-state-stores >}}) supported by Dapr. All [pub/sub brokers]({{< ref supported-pubsub >}}) are supported with the outbox feature.
+
+{{% alert title="Note" color="primary" %}}
+Message brokers that work with the competing consumer pattern (for example, [Apache Kafka]({{< ref setup-apache-kafka>}}) are encouraged to reduce the chances of duplicate events.
+{{% /alert %}}
+
+## Usage
+
+To enable the outbox feature, add the following required and optional fields on a state store component:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+ name: mysql-outbox
+spec:
+ type: state.mysql
+ version: v1
+ metadata:
+ - name: connectionString
+ value: "