dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'issue_3704' of https://github.com/hhunter-ms/docs into issue_3704

This commit is contained in:
Hannah Hunter 2024-03-01 12:11:07 -05:00
parent 103ea58a33 633b052495
commit e5f9dc0ee9
5 changed files with 190 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
daprdocs/content/en/getting-started/quickstarts/workflow-quickstart.md
View File

@ -111,7 +111,7 @@ View the workflow trace spans in the Zipkin web UI (typically at `http://localho
### What happened?
When you ran `dapr run --app-id order-processor --resources-path ../../../components/ -- python3 app.py`:
When you ran `dapr run -f .`:
1. A unique order ID for the workflow is generated (in the above example, `f4e1926e-3721-478d-be8a-f5bebd1995da`) and the workflow is scheduled.
1. The `NotifyActivity` workflow activity sends a notification saying an order for 10 cars has been received.
@ -269,10 +269,12 @@ In `workflow.py`, the workflow is defined as a class with all of its associated
{{% codetab %}}
The `order-processor` console app starts and manages the lifecycle of an order processing workflow that stores and retrieves data in a state store. The workflow consists of four workflow activities, or tasks:
- `NotifyActivity`: Utilizes a logger to print out messages throughout the workflow
- `ReserveInventoryActivity`: Checks the state store to ensure that there is enough inventory for the purchase
- `ProcessPaymentActivity`: Processes and authorizes the payment
- `UpdateInventoryActivity`: Removes the requested items from the state store and updates the store with the new remaining inventory value
- `notifyActivity`: Utilizes a logger to print out messages throughout the workflow. These messages notify the user when there is insufficient inventory, their payment couldn't be processed, and more.
- `reserveInventoryActivity`: Checks the state store to ensure that there is enough inventory present for purchase.
- `requestApprovalActivity`: Requests approval for orders over a certain threshold
- `processPaymentActivity`: Processes and authorizes the payment.
- `updateInventoryActivity`: Updates the state store with the new remaining inventory value.
### Step 1: Pre-requisites
@ -299,12 +301,21 @@ In a new terminal window, navigate to the `order-processor` directory:
cd workflows/javascript/sdk/order-processor
```
### Step 3: Run the order processor app
In the terminal, start the order processor app alongside a Dapr sidecar:
Install the dependencies:
```bash
dapr run
cd ./javascript/sdk
npm install
npm run build
cd ..
```
### Step 3: Run the order processor app
In the terminal, start the order processor app alongside a Dapr sidecar using [Multi-App Run]({{< ref multi-app-dapr-run >}}):
```bash
dapr run -f .
```
This starts the `order-processor` app with unique workflow ID and runs the workflow activities.
@ -312,7 +323,66 @@ This starts the `order-processor` app with unique workflow ID and runs the workf
Expected output:
```
== APP - workflowApp == == APP == Orchestration scheduled with ID: 0c332155-1e02-453a-a333-28cfc7777642
== APP - workflowApp == == APP == Waiting 30 seconds for instance 0c332155-1e02-453a-a333-28cfc7777642 to complete...
== APP - workflowApp == == APP == Received "Orchestrator Request" work item with instance id '0c332155-1e02-453a-a333-28cfc7777642'
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Rebuilding local state with 0 history event...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Processing 2 new history event(s): [ORCHESTRATORSTARTED=1, EXECUTIONSTARTED=1]
== APP - workflowApp == == APP == Processing order 0c332155-1e02-453a-a333-28cfc7777642...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Waiting for 1 task(s) and 0 event(s) to complete...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Returning 1 action(s)
== APP - workflowApp == == APP == Received "Activity Request" work item
== APP - workflowApp == == APP == Received order 0c332155-1e02-453a-a333-28cfc7777642 for 10 item1 at a total cost of 100
== APP - workflowApp == == APP == Activity notifyActivity completed with output undefined (0 chars)
== APP - workflowApp == == APP == Received "Orchestrator Request" work item with instance id '0c332155-1e02-453a-a333-28cfc7777642'
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Rebuilding local state with 3 history event...
== APP - workflowApp == == APP == Processing order 0c332155-1e02-453a-a333-28cfc7777642...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Processing 2 new history event(s): [ORCHESTRATORSTARTED=1, TASKCOMPLETED=1]
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Waiting for 1 task(s) and 0 event(s) to complete...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Returning 1 action(s)
== APP - workflowApp == == APP == Received "Activity Request" work item
== APP - workflowApp == == APP == Reserving inventory for 0c332155-1e02-453a-a333-28cfc7777642 of 10 item1
== APP - workflowApp == == APP == 2024-02-16T03:15:59.498Z INFO [HTTPClient, HTTPClient] Sidecar Started
== APP - workflowApp == == APP == There are 100 item1 in stock
== APP - workflowApp == == APP == Activity reserveInventoryActivity completed with output {"success":true,"inventoryItem":{"perItemCost":100,"quantity":100,"itemName":"item1"}} (86 chars)
== APP - workflowApp == == APP == Received "Orchestrator Request" work item with instance id '0c332155-1e02-453a-a333-28cfc7777642'
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Rebuilding local state with 6 history event...
== APP - workflowApp == == APP == Processing order 0c332155-1e02-453a-a333-28cfc7777642...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Processing 2 new history event(s): [ORCHESTRATORSTARTED=1, TASKCOMPLETED=1]
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Waiting for 1 task(s) and 0 event(s) to complete...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Returning 1 action(s)
== APP - workflowApp == == APP == Received "Activity Request" work item
== APP - workflowApp == == APP == Processing payment for order item1
== APP - workflowApp == == APP == Payment of 100 for 10 item1 processed successfully
== APP - workflowApp == == APP == Activity processPaymentActivity completed with output true (4 chars)
== APP - workflowApp == == APP == Received "Orchestrator Request" work item with instance id '0c332155-1e02-453a-a333-28cfc7777642'
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Rebuilding local state with 9 history event...
== APP - workflowApp == == APP == Processing order 0c332155-1e02-453a-a333-28cfc7777642...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Processing 2 new history event(s): [ORCHESTRATORSTARTED=1, TASKCOMPLETED=1]
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Waiting for 1 task(s) and 0 event(s) to complete...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Returning 1 action(s)
== APP - workflowApp == == APP == Received "Activity Request" work item
== APP - workflowApp == == APP == Updating inventory for 0c332155-1e02-453a-a333-28cfc7777642 of 10 item1
== APP - workflowApp == == APP == Inventory updated for 0c332155-1e02-453a-a333-28cfc7777642, there are now 90 item1 in stock
== APP - workflowApp == == APP == Activity updateInventoryActivity completed with output {"success":true,"inventoryItem":{"perItemCost":100,"quantity":90,"itemName":"item1"}} (85 chars)
== APP - workflowApp == == APP == Received "Orchestrator Request" work item with instance id '0c332155-1e02-453a-a333-28cfc7777642'
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Rebuilding local state with 12 history event...
== APP - workflowApp == == APP == Processing order 0c332155-1e02-453a-a333-28cfc7777642...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Processing 2 new history event(s): [ORCHESTRATORSTARTED=1, TASKCOMPLETED=1]
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Waiting for 1 task(s) and 0 event(s) to complete...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Returning 1 action(s)
== APP - workflowApp == == APP == Received "Activity Request" work item
== APP - workflowApp == == APP == order 0c332155-1e02-453a-a333-28cfc7777642 processed successfully!
== APP - workflowApp == == APP == Activity notifyActivity completed with output undefined (0 chars)
== APP - workflowApp == == APP == Received "Orchestrator Request" work item with instance id '0c332155-1e02-453a-a333-28cfc7777642'
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Rebuilding local state with 15 history event...
== APP - workflowApp == == APP == Processing order 0c332155-1e02-453a-a333-28cfc7777642...
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Processing 2 new history event(s): [ORCHESTRATORSTARTED=1, TASKCOMPLETED=1]
== APP - workflowApp == == APP == Order 0c332155-1e02-453a-a333-28cfc7777642 processed successfully!
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Orchestration completed with status COMPLETED
== APP - workflowApp == == APP == 0c332155-1e02-453a-a333-28cfc7777642: Returning 1 action(s)
== APP - workflowApp == time="2024-02-15T21:15:59.5589687-06:00" level=info msg="0c332155-1e02-453a-a333-28cfc7777642: 'orderProcessingWorkflow' completed with a COMPLETED status." app_id=activity-sequence-workflow instance=kaibocai-devbox scope=wfengine.backend type=log ver=1.12.4
== APP - workflowApp == == APP == Instance 0c332155-1e02-453a-a333-28cfc7777642 completed
```
### (Optional) Step 4: View in Zipkin
@ -329,41 +399,90 @@ View the workflow trace spans in the Zipkin web UI (typically at `http://localho
### What happened?
When you ran `dapr run `:
When you ran `dapr run -f .`:
1. A unique order ID for the workflow is generated (in the above example, `6d2abcc9`) and the workflow is scheduled.
1. The `NotifyActivity` workflow activity sends a notification saying an order for 10 cars has been received.
1. The `ReserveInventoryActivity` workflow activity checks the inventory data, determines if you can supply the ordered item, and responds with the number of cars in stock.
1. A unique order ID for the workflow is generated (in the above example, `0c332155-1e02-453a-a333-28cfc7777642`) and the workflow is scheduled.
1. The `notifyActivity` workflow activity sends a notification saying an order for 10 cars has been received.
1. The `reserveInventoryActivity` workflow activity checks the inventory data, determines if you can supply the ordered item, and responds with the number of cars in stock.
1. Your workflow starts and notifies you of its status.
1. The `ProcessPaymentActivity` workflow activity begins processing payment for order `6d2abcc9` and confirms if successful.
1. The `UpdateInventoryActivity` workflow activity updates the inventory with the current available cars after the order has been processed.
1. The `NotifyActivity` workflow activity sends a notification saying that order `6d2abcc9` has completed.
1. The `processPaymentActivity` workflow activity begins processing payment for order `0c332155-1e02-453a-a333-28cfc7777642` and confirms if successful.
1. The `updateInventoryActivity` workflow activity updates the inventory with the current available cars after the order has been processed.
1. The `notifyActivity` workflow activity sends a notification saying that order `0c332155-1e02-453a-a333-28cfc7777642` has completed.
1. The workflow terminates as completed.
#### `order-processor/index.js`
#### `order-processor/workflowApp.ts`
In the application's program file:
In the application file:
- The unique workflow order ID is generated
- The workflow is scheduled
- The workflow status is retrieved
- The workflow and the workflow activities it invokes are registered
```javascript
import { DaprWorkflowClient, WorkflowRuntime, DaprClient } from "@dapr/dapr-dev";
import { InventoryItem, OrderPayload } from "./model";
import { notifyActivity, orderProcessingWorkflow, processPaymentActivity, requestApprovalActivity, reserveInventoryActivity, updateInventoryActivity } from "./orderProcessingWorkflow";
async function start() {
// Update the gRPC client and worker to use a local address and port
const workflowClient = new DaprWorkflowClient();
const workflowWorker = new WorkflowRuntime();
const daprClient = new DaprClient();
const storeName = "statestore";
const inventory = new InventoryItem("item1", 100, 100);
const key = inventory.itemName;
await daprClient.state.save(storeName, [
{
key: key,
value: inventory,
}
]);
const order = new OrderPayload("item1", 100, 10);
workflowWorker
.registerWorkflow(orderProcessingWorkflow)
.registerActivity(notifyActivity)
.registerActivity(reserveInventoryActivity)
.registerActivity(requestApprovalActivity)
.registerActivity(processPaymentActivity)
.registerActivity(updateInventoryActivity);
// Wrap the worker startup in a try-catch block to handle any errors during startup
try {
await workflowWorker.start();
console.log("Workflow runtime started successfully");
} catch (error) {
console.error("Error starting workflow runtime:", error);
}
// Schedule a new orchestration
try {
const id = await workflowClient.scheduleNewWorkflow(orderProcessingWorkflow, order);
console.log(`Orchestration scheduled with ID: ${id}`);
// Wait for orchestration completion
const state = await workflowClient.waitForWorkflowCompletion(id, undefined, 30);
console.log(`Orchestration completed! Result: ${state?.serializedOutput}`);
} catch (error) {
console.error("Error scheduling or waiting for orchestration:", error);
throw error;
}
await workflowWorker.stop();
await workflowClient.stop();
}
start().catch((e) => {
console.error(e);
process.exit(1);
});
```
#### `order-processor/Workflows/OrderProcessingWorkflow.js`
In `OrderProcessingWorkflow.js`, the workflow is defined as a class with all of its associated tasks (determined by workflow activities).
```javascript
```
#### `order-processor/Activities` directory
The `Activities` directory holds the four workflow activities used by the workflow, defined in the following files:
{{% /codetab %}}
<!-- .NET -->
@ -454,7 +573,7 @@ View the workflow trace spans in the Zipkin web UI (typically at `http://localho
### What happened?
When you ran `dapr run --app-id order-processor dotnet run`:
When you ran `dapr run -f .`:
1. A unique order ID for the workflow is generated (in the above example, `6d2abcc9`) and the workflow is scheduled.
1. The `NotifyActivity` workflow activity sends a notification saying an order for 10 cars has been received.
@ -713,7 +832,7 @@ View the workflow trace spans in the Zipkin web UI (typically at `http://localho
### What happened?
When you ran `dapr run`:
When you ran `dapr run -f .`:
1. A unique order ID for the workflow is generated (in the above example, `edceba90-9c45-4be8-ad40-60d16e060797`) and the workflow is scheduled.
1. The `NotifyActivity` workflow activity sends a notification saying an order for 10 cars has been received.

6
daprdocs/content/en/operations/components/certification-lifecycle.md
View File

@ -62,6 +62,12 @@ A component may skip the Beta stage and conformance test requirement per the dis
- The component has been available as Alpha or Beta for at least 1 minor version release of Dapr runtime prior
- A maintainer will address component security, core functionality and test issues according to the Dapr support policy and issue a patch release that includes the patched stable component
{{% alert title="Note" color="primary" %}}
Stable Dapr components are based on Dapr certification and conformance tests and are not a guarantee of support by any specific vendor, where the vendor's SDK is used as part of the component.
Dapr component tests guarantee the stability of a component independent of a third party vendor's declared stability status for any SDKs used. This is because the meaning of stable (for example alpha, beta, stable) can vary for each vendor.
{{% /alert %}}
### Previous Generally Available (GA) components
Any component that was previously certified as GA is allowed into Stable even if the new requirements are not met.

25
daprdocs/content/en/operations/resiliency/health-checks/sidecar-health.md
View File

@ -8,22 +8,29 @@ description: Dapr sidecar health checks
Dapr provides a way to determine its health using an [HTTP `/healthz` endpoint]({{< ref health_api.md >}}). With this endpoint, the *daprd* process, or sidecar, can be:
- Probed for its health
- Determined for readiness and liveness
- Probed for its overall health
- Probed for Dapr sidecar readiness during initialization
- Determined for readiness and liveness with Kubernetes
In this guide, you learn how the Dapr `/healthz` endpoint integrate with health probes from the application hosting platform (for example, Kubernetes).
The following diagram demonstrates how Dapr checks for outbound health connections from the sidecar using `v1.0/healthz/outbound`, as shown by the green boundary lines. With this behavior, Dapr waits for a successful response from `v1.0/healthz/outbound`, rather than waiting for the Dapr HTTP port to be available (as shown by the red boundary lines). This provides a more explict implementation that is better isolated from accidental change.
<img src="/images/healthz-outbound.png" width="800" alt="Diagram of Dapr checking oubound health connections." />
When deploying Dapr to a hosting platform like Kubernetes, the Dapr health endpoint is automatically configured for you.
In this guide, you learn how the Dapr `/healthz` endpoint integrate with health probes from the application hosting platform (for example, Kubernetes) as well as the Dapr SDKs.
{{% alert title="Note" color="primary" %}}
Dapr actors also have a health API endpoint where Dapr probes the application for a response to a signal from Dapr that the actor application is healthy and running. See [actor health API]({{< ref "actors_api.md#health-check" >}}).
{{% /alert %}}
The following diagram shows the steps when a Dapr sidecar starts, the healthz endpoint and when the App channel is initialized.
<img src="/images/healthz-outbound.png" width="800" alt="Diagram of Dapr checking oubound health connections." />
## Outbound health endpoint
The `v1.0/healthz/` endpoint is used to wait when all components are initialized, the Dapr HTTP port to be available _and_ the app channel is initialized, as shown by the red boundary lines. This is used to check the complete initialization of the Dapr sidecar and its health. On the other hand, the `v1.0/healthz/outbound` endpoint returns successfully when all the components are initialized, the Dapr HTTP port to be available, but the app channel is not yet established as shown by the green boundary lines.
In the Dapr SDKs the `waitForSidecar` method (for example .NET and Java SDKs) uses for this specific check with the `v1.0/healthz/outbound` endpoint. Using this behavior, Dapr waits for a successful response from `v1.0/healthz/outbound`, rather than waiting for the app channel to be available (as shown by the red boundary lines) with the v1.0/healthz/ endpoint. This approach enables your application to perform calls on the Dapr sidecar APIs before the app channel is initalized, for example reading secrets with the secrets API.
If you are using the `waitForSidecar` method on the SDKs then the correct initialization is performed. Otherwise you can call the `v1.0/healthz/outbound` endpoint during initalization, and if successesful, then you can call the Dapr sidecar APIs.
## Health endpoint: Integration with Kubernetes
When deploying Dapr to a hosting platform like Kubernetes, the Dapr health endpoint is automatically configured for you.
Kubernetes uses *readiness* and *liveness* probes to determines the health of the container.

9
daprdocs/content/en/operations/support/support-release-policy.md
View File

@ -91,6 +91,15 @@ The table below shows the versions of Dapr releases that have been tested togeth
| Mar 25th 2022 | 1.6.1</br> | 1.6.0 | Java 1.4.0 </br>Go 1.3.1 </br>PHP 1.1.0 </br>Python 1.5.0 </br>.NET 1.6.0 </br>JS 2.0.0 | 0.9.0 | Unsupported | |
| Jan 25th 2022 | 1.6.0</br> | 1.6.0 | Java 1.4.0 </br>Go 1.3.1 </br>PHP 1.1.0 </br>Python 1.5.0 </br>.NET 1.6.0 </br>JS 2.0.0 | 0.9.0 | Unsupported | |
## SDK compatibility
The SDKs and runtime are committed to non-breaking changes other than those required for security issues. All breaking changes are announced if required in the release notes.
**SDK and runtime forward compatibility**
Newer Dapr SDKs support the latest version of Dapr runtime and two previous versions (N-2).
**SDK and runtime backward compatibility**
For a new Dapr runtime, the current SDK version and two previous versions (N-2) are supported.
## Upgrade paths
After the 1.0 release of the runtime there may be situations where it is necessary to explicitly upgrade through an additional release to reach the desired target. For example, an upgrade from v1.0 to v1.2 may need to pass through v1.1.

14
daprdocs/content/en/reference/api/health_api.md
View File

@ -6,17 +6,17 @@ description: "Detailed documentation on the health API"
weight: 1000
---
Dapr provides health checking probes that can be used as readiness or liveness of Dapr.
Dapr provides health checking probes that can be used as readiness or liveness of Dapr and for initialization readiness from SDKs.
## Get Dapr health state
Gets the health state for Dapr by either:
- Waiting for a specific health check against `v1.0/healthz/outbound`; or
- Waiting for the Dapr HTTP port to become available
- Check for sidecar health
- Check for the sidecar health, including component readiness, used during initialization.
### Wait for Dapr HTTP port to become available
With this behavior, Dapr waits for the Dapr HTTP port to become available to
Wait for all components to be initialized, the Dapr HTTP port to be available _and_ the app channel is initialized. For example, this endpoint is used with Kubernetes liveness probes.
#### HTTP Request
@ -45,9 +45,9 @@ curl -i http://localhost:3500/v1.0/healthz
### Wait for specific health check against `/outbound` path
With this behavior, Dapr waits for a successful response from `v1.0/healthz/outbound`, rather than waiting for the Dapr HTTP port to be available. This provides a more explict implementation that is better isolated from accidental change.
Wait for all components to be initialized, the Dapr HTTP port to be available, however the app channel is not yet established. This endpoint enables your application to perform calls on the Dapr sidecar APIs before the app channel is initalized, for example reading secrets with the secrets API. For example used in the Dapr SDKs `waitForSidecar` method (for example .NET and Java SDKs) to check sidecar is initialized correctly ready for any calls.
For example, [in the .NET SDK,](https://github.com/dapr/dotnet-sdk/blob/17f849b17505b9a61be1e7bd3e69586718b9fdd3/src/Dapr.Client/DaprClientGrpc.cs#L1758-L1785) if the ordering of a Dapr runtime init ever changed (accidentally or deliberately), and the Dapr HTTP port was open _before_ all components were initialized, this would cause a break in behavior.
For example, the [Java SDK](https://docs.dapr.io/developing-applications/sdks/java/java-client/#wait-for-sidecar) and [the .NET SDK](https://github.com/dapr/dotnet-sdk/blob/17f849b17505b9a61be1e7bd3e69586718b9fdd3/src/Dapr.Client/DaprClientGrpc.cs#L1758-L1785) uses this endpoint for initialization.
Currently supported in the:
- [.NET SDK](https://github.com/dapr/dotnet-sdk/blob/17f849b17505b9a61be1e7bd3e69586718b9fdd3/src/Dapr.Client/DaprClientGrpc.cs#L1758-L1785)
@ -82,4 +82,4 @@ curl -i http://localhost:3500/v1.0/healthz/outbound
## Related articles
- [Sidecar health]({{< ref "sidecar-health.md" >}})
- [App health]({{< ref "app-health.md" >}})
- [App health]({{< ref "app-health.md" >}})