mirror of https://github.com/dapr/docs.git
Merge branch 'v1.11' into workflow-review
Signed-off-by: Mark Fussell <markfussell@gmail.com>
This commit is contained in:
Mark Fussell
GitHub
commit
727237d115
|
|
@ -29,4 +29,5 @@ The following are the building blocks provided by Dapr:
|
|||
| [**Secrets**]({{< ref "secrets-overview.md" >}}) | `/v1.0/secrets` | Dapr provides a secrets building block API and integrates with secret stores such as public cloud stores, local stores and Kubernetes to store the secrets. Services can call the secrets API to retrieve secrets, for example to get a connection string to a database.
|
||||
| [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | `/v1.0/configuration` | The Configuration API enables you to retrieve and subscribe to application configuration items for supported configuration stores. This enables an application to retrieve specific configuration information, for example, at start up or when configuration changes are made in the store.
|
||||
| [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource so that multiple instances of an application can access the resource without conflicts and provide consistency guarantees.
|
||||
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability.
|
||||
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability.
|
||||
| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your application.
|
||||
|
|
@ -108,6 +108,13 @@ A [workflow]({{< ref workflow-overview.md >}}) is custom application logic that
|
|||
<!--- [List of supported workflows]()
|
||||
- [Workflow implementations](https://github.com/dapr/components-contrib/tree/master/workflows)-->
|
||||
|
||||
### Cryptography
|
||||
|
||||
[Cryptography]({{< ref cryptography-overview.md >}}) components are used to perform crypographic operations, including encrypting and decrypting messages, without exposing keys to your application.
|
||||
|
||||
- [List of supported cryptography components]({{< ref supported-cryptography >}})
|
||||
- [Cryptography implementations](https://github.com/dapr/components-contrib/tree/master/crypto)
|
||||
|
||||
### Middleware
|
||||
|
||||
Dapr allows custom [middleware]({{< ref "middleware.md" >}}) to be plugged into the HTTP request processing pipeline. Middleware can perform additional actions on an HTTP request (such as authentication, encryption, and message transformation) before the request is routed to the user code, or the response is returned to the client. The middleware components are used with the [service invocation]({{< ref "service-invocation-overview.md" >}}) building block.
|
||||
|
|
|
|||
|
|
@ -44,8 +44,8 @@ Each of these building block APIs is independent, meaning that you can use one,
|
|||
| [**Secrets**]({{< ref "secrets-overview.md" >}}) | The secrets management API integrates with public cloud and local secret stores to retrieve the secrets for use in application code.
|
||||
| [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | The configuration API enables you to retrieve and subscribe to application configuration items from configuration stores.
|
||||
| [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | The distributed lock API enables your application to acquire a lock for any resource that gives it exclusive access until either the lock is released by the application, or a lease timeout occurs.
|
||||
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The workflow API can be combined with other Dapr building blocks to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components.
|
||||
|
||||
| [**Workflows**]({{< ref "workflow-overview.md" >}}) | The workflow API can be combined with other Dapr building blocks to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components.
|
||||
| [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | The cryptography API provides an abstraction layer on top of security infrastructure such as key vaults. It contains APIs that allow you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your applications.
|
||||
|
||||
## Sidecar architecture
|
||||
|
||||
|
|
|
|||
|
|
@ -26,12 +26,12 @@ Create a configuration item in a supported configuration store. This can be a si
|
|||
docker run --name my-redis -p 6379:6379 -d redis:6
|
||||
```
|
||||
|
||||
### Save an item
|
||||
### Save an item
|
||||
|
||||
Using the [Redis CLI](https://redis.com/blog/get-redis-cli-without-installing-redis-server/), connect to the Redis instance:
|
||||
|
||||
```
|
||||
redis-cli -p 6379
|
||||
redis-cli -p 6379
|
||||
```
|
||||
|
||||
Save a configuration item:
|
||||
|
|
@ -45,10 +45,10 @@ MSET orderId1 "101||1" orderId2 "102||1"
|
|||
Save the following component file to the [default components folder]({{< ref "install-dapr-selfhost.md#step-5-verify-components-directory-has-been-initialized" >}}) on your machine. You can use this as the Dapr component YAML:
|
||||
|
||||
- For Kubernetes using `kubectl`.
|
||||
- When running with the Dapr CLI.
|
||||
- When running with the Dapr CLI.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Since the Redis configuration component has identical metadata to the Redis `statestore.yaml` component, you can simply copy/change the Redis state store component type if you already have a Redis `statestore.yaml`.
|
||||
Since the Redis configuration component has identical metadata to the Redis `statestore.yaml` component, you can simply copy/change the Redis state store component type if you already have a Redis `statestore.yaml`.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
|
|
@ -250,7 +250,7 @@ Invoke-RestMethod -Uri 'http://localhost:3601/v1.0/configuration/configstore?key
|
|||
|
||||
### Subscribe to configuration item updates
|
||||
|
||||
Below are code examples that leverage SDKs to subscribe to keys `[orderId1, orderId2]` using `configstore` store component.
|
||||
Below are code examples that leverage SDKs to subscribe to keys `[orderId1, orderId2]` using `configstore` store component.
|
||||
|
||||
{{< tabs ".NET" "ASP.NET Core" Java Python Go Javascript>}}
|
||||
|
||||
|
|
@ -328,7 +328,7 @@ namespace ConfigurationApi
|
|||
// Get the initial value and continue to watch it for changes.
|
||||
config.AddDaprConfigurationStore("configstore", new List<string>() { "orderId1","orderId2" }, client, TimeSpan.FromSeconds(20));
|
||||
config.AddStreamingDaprConfigurationStore("configstore", new List<string>() { "orderId1","orderId2" }, client, TimeSpan.FromSeconds(20));
|
||||
|
||||
|
||||
})
|
||||
.ConfigureWebHostDefaults(webBuilder =>
|
||||
{
|
||||
|
|
@ -429,7 +429,7 @@ dapr run --app-id orderprocessing -- python3 OrderProcessingService.py
|
|||
|
||||
{{% codetab %}}
|
||||
|
||||
```go
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
|
|
@ -653,7 +653,7 @@ async function main() {
|
|||
);
|
||||
setTimeout(() => {
|
||||
// Unsubscribe to config updates
|
||||
stream.stop();
|
||||
stream.stop();
|
||||
console.log("App unsubscribed to config changes");
|
||||
process.exit(0);
|
||||
}, 20000);
|
||||
|
|
@ -679,6 +679,8 @@ Invoke-RestMethod -Uri 'http://localhost:<DAPR_HTTP_PORT>/v1.0/configuration/con
|
|||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Next steps
|
||||
|
||||
* Read [configuration API overview]({{< ref configuration-api-overview.md >}})
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Cryptography"
|
||||
linkTitle: "Cryptography"
|
||||
weight: 110
|
||||
description: "Perform cryptographic operations without exposing keys to your application"
|
||||
---
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
---
|
||||
type: docs
|
||||
title: Cryptography overview
|
||||
linkTitle: Overview
|
||||
weight: 1000
|
||||
description: "Overview of Dapr Cryptography"
|
||||
---
|
||||
|
||||
With the cryptography building block, you can leverage cryptography in a safe and consistent way. Dapr exposes APIs that allow you to perform operations, such as encrypting and decrypting messages, within key vaults or the Dapr sidecar, without exposing cryptographic keys to your application.
|
||||
|
||||
## Why Cryptography?
|
||||
|
||||
Applications make extensive use of cryptography, which, when implemented correctly, can make solutions safer even when data is compromised. In certain cases, you may be required to use cryptography to comply with industry regulations (for example, in finance) or legal requirements (including privacy regulations such as GDPR).
|
||||
|
||||
However, leveraging cryptography correctly can be difficult. You need to:
|
||||
|
||||
- Pick the right algorithms and options
|
||||
- Learn the proper way to manage and protect keys
|
||||
- Navigate operational complexities when you wants limit access to cryptographic key material
|
||||
|
||||
One important requirement for security is limiting access to your cryptographic keys, what is often referred to as "raw key material". Dapr can integrate with key vaults such as Azure Key Vault (with more components coming in the future) which store keys in secure enclaves and perform cryptographic operations in the vaults, without exposing keys to your application or Dapr.
|
||||
|
||||
Alternatively, you can configure Dapr to manage the cryptographic keys for you, performing operations within the sidecar, again without exposing raw key material to your application.
|
||||
|
||||
## Cryptography in Dapr
|
||||
|
||||
With Dapr, you can perform cryptographic operations without exposing cryptographic keys to your application.
|
||||
|
||||
<img src="/images/cryptography-overview.png" width=1000 style="padding-bottom:15px;" alt="Diagram showing how Dapr cryptography works with your app">
|
||||
|
||||
|
||||
By using the cryptography building block, you can:
|
||||
|
||||
- More easily perform cryptographic operations in a safe way. Dapr provides safeguards against using unsafe algorithms, or using algorithms with unsafe options.
|
||||
- Keep keys outside of applications. Applications never see the "raw key material", but can request the vault to perform operations with the keys. When using the cryptographic engine of Dapr, operations are performed safely within the Dapr sidecar.
|
||||
- Experience greater separation of concerns. By using external vaults or cryptographic components, only authorized teams can access private key materials.
|
||||
- Manage and rotate keys more easily. Keys are managed in the vault and outside of the application, and they can be rotated without needing the developers to be involved (or even without restarting the apps).
|
||||
- Enables better audit logging to monitor when operations are performed with keys in a vault.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
While both HTTP and gRPC are supported in the alpha release, using the gRPC APIs with the supported Dapr SDKs is the recommended approach for cryptography.
|
||||
{{% /alert %}}
|
||||
|
||||
## Features
|
||||
|
||||
### Cryptographic components
|
||||
|
||||
The Dapr cryptography building block incldues two kinds of components:
|
||||
|
||||
- **Components that allow interacting with management services or vaults ("key vaults").**
|
||||
Similar to how Dapr offers an "abstraction layer" on top of various secret stores or state stores, these components allow interacting with various key vaults such as Azure Key Vault (with more coming in future Dapr releases). With these components, cryptographic operations on the private keys are performed within the vaults and Dapr never sees your private keys.
|
||||
|
||||
- **Components based on Dapr's own cryptographic engine.**
|
||||
When key vaults are not available, you can leverage components based on Dapr's own cryptographic engine. These components, which have `.dapr.` in the name, perform cryptographic operations within the Dapr sidecar, with keys stored on files, Kubernetes secrets, or other sources. Although the private keys are known by Dapr, they are still not available to your applications.
|
||||
|
||||
Both kinds of components, either those leveraging key vaults or using the cryptopgrahic engine in Dapr, offer the same abstraction layer. This allows your solution to switch between various vaults and/or cryptography components as needed. For example, you can use a locally-stored key during development, and a cloud vault in production.
|
||||
|
||||
### Cryptographic APIs
|
||||
|
||||
Cryptographic APIs allow encrypting and decrypting data using the [Dapr Crypto Scheme v1](https://github.com/dapr/kit/blob/main/schemes/enc/v1/README.md). This is an opinionated encryption scheme designed to use modern, safe cryptographic standards, and processes data (even large files) efficiently as a stream.
|
||||
|
||||
## Try out cryptography
|
||||
|
||||
### Quickstarts and tutorials
|
||||
|
||||
Want to put the Dapr cryptography API to the test? Walk through the following quickstart and tutorials to see cryptography in action:
|
||||
|
||||
| Quickstart/tutorial | Description |
|
||||
| ------------------- | ----------- |
|
||||
| [Cryptography quickstart]({{< ref cryptography-quickstart.md >}}) | Encrypt and decrypt messages and large files using RSA and AES keys with the cryptography API. |
|
||||
|
||||
### Start using cryptography directly in your app
|
||||
|
||||
Want to skip the quickstarts? Not a problem. You can try out the cryptography building block directly in your application to encrypt and decrypt your application. After [Dapr is installed]({{< ref "getting-started/_index.md" >}}), you can begin using the cryptography API starting with [the cryptography how-to guide]({{< ref howto-cryptography.md >}}).
|
||||
|
||||
## Demo
|
||||
|
||||
Watch this [demo video of the Cryptography API from the Dapr Community Call #83](https://youtu.be/PRWYX4lb2Sg?t=1148):
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/PRWYX4lb2Sg?start=1148" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
|
||||
|
||||
## Next steps
|
||||
|
||||
{{< button text="Use the cryptography API >>" page="howto-cryptography.md" >}}
|
||||
|
||||
## Related links
|
||||
- [Cryptography overview]({{< ref cryptography-overview.md >}})
|
||||
- [Cryptography component specs]({{< ref supported-cryptography >}})
|
||||
|
|
@ -0,0 +1,146 @@
|
|||
---
|
||||
type: docs
|
||||
title: "How to: Use the cryptography APIs"
|
||||
linkTitle: "How to: Use cryptography"
|
||||
weight: 2000
|
||||
description: "Learn how to encrypt and decrypt files"
|
||||
---
|
||||
|
||||
Now that you've read about [Cryptography as a Dapr building block]({{< ref cryptography-overview.md >}}), let's walk through using the cryptography APIs with the SDKs.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Dapr cryptography is currently in alpha.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
## Encrypt
|
||||
|
||||
Using the Dapr gRPC APIs in your project, you can encrypt a stream of data, such as a file.
|
||||
|
||||
{{< tabs "Go" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--go-->
|
||||
|
||||
```go
|
||||
out, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{
|
||||
// Name of the Dapr component (required)
|
||||
ComponentName: "mycryptocomponent",
|
||||
// Name of the key stored in the component (required)
|
||||
KeyName: "mykey",
|
||||
// Algorithm used for wrapping the key, which must be supported by the key named above.
|
||||
// Options include: "RSA", "AES"
|
||||
Algorithm: "RSA",
|
||||
})
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
The following example puts the `Encrypt` API in context, with code that reads the file, encrypts it, then stores the result in another file.
|
||||
|
||||
{{< tabs "Go" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--go-->
|
||||
|
||||
```go
|
||||
// Input file, clear-text
|
||||
rf, err := os.Open("input")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer rf.Close()
|
||||
|
||||
// Output file, encrypted
|
||||
wf, err := os.Create("output.enc")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
defer wf.Close()
|
||||
|
||||
// Encrypt the data using Dapr
|
||||
out, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{
|
||||
// These are the 3 required parameters
|
||||
ComponentName: "mycryptocomponent",
|
||||
KeyName: "mykey",
|
||||
Algorithm: "RSA",
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Read the stream and copy it to the out file
|
||||
n, err := io.Copy(wf, out)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Println("Written", n, "bytes")
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
The following example uses the `Encrypt` API to encrypt a string.
|
||||
|
||||
{{< tabs "Go" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--go-->
|
||||
|
||||
```go
|
||||
// Input string
|
||||
rf := strings.NewReader("Amor, ch’a nullo amato amar perdona, mi prese del costui piacer sì forte, che, come vedi, ancor non m’abbandona")
|
||||
|
||||
// Encrypt the data using Dapr
|
||||
enc, err := sdkClient.Encrypt(context.Background(), rf, dapr.EncryptOptions{
|
||||
ComponentName: "mycryptocomponent",
|
||||
KeyName: "mykey",
|
||||
Algorithm: "RSA",
|
||||
})
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// Read the encrypted data into a byte slice
|
||||
enc, err := io.ReadAll(enc)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
|
||||
## Decrypt
|
||||
|
||||
To decrypt a file, add the `Decrypt` gRPC API to your project.
|
||||
|
||||
{{< tabs "Go" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--go-->
|
||||
|
||||
In the following example, `out` is a stream that can be written to file or read in memory, as in the examples above.
|
||||
|
||||
```go
|
||||
out, err := sdkClient.Decrypt(context.Background(), rf, dapr.EncryptOptions{
|
||||
// Only required option is the component name
|
||||
ComponentName: "mycryptocomponent",
|
||||
})
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Next steps
|
||||
[Cryptography component specs]({{< ref supported-cryptography >}})
|
||||
|
|
@ -30,10 +30,12 @@ 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" >}}
|
||||
{{< tabs ".NET" Python >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--csharp-->
|
||||
|
||||
Define the workflow activities you'd like your workflow to perform. Activities are a class definition and can take inputs and outputs. Activities also participate in dependency injection, like binding to a Dapr client.
|
||||
|
||||
The activities called in the example below are:
|
||||
|
|
@ -96,6 +98,24 @@ public class ProcessPaymentActivity : WorkflowActivity<PaymentRequest, object>
|
|||
|
||||
[See the full `ProcessPaymentActivity.cs` workflow activity example.](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Activities/ProcessPaymentActivity.cs)
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--python-->
|
||||
|
||||
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 %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
|
@ -104,10 +124,12 @@ public class ProcessPaymentActivity : WorkflowActivity<PaymentRequest, object>
|
|||
|
||||
Next, register and call the activites in a workflow.
|
||||
|
||||
{{< tabs ".NET" >}}
|
||||
{{< tabs ".NET" Python >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--csharp-->
|
||||
|
||||
The `OrderProcessingWorkflow` class is derived from a base class called `Workflow` with input and output parameter types. It also includes a `RunAsync` method that does the heavy lifting of the workflow and calls the workflow activities.
|
||||
|
||||
```csharp
|
||||
|
|
@ -144,6 +166,28 @@ The `OrderProcessingWorkflow` class is derived from a base class called `Workflo
|
|||
|
||||
[See the full workflow example in `OrderProcessingWorkflow.cs`.](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Workflows/OrderProcessingWorkflow.cs)
|
||||
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--python-->
|
||||
|
||||
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 >}}
|
||||
|
|
@ -152,10 +196,12 @@ The `OrderProcessingWorkflow` class is derived from a base class called `Workflo
|
|||
|
||||
Finally, compose the application using the workflow.
|
||||
|
||||
{{< tabs ".NET" >}}
|
||||
{{< tabs ".NET" Python >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--csharp-->
|
||||
|
||||
[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
|
||||
|
|
@ -223,8 +269,97 @@ app.Run();
|
|||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
{{% codetab %}}
|
||||
|
||||
<!--python-->
|
||||
|
||||
[In the following example](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py), for a basic Python hello world application using the Python SDK, your project code would include:
|
||||
|
||||
- A Python package called `DaprClient` to receive the Python SDK capabilities.
|
||||
- A builder with extensions called:
|
||||
- `WorkflowRuntime`: Allows you to register workflows and workflow activities
|
||||
- `DaprWorkflowContext`: Allows you to [create workflows]({{< ref "#write-the-workflow" >}})
|
||||
- `WorkflowActivityContext`: Allows you to [create workflow activities]({{< ref "#write-the-workflow-activities" >}})
|
||||
- API calls. In the example below, these calls start, pause, resume, purge, and terminate the workflow.
|
||||
|
||||
```python
|
||||
from dapr.ext.workflow import WorkflowRuntime, DaprWorkflowContext, WorkflowActivityContext
|
||||
from dapr.clients import DaprClient
|
||||
|
||||
# ...
|
||||
|
||||
def main():
|
||||
with DaprClient() as d:
|
||||
host = settings.DAPR_RUNTIME_HOST
|
||||
port = settings.DAPR_GRPC_PORT
|
||||
workflowRuntime = WorkflowRuntime(host, port)
|
||||
workflowRuntime = WorkflowRuntime()
|
||||
workflowRuntime.register_workflow(hello_world_wf)
|
||||
workflowRuntime.register_activity(hello_act)
|
||||
workflowRuntime.start()
|
||||
|
||||
# Start workflow
|
||||
print("==========Start Counter Increase as per Input:==========")
|
||||
start_resp = d.start_workflow(instance_id=instanceId, workflow_component=workflowComponent,
|
||||
workflow_name=workflowName, input=inputData, workflow_options=workflowOptions)
|
||||
print(f"start_resp {start_resp.instance_id}")
|
||||
|
||||
# ...
|
||||
|
||||
# Pause workflow
|
||||
d.pause_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
print(f"Get response from {workflowName} after pause call: {getResponse.runtime_status}")
|
||||
|
||||
# Resume workflow
|
||||
d.resume_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
print(f"Get response from {workflowName} after resume call: {getResponse.runtime_status}")
|
||||
|
||||
sleep(1)
|
||||
# Raise workflow
|
||||
d.raise_workflow_event(instance_id=instanceId, workflow_component=workflowComponent,
|
||||
event_name=eventName, event_data=eventData)
|
||||
|
||||
sleep(5)
|
||||
# Purge workflow
|
||||
d.purge_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
try:
|
||||
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
except DaprInternalError as err:
|
||||
if nonExistentIDError in err._message:
|
||||
print("Instance Successfully Purged")
|
||||
|
||||
# Kick off another workflow for termination purposes
|
||||
start_resp = d.start_workflow(instance_id=instanceId, workflow_component=workflowComponent,
|
||||
workflow_name=workflowName, input=inputData, workflow_options=workflowOptions)
|
||||
print(f"start_resp {start_resp.instance_id}")
|
||||
|
||||
# Terminate workflow
|
||||
d.terminate_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
sleep(1)
|
||||
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
print(f"Get response from {workflowName} after terminate call: {getResponse.runtime_status}")
|
||||
|
||||
# Purge workflow
|
||||
d.purge_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
try:
|
||||
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
except DaprInternalError as err:
|
||||
if nonExistentIDError in err._message:
|
||||
print("Instance Successfully Purged")
|
||||
|
||||
workflowRuntime.shutdown()
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
```
|
||||
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
|
||||
{{% alert title="Important" color="warning" %}}
|
||||
|
|
@ -241,4 +376,6 @@ Now that you've authored a workflow, learn how to manage it.
|
|||
## Related links
|
||||
- [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 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)
|
||||
|
|
|
|||
|
|
@ -8,12 +8,12 @@ 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 SDK" HTTP >}}
|
||||
{{< tabs ".NET" Python HTTP >}}
|
||||
|
||||
<!--NET-->
|
||||
{{% codetab %}}
|
||||
|
||||
Manage your workflow within your code. In the `OrderProcessingWorkflow` example from the [Author a workflow]({{< ref "howto-author-workflow.md#write-the-workflow" >}}) guide, the workflow is registered in the code. You can now start, terminate, and get information about a running workflow:
|
||||
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";
|
||||
|
|
@ -46,6 +46,56 @@ await daprClient.PurgeWorkflowAsync(orderId, workflowComponent);
|
|||
|
||||
{{% /codetab %}}
|
||||
|
||||
<!--Python-->
|
||||
{{% codetab %}}
|
||||
|
||||
Manage your workflow within your code. In the workflow example from the [Author a workflow]({{< ref "howto-author-workflow.md#write-the-application" >}}) guide, the workflow is registered in the code using the following APIs:
|
||||
- **start_workflow**: Start an instance of a workflow
|
||||
- **get_workflow**: Get information on the status of the workflow
|
||||
- **pause_workflow**: Pauses or suspends a workflow instance that can later be resumed
|
||||
- **resume_workflow**: Resumes a paused workflow instance
|
||||
- **raise_workflow_event**: Raise an event on a workflow
|
||||
- **purge_workflow**: Removes all metadata related to a specific workflow instance
|
||||
- **terminate_workflow**: Terminate or stop a particular instance of a workflow
|
||||
|
||||
```python
|
||||
from dapr.ext.workflow import WorkflowRuntime, DaprWorkflowContext, WorkflowActivityContext
|
||||
from dapr.clients import DaprClient
|
||||
|
||||
# Sane parameters
|
||||
instanceId = "exampleInstanceID"
|
||||
workflowComponent = "dapr"
|
||||
workflowName = "hello_world_wf"
|
||||
eventName = "event1"
|
||||
eventData = "eventData"
|
||||
|
||||
# Start the workflow
|
||||
start_resp = d.start_workflow(instance_id=instanceId, workflow_component=workflowComponent,
|
||||
workflow_name=workflowName, input=inputData, workflow_options=workflowOptions)
|
||||
|
||||
# Get info on the workflow
|
||||
getResponse = d.get_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
|
||||
# Pause the workflow
|
||||
d.pause_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
|
||||
# Resume the workflow
|
||||
d.resume_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
|
||||
# Raise an event on the workflow.
|
||||
d.raise_workflow_event(instance_id=instanceId, workflow_component=workflowComponent,
|
||||
event_name=eventName, event_data=eventData)
|
||||
|
||||
# Purge the workflow
|
||||
d.purge_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
|
||||
# Terminate the workflow
|
||||
d.terminate_workflow(instance_id=instanceId, workflow_component=workflowComponent)
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
|
||||
<!--HTTP-->
|
||||
{{% codetab %}}
|
||||
|
||||
|
|
@ -121,5 +171,7 @@ 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 .NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
|
||||
- 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)
|
||||
- [Workflow API reference]({{< ref workflow_api.md >}})
|
||||
|
|
|
|||
|
|
@ -123,7 +123,9 @@ You can use the following SDKs to author a workflow.
|
|||
|
||||
| Language stack | Package |
|
||||
| - | - |
|
||||
| .NET | [Dapr.Workflow](https://www.nuget.org/packages/Dapr.Workflow) |
|
||||
| .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) |
|
||||
|
||||
|
||||
## Try out workflows
|
||||
|
||||
|
|
@ -135,6 +137,8 @@ Want to put workflows to the test? Walk through the following quickstart and tut
|
|||
| ------------------- | ----------- |
|
||||
| [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 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. |
|
||||
|
||||
|
||||
### Start using workflows directly in your app
|
||||
|
||||
|
|
@ -153,4 +157,6 @@ Watch [this video for an overview on Dapr Workflow](https://youtu.be/s1p9MNl4VGo
|
|||
## Related links
|
||||
|
||||
- [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 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)
|
||||
|
|
|
|||
|
|
@ -7,13 +7,13 @@ 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 is currently a preview feature only supported in Linux/MacOS.
|
||||
{{% /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:
|
||||
- Use the multi-app template
|
||||
- Use the multi-app template
|
||||
- View started applications
|
||||
- Stop the multi-app template
|
||||
- Stop the multi-app template
|
||||
- Stucture the multi-app template file
|
||||
|
||||
## Use the multi-app template
|
||||
|
|
@ -65,7 +65,7 @@ dapr stop -f ./path/to/<your-preferred-file-name>.yaml
|
|||
|
||||
## 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.
|
||||
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.
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
|
@ -77,15 +77,16 @@ apps:
|
|||
- appID: webapp # optional
|
||||
appDirPath: .dapr/webapp/ # REQUIRED
|
||||
resourcesPath: .dapr/resources # deprecated
|
||||
resourcesPaths: .dapr/resources # comman separated resources paths. (optional) can be default by convention
|
||||
resourcesPaths: .dapr/resources # comma separated resources paths. (optional) can be left to default value by convention.
|
||||
appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention.
|
||||
configFilePath: .dapr/config.yaml # (optional) can be default by convention too, ignore if file is not found.
|
||||
appProtocol: http
|
||||
appPort: 8080
|
||||
appHealthCheckPath: "/healthz"
|
||||
appHealthCheckPath: "/healthz"
|
||||
command: ["python3" "app.py"]
|
||||
appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole.
|
||||
daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file.
|
||||
- appID: backend # optional
|
||||
- appID: backend # optional
|
||||
appDirPath: .dapr/backend/ # REQUIRED
|
||||
appProtocol: grpc
|
||||
appPort: 3000
|
||||
|
|
@ -106,15 +107,16 @@ The following rules apply for all the paths present in the template file:
|
|||
|
||||
## Template properties
|
||||
|
||||
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" >}}).
|
||||
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" >}}).
|
||||
|
||||
|
||||
| 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` |
|
||||
| `resourcesPath` | N | **Deprecated**. Path to your Dapr resources. Can be default by convention| `./app/components`, `./webapp/components` |
|
||||
| `resourcesPaths` | N | Comma separated paths to your Dapr resources. Can be default by convention | `./app/components`, `./webapp/components` |
|
||||
| `resourcesPath` | N | **Deprecated**. Path to your Dapr resources. Can be default value by convention| `./app/components`, `./webapp/components` |
|
||||
| `resourcesPaths` | N | Comma separated paths to your Dapr resources. Can be default value by convention | `./app/components`, `./webapp/components` |
|
||||
| `appChannelAddress` | N | The network address the application listens on. Can be left to the default value by convention. | `127.0.0.1` | `localhost` |
|
||||
| `configFilePath` | N | Path to your application's configuration file | `./webapp/config.yaml` |
|
||||
| `appProtocol` | N | The protocol Dapr uses to talk to the application. | `http`, `grpc` |
|
||||
| `appPort` | N | The port your application is listening on | `8080`, `3000` |
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O
|
|||
The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`).
|
||||
|
||||
```bash
|
||||
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash -s 1.9.1
|
||||
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash -s {{% dapr-latest-version cli="true" %}}
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O
|
|||
The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`).
|
||||
|
||||
```bash
|
||||
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | DAPR_INSTALL_DIR="$HOME/dapr" /bin/bash -s 1.9.1
|
||||
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | DAPR_INSTALL_DIR="$HOME/dapr" /bin/bash -s {{% dapr-latest-version cli="true" %}}
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
|
@ -73,7 +73,7 @@ powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master
|
|||
The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`).
|
||||
|
||||
```powershell
|
||||
powershell -Command "$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList 1.9.1"
|
||||
powershell -Command "$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList {{% dapr-latest-version cli="true" %}}"
|
||||
```
|
||||
|
||||
#### Install without administrative rights
|
||||
|
|
@ -91,7 +91,7 @@ The following example shows how to install CLI version `{{% dapr-latest-version
|
|||
|
||||
```powershell
|
||||
$Env:DAPR_INSTALL_DIR = "<your_alt_install_dir_path>"
|
||||
$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList "1.9.1", "$Env:DAPR_INSTALL_DIR"
|
||||
$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList "{{% dapr-latest-version cli="true" %}}", "$Env:DAPR_INSTALL_DIR"
|
||||
```
|
||||
|
||||
#### Install using winget
|
||||
|
|
@ -136,7 +136,7 @@ curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh
|
|||
The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`).
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | /bin/bash -s 1.9.1
|
||||
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | /bin/bash -s {{% dapr-latest-version cli="true" %}}
|
||||
```
|
||||
|
||||
**For ARM64 Macs:**
|
||||
|
|
@ -177,7 +177,7 @@ curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh
|
|||
The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`).
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | DAPR_INSTALL_DIR="$HOME/dapr" -s 1.9.1
|
||||
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | DAPR_INSTALL_DIR="$HOME/dapr" -s {{% dapr-latest-version cli="true" %}}
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
|
|
|||
|
|
@ -31,3 +31,4 @@ Hit the ground running with our Dapr quickstarts, complete with code samples aim
|
|||
| [Configuration]({{< ref configuration-quickstart.md >}}) | Get configuration items and subscribe for configuration updates. |
|
||||
| [Resiliency]({{< ref resiliency >}}) | Define and apply fault-tolerance policies to your Dapr API requests. |
|
||||
| [Workflow]({{< ref workflow-quickstart.md >}}) | Orchestrate business workflow activities in long running, fault-tolerant, stateful applications. |
|
||||
| [Cryptography]({{< ref cryptography-quickstart.md >}}) | Encrypt and decrypt data using Dapr's cryptographic APIs. |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,288 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Quickstart: Cryptography"
|
||||
linkTitle: Cryptography
|
||||
weight: 79
|
||||
description: Get started with the Dapr Cryptography building block
|
||||
---
|
||||
|
||||
{{% alert title="Alpha" color="warning" %}}
|
||||
The cryptography building block is currently in **alpha**.
|
||||
{{% /alert %}}
|
||||
|
||||
Let's take a look at the Dapr [cryptography building block]({{< ref cryptography >}}). In this Quickstart, you'll create an application that encrypts and decrypts data using the Dapr cryptography APIs. You'll:
|
||||
|
||||
- Encrypt and then decrypt a short string (using an RSA key), reading the result in-memory, in a Go byte slice.
|
||||
- Encrypt and then decrypt a large file (using an AES key), storing the encrypted and decrypted data to files using streams.
|
||||
|
||||
<img src="/images/crypto-quickstart.png" width=800 style="padding-bottom:15px;">
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
This example uses the Dapr SDK, which leverages gRPC and is **strongly** recommended when using cryptographic APIs to encrypt and decrypt messages.
|
||||
{{% /alert %}}
|
||||
|
||||
Currently, you can experience the cryptography API using the Go SDK.
|
||||
|
||||
{{< tabs "Go" >}}
|
||||
|
||||
<!-- Go -->
|
||||
{{% codetab %}}
|
||||
|
||||
> This quickstart includes a Go application called `crypto-quickstart`.
|
||||
|
||||
### 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/).
|
||||
<!-- IGNORE_LINKS -->
|
||||
- [Docker Desktop](https://www.docker.com/products/docker-desktop)
|
||||
<!-- END_IGNORE -->
|
||||
- [OpenSSL](https://www.openssl.org/source/) available on your system
|
||||
|
||||
### Step 1: Set up the environment
|
||||
|
||||
Clone the [sample provided in the Quickstarts repo](https://github.com/dapr/quickstarts/tree/master/cryptography)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/dapr/quickstarts.git
|
||||
```
|
||||
|
||||
In the terminal, from the root directory, navigate to the cryptography sample.
|
||||
|
||||
```bash
|
||||
cd cryptography/go/sdk
|
||||
```
|
||||
|
||||
### Step 2: Run the application with Dapr
|
||||
|
||||
Navigate into the folder with the source code:
|
||||
|
||||
```bash
|
||||
cd ./crypto-quickstart
|
||||
```
|
||||
|
||||
The application code defines two required keys:
|
||||
- Private RSA key
|
||||
- A 256-bit symmetric (AES) key
|
||||
|
||||
Generate two keys, an RSA key and and AES key using OpenSSL and write these to two files:
|
||||
|
||||
```bash
|
||||
mkdir -p keys
|
||||
# Generate a private RSA key, 4096-bit keys
|
||||
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out keys/rsa-private-key.pem
|
||||
# Generate a 256-bit key for AES
|
||||
openssl rand -out keys/symmetric-key-256 32
|
||||
```
|
||||
|
||||
Run the Go service app with Dapr:
|
||||
|
||||
```bash
|
||||
dapr run --app-id crypto-quickstart --resources-path ../../../components/ -- go run .
|
||||
```
|
||||
|
||||
**Expected output**
|
||||
|
||||
```
|
||||
== APP == dapr client initializing for: 127.0.0.1:52407
|
||||
== APP == Encrypted the message, got 856 bytes
|
||||
== APP == Decrypted the message, got 24 bytes
|
||||
== APP == The secret is "passw0rd"
|
||||
== APP == Wrote decrypted data to encrypted.out
|
||||
== APP == Wrote decrypted data to decrypted.out.jpg
|
||||
```
|
||||
|
||||
### What happened?
|
||||
|
||||
#### `local-storage.yaml`
|
||||
|
||||
Earlier, you created a directory inside `crypto-quickstarts` called `keys`. In [the `local-storage` component YAML](https://github.com/dapr/quickstarts/tree/master/cryptography/components/local-storage.yaml), the `path` metadata maps to the newly created `keys` directory.
|
||||
|
||||
```yml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: localstorage
|
||||
spec:
|
||||
type: crypto.dapr.localstorage
|
||||
version: v1
|
||||
metadata:
|
||||
- name: path
|
||||
# Path is relative to the folder where the example is located
|
||||
value: ./keys
|
||||
```
|
||||
|
||||
#### `app.go`
|
||||
|
||||
[The application file](https://github.com/dapr/quickstarts/tree/master/cryptography/go/sdk/crypto-quickstart/app.go) encrypts and decrypts messages and files using the RSA and AES keys that you generated. The application creates a new Dapr SDK client:
|
||||
|
||||
```go
|
||||
func main() {
|
||||
// Create a new Dapr SDK client
|
||||
client, err := dapr.NewClient()
|
||||
|
||||
//...
|
||||
|
||||
// Step 1: encrypt a string using the RSA key, then decrypt it and show the output in the terminal
|
||||
encryptDecryptString(client)
|
||||
|
||||
// Step 2: encrypt a large file and then decrypt it, using the AES key
|
||||
encryptDecryptFile(client)
|
||||
}
|
||||
```
|
||||
|
||||
##### Encrypting and decrypting a string using the RSA key
|
||||
|
||||
Once the client is created, the application encrypts a message:
|
||||
|
||||
```go
|
||||
func encryptDecryptString(client dapr.Client) {
|
||||
// ...
|
||||
|
||||
// Encrypt the message
|
||||
encStream, err := client.Encrypt(context.Background(),
|
||||
strings.NewReader(message),
|
||||
dapr.EncryptOptions{
|
||||
ComponentName: CryptoComponentName,
|
||||
// Name of the key to use
|
||||
// Since this is a RSA key, we specify that as key wrapping algorithm
|
||||
KeyName: RSAKeyName,
|
||||
KeyWrapAlgorithm: "RSA",
|
||||
},
|
||||
)
|
||||
|
||||
// ...
|
||||
|
||||
// The method returns a readable stream, which we read in full in memory
|
||||
encBytes, err := io.ReadAll(encStream)
|
||||
// ...
|
||||
|
||||
fmt.Printf("Encrypted the message, got %d bytes\n", len(encBytes))
|
||||
```
|
||||
|
||||
The application then decrypts the message:
|
||||
|
||||
```go
|
||||
// Now, decrypt the encrypted data
|
||||
decStream, err := client.Decrypt(context.Background(),
|
||||
bytes.NewReader(encBytes),
|
||||
dapr.DecryptOptions{
|
||||
// We just need to pass the name of the component
|
||||
ComponentName: CryptoComponentName,
|
||||
// Passing the name of the key is optional
|
||||
KeyName: RSAKeyName,
|
||||
},
|
||||
)
|
||||
|
||||
// ...
|
||||
|
||||
// The method returns a readable stream, which we read in full in memory
|
||||
decBytes, err := io.ReadAll(decStream)
|
||||
|
||||
// ...
|
||||
|
||||
// Print the message on the console
|
||||
fmt.Printf("Decrypted the message, got %d bytes\n", len(decBytes))
|
||||
fmt.Println(string(decBytes))
|
||||
}
|
||||
```
|
||||
|
||||
##### Encrypt and decrpyt a large file using the AES key
|
||||
|
||||
Next, the application encrypts a large image file:
|
||||
|
||||
```go
|
||||
func encryptDecryptFile(client dapr.Client) {
|
||||
const fileName = "liuguangxi-66ouBTTs_x0-unsplash.jpg"
|
||||
|
||||
// Get a readable stream to the input file
|
||||
plaintextF, err := os.Open(fileName)
|
||||
|
||||
// ...
|
||||
|
||||
defer plaintextF.Close()
|
||||
|
||||
// Encrypt the file
|
||||
encStream, err := client.Encrypt(context.Background(),
|
||||
plaintextF,
|
||||
dapr.EncryptOptions{
|
||||
ComponentName: CryptoComponentName,
|
||||
// Name of the key to use
|
||||
// Since this is a symmetric key, we specify AES as key wrapping algorithm
|
||||
KeyName: SymmetricKeyName,
|
||||
KeyWrapAlgorithm: "AES",
|
||||
},
|
||||
)
|
||||
|
||||
// ...
|
||||
|
||||
// Write the encrypted data to a file "encrypted.out"
|
||||
encryptedF, err := os.Create("encrypted.out")
|
||||
|
||||
// ...
|
||||
|
||||
encryptedF.Close()
|
||||
|
||||
fmt.Println("Wrote decrypted data to encrypted.out")
|
||||
```
|
||||
|
||||
The application then decrypts the large image file:
|
||||
|
||||
```go
|
||||
// Now, decrypt the encrypted data
|
||||
// First, open the file "encrypted.out" again, this time for reading
|
||||
encryptedF, err = os.Open("encrypted.out")
|
||||
|
||||
// ...
|
||||
|
||||
defer encryptedF.Close()
|
||||
|
||||
// Now, decrypt the encrypted data
|
||||
decStream, err := client.Decrypt(context.Background(),
|
||||
encryptedF,
|
||||
dapr.DecryptOptions{
|
||||
// We just need to pass the name of the component
|
||||
ComponentName: CryptoComponentName,
|
||||
// Passing the name of the key is optional
|
||||
KeyName: SymmetricKeyName,
|
||||
},
|
||||
)
|
||||
|
||||
// ...
|
||||
|
||||
// Write the decrypted data to a file "decrypted.out.jpg"
|
||||
decryptedF, err := os.Create("decrypted.out.jpg")
|
||||
|
||||
// ...
|
||||
|
||||
decryptedF.Close()
|
||||
|
||||
fmt.Println("Wrote decrypted data to decrypted.out.jpg")
|
||||
}
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Watch the demo
|
||||
|
||||
Watch this [demo video of the cryptography API from the Dapr Community Call #83](https://youtu.be/PRWYX4lb2Sg?t=1148):
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/PRWYX4lb2Sg?start=1148" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
|
||||
|
||||
## Tell us what you think!
|
||||
|
||||
We're continuously working to improve our Quickstart examples and value your feedback. Did you find this Quickstart helpful? Do you have suggestions for improvement?
|
||||
|
||||
Join the discussion in our [discord channel](https://discord.com/channels/778680217417809931/953427615916638238).
|
||||
|
||||
## Next steps
|
||||
|
||||
- Walk through [more examples of encrypting and decrypting using the cryptography API]({{< ref howto-cryptography.md >}})
|
||||
- Learn more about [cryptography as a Dapr building block]({{< ref cryptography-overview.md >}})
|
||||
|
||||
{{< button text="Explore Dapr tutorials >>" page="getting-started/tutorials/_index.md" >}}
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Alpha APIs"
|
||||
linkTitle: "Alpha APIs"
|
||||
weight: 5000
|
||||
description: "List of current alpha APIs"
|
||||
---
|
||||
|
||||
| Building block/API | gRPC | HTTP | Description | Documentation | Version introduced |
|
||||
| ------------------ | ---- | ---- | ----------- | ------------- | ------------------ |
|
||||
| Query State | [Query State proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L44) | `v1.0-alpha1/state/statestore/query` | The state query API enables you to retrieve, filter, and sort the key/value data stored in state store components. | [Query State API]({{< ref "howto-state-query-api.md" >}}) | v1.5 |
|
||||
| Distributed Lock | [Lock proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L112) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource. | [Distributed Lock API]({{< ref "distributed-lock-api-overview.md" >}}) | v1.8 |
|
||||
| Workflow | [Workflow proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L151) | `/v1.0-alpha1/workflow` | The workflow API enables you to define long running, persistent processes or data flows. | [Workflow API]({{< ref "workflow-overview.md" >}}) | v1.10 |
|
||||
| Bulk Publish | [Bulk publish proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L59) | `v1.0-alpha1/publish/bulk` | The bulk publish API allows you to publish multiple messages to a topic in a single request. | [Bulk Publish and Subscribe API]({{< ref "pubsub-bulk.md" >}}) | v1.10 |
|
||||
| Bulk Subscribe | [Bulk subscribe proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/appcallback.proto#L57) | N/A | The bulk subscribe application callback receives multiple messages from a topic in a single call. | [Bulk Publish and Subscribe API]({{< ref "pubsub-bulk.md" >}}) | v1.10 |
|
||||
| Cryptography | [Crypto proto](https://github.com/dapr/dapr/blob/5aba3c9aa4ea9b3f388df125f9c66495b43c5c9e/dapr/proto/runtime/v1/dapr.proto#L118) | `v1.0-alpha1/crypto` | The cryptography API enables you to perform **high level** cryptography operations for encrypting and decrypting messages. | [Cryptography API]({{< ref "cryptography-overview.md" >}}) | v1.11 |
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Breaking changes and deprecations"
|
||||
linkTitle: "Breaking changes and deprecations"
|
||||
weight: 2500
|
||||
description: "Handling of breaking changes and deprecations"
|
||||
---
|
||||
|
||||
## Breaking changes
|
||||
|
||||
Breaking changes are defined as a change to any of the following that cause compilation errors or undesirable runtime behavior to an existing 3rd party consumer application or script after upgrading to the next stable minor version of a Dapr artifact (SDK, CLI, runtime, etc):
|
||||
|
||||
- Code behavior
|
||||
- Schema
|
||||
- Default configuration value
|
||||
- Command line argument
|
||||
- Published metric
|
||||
- Kubernetes CRD template
|
||||
- Publicly accessible API
|
||||
- Publicly visible SDK interface, method, class, or attribute
|
||||
|
||||
Breaking changes can be applied right away to the following cases:
|
||||
|
||||
- Projects versioned at 0.x.y
|
||||
- Preview feature
|
||||
- Alpha API
|
||||
- Preview or Alpha interface, class, method or attribute in SDK
|
||||
- Dapr Component in Alpha or Beta
|
||||
- Components-Contrib interface
|
||||
- URLs in Docs and Blog
|
||||
- An **exceptional** case where it is **required** to fix a critical bug or security vulnerability.
|
||||
|
||||
### Process for applying breaking changes
|
||||
|
||||
There is a process for applying breaking changes:
|
||||
|
||||
1. A deprecation notice must be posted as part of a release.
|
||||
1. The breaking changes are applied two (2) releases after the release in which the deprecation was announced.
|
||||
- For example, feature X is announced to be deprecated in the 1.0.0 release notes and will then be removed in 1.2.0.
|
||||
|
||||
## Deprecations
|
||||
|
||||
Deprecations appear in release notes under a section named “Deprecations”, which indicates:
|
||||
|
||||
- The point in the future the now-deprecated feature will no longer be supported. For example release x.y.z. This is at least two (2) releases prior.
|
||||
- Document any steps the user must take to modify their code, operations, etc if applicable in the release notes.
|
||||
|
||||
After announcing a future breaking change, the change will happen in 2 releases or 6 months, whichever is greater. Deprecated features should respond with warning but do nothing otherwise.
|
||||
|
||||
|
||||
## Announced deprecations
|
||||
|
||||
| Feature | Deprecation announcement | Removal |
|
||||
|-----------------------|-----------------------|------------------------- |
|
||||
| GET /v1.0/shutdown API (Users should use [POST API]({{< ref kubernetes-job.md >}}) instead) | 1.2.0 | 1.4.0 |
|
||||
| Java domain builder classes deprecated (Users should use [setters](https://github.com/dapr/java-sdk/issues/587) instead) | Java SDK 1.3.0 | Java SDK 1.5.0 |
|
||||
| Service invocation will no longer provide a default content type header of `application/json` when no content-type is specified. You must explicitly [set a content-type header]({{< ref "service_invocation_api.md#request-contents" >}}) for service invocation if your invoked apps rely on this header. | 1.7.0 | 1.9.0 |
|
||||
| gRPC service invocation using `invoke` method is deprecated. Use proxy mode service invocation instead. See [How-To: Invoke services using gRPC ]({{< ref howto-invoke-services-grpc.md >}}) to use the proxy mode.| 1.9.0 | 1.10.0 |
|
||||
|
||||
## Related links
|
||||
|
||||
- Read the [Versioning Policy]({{< ref support-versioning.md >}})
|
||||
- Read the [Supported Releases]({{< ref support-release-policy.md >}})
|
||||
|
|
@ -20,6 +20,7 @@ For CLI there is no explicit opt-in, just the version that this was first made a
|
|||
| **Pluggable components** | Allows creating self-hosted gRPC-based components written in any language that supports gRPC. The following component APIs are supported: State stores, Pub/sub, Bindings | N/A | [Pluggable components concept]({{<ref "components-concept#pluggable-components" >}})| 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 |
|
||||
| **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 |
|
||||
|
||||
|
|
|
|||
|
|
@ -28,6 +28,17 @@ There will be at least 6 weeks between major.minor version releases giving users
|
|||
|
||||
Patch support is for supported versions (current and previous).
|
||||
|
||||
## Build variations
|
||||
|
||||
The Dapr's sidecar image is published to both [GitHub Container Registry](https://github.com/dapr/dapr/pkgs/container/daprd) and [Docker Registry](https://hub.docker.com/r/daprio/daprd/tags). The default image contains all components. From version 1.11, Dapr also offers a variation of the sidecar image, containing only stable components.
|
||||
|
||||
* Default sidecar images: `daprio/daprd:<version>` or `ghcr.io/dapr/daprd:<version>` (for example `ghcr.io/dapr/daprd:1.11.0`)
|
||||
* Sidecar images for stable components: `daprio/daprd:<version>-stable` or `ghcr.io/dapr/daprd:<version>-stable` (for example `ghcr.io/dapr/daprd:1.11.0-stable`)
|
||||
|
||||
On Kubernetes, the sidecar image can be overwritten for the application Deployment resource with the `dapr.io/sidecar-image` annotation. See more about [Dapr's arguments and annotations]({{<ref "arguments-annotations-overview.md" >}}). The default 'daprio/daprd:latest' image is used if not specified.
|
||||
|
||||
Learn more about [Dapr components' certification lifecycle]({{<ref "certification-lifecycle.md" >}}).
|
||||
|
||||
## Supported versions
|
||||
|
||||
The table below shows the versions of Dapr releases that have been tested together and form a "packaged" release. Any other combinations of releases are not supported.
|
||||
|
|
@ -106,59 +117,6 @@ General guidance on upgrading can be found for [self hosted mode]({{< ref self-h
|
|||
| 1.9.0 | N/A | 1.9.6 |
|
||||
| 1.10.0 | N/A | 1.10.7 |
|
||||
|
||||
## Breaking changes and deprecations
|
||||
|
||||
### Breaking changes
|
||||
|
||||
Breaking changes are defined as a change to any of the following that cause compilation errors or undesirable runtime behavior to an existing 3rd party consumer application or script after upgrading to the next stable minor version of a Dapr artifact (SDK, CLI, runtime, etc):
|
||||
|
||||
- Code behavior
|
||||
- Schema
|
||||
- Default configuration value
|
||||
- Command line argument
|
||||
- Published metric
|
||||
- Kubernetes CRD template
|
||||
- Publicly accessible API
|
||||
- Publicly visible SDK interface, method, class, or attribute
|
||||
|
||||
Breaking changes can be applied right away to the following cases:
|
||||
|
||||
- Projects versioned at 0.x.y
|
||||
- Preview feature
|
||||
- Alpha API
|
||||
- Preview or Alpha interface, class, method or attribute in SDK
|
||||
- Dapr Component in Alpha or Beta
|
||||
- Components-Contrib interface
|
||||
- URLs in Docs and Blog
|
||||
- An **exceptional** case where it is **required** to fix a critical bug or security vulnerability.
|
||||
|
||||
#### Process for applying breaking changes
|
||||
|
||||
There is a process for applying breaking changes:
|
||||
|
||||
1. A deprecation notice must be posted as part of a release.
|
||||
1. The breaking changes are applied two (2) releases after the release in which the deprecation was announced.
|
||||
- For example, feature X is announced to be deprecated in the 1.0.0 release notes and will then be removed in 1.2.0.
|
||||
|
||||
### Depreciations
|
||||
|
||||
Deprecations appear in release notes under a section named “Deprecations”, which indicates:
|
||||
|
||||
- The point in the future the now-deprecated feature will no longer be supported. For example release x.y.z. This is at least two (2) releases prior.
|
||||
- Document any steps the user must take to modify their code, operations, etc if applicable in the release notes.
|
||||
|
||||
After announcing a future breaking change, the change will happen in 2 releases or 6 months, whichever is greater. Deprecated features should respond with warning but do nothing otherwise.
|
||||
|
||||
|
||||
### Announced deprecations
|
||||
|
||||
| Feature | Deprecation announcement | Removal |
|
||||
|-----------------------|-----------------------|------------------------- |
|
||||
| GET /v1.0/shutdown API (Users should use [POST API]({{< ref kubernetes-job.md >}}) instead) | 1.2.0 | 1.4.0 |
|
||||
| Java domain builder classes deprecated (Users should use [setters](https://github.com/dapr/java-sdk/issues/587) instead) | Java SDK 1.3.0 | Java SDK 1.5.0 |
|
||||
| Service invocation will no longer provide a default content type header of `application/json` when no content-type is specified. You must explicitly [set a content-type header]({{< ref "service_invocation_api.md#request-contents" >}}) for service invocation if your invoked apps rely on this header. | 1.7.0 | 1.9.0 |
|
||||
| gRPC service invocation using `invoke` method is deprecated. Use proxy mode service invocation instead. See [How-To: Invoke services using gRPC ]({{< ref howto-invoke-services-grpc.md >}}) to use the proxy mode.| 1.9.0 | 1.10.0 |
|
||||
|
||||
## Upgrade on Hosting platforms
|
||||
|
||||
Dapr can support multiple hosting platforms for production. With the 1.0 release the two supported platforms are Kubernetes and physical machines. For Kubernetes upgrades see [Production guidelines on Kubernetes]({{< ref kubernetes-production.md >}})
|
||||
|
|
@ -175,4 +133,5 @@ Below is a list of software that the latest version of Dapr (v{{% dapr-latest-ve
|
|||
|
||||
## Related links
|
||||
|
||||
- Read the [Versioning policy]({{< ref support-versioning.md >}})
|
||||
- Read the [Versioning Policy]({{< ref support-versioning.md >}})
|
||||
- Read the [Breaking Changes and Deprecation Policy]({{< ref breaking-changes-and-deprecations.md >}})
|
||||
|
|
|
|||
|
|
@ -12,8 +12,8 @@ Dapr provides users with the ability to interact with workflows and comes with a
|
|||
|
||||
Start a workflow instance with the given name and optionally, an instance ID.
|
||||
|
||||
```http
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/start[?instanceId=<instanceId>]
|
||||
```
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/start[?instanceID=<instanceID>]
|
||||
```
|
||||
|
||||
Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
|
||||
|
|
@ -24,7 +24,7 @@ Parameter | Description
|
|||
--------- | -----------
|
||||
`workflowComponentName` | Use `dapr` for Dapr Workflows
|
||||
`workflowName` | Identify the workflow type
|
||||
`instanceId` | (Optional) Unique value created for each run of a specific workflow
|
||||
`instanceID` | (Optional) Unique value created for each run of a specific workflow
|
||||
|
||||
### Request content
|
||||
|
||||
|
|
@ -52,8 +52,8 @@ The API call will provide a response similar to this:
|
|||
|
||||
Terminate a running workflow instance with the given name and instance ID.
|
||||
|
||||
```http
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<instanceId>/terminate
|
||||
```
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/terminate
|
||||
```
|
||||
|
||||
### URL parameters
|
||||
|
|
@ -79,7 +79,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.
|
||||
|
||||
```http
|
||||
```
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceID>/raiseEvent/<eventName>
|
||||
```
|
||||
|
||||
|
|
@ -112,7 +112,7 @@ None.
|
|||
|
||||
Pause a running workflow instance.
|
||||
|
||||
```http
|
||||
```
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/pause
|
||||
```
|
||||
|
||||
|
|
@ -139,7 +139,7 @@ None.
|
|||
|
||||
Resume a paused workflow instance.
|
||||
|
||||
```http
|
||||
```
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/resume
|
||||
```
|
||||
|
||||
|
|
@ -166,7 +166,7 @@ None.
|
|||
|
||||
Purge the workflow state from your state store with the workflow's instance ID.
|
||||
|
||||
```http
|
||||
```
|
||||
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/purge
|
||||
```
|
||||
|
||||
|
|
@ -193,7 +193,7 @@ None.
|
|||
|
||||
Get information about a given workflow instance.
|
||||
|
||||
```http
|
||||
```
|
||||
GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ This table is meant to help users understand the equivalent options for running
|
|||
| `--dapr-http-port` | `--dapr-http-port` | | not supported | The HTTP port for the Dapr API |
|
||||
| `--dapr-http-max-request-size` | --dapr-http-max-request-size | | `dapr.io/http-max-request-size` | Increasing max size of request body http and grpc servers parameter in MB to handle uploading of big files. Default is `4` MB |
|
||||
| `--dapr-http-read-buffer-size` | --dapr-http-read-buffer-size | | `dapr.io/http-read-buffer-size` | Increasing max size of http header read buffer in KB to handle when sending multi-KB headers. The default 4 KB. When sending bigger than default 4KB http headers, you should set this to a larger value, for example 16 (for 16KB) |
|
||||
| not supported | `--image` | | `dapr.io/sidecar-image` | Dapr sidecar image. Default is `daprio/daprd:latest`. Use this when building your own custom image of Dapr and the Dapr sidecar will use this image instead of the default image of Dapr |
|
||||
| not supported | `--image` | | `dapr.io/sidecar-image` | Dapr sidecar image. Default is daprio/daprd:latest. The Dapr sidecar uses this image instead of the latest default image. Use this when building your own custom image of Dapr and or [using an alternative stable Dapr image]({{<ref "support-release-policy.md#build-variations" >}}) |
|
||||
| `--internal-grpc-port` | not supported | | not supported | gRPC port for the Dapr Internal API to listen on |
|
||||
| `--enable-metrics` | not supported | | configuration spec | Enable prometheus metric (default true) |
|
||||
| `--enable-mtls` | not supported | | configuration spec | Enables automatic mTLS for daprd to daprd communication channels |
|
||||
|
|
|
|||
|
|
@ -28,6 +28,7 @@ dapr run [flags] [command]
|
|||
| `--app-port`, `-p` | `APP_PORT` | | The port your application is listening on |
|
||||
| `--app-protocol`, `-P` | | `http` | The protocol Dapr uses to talk to the application. Valid values are: `http`, `grpc`, `https` (HTTP with TLS), `grpcs` (gRPC with TLS), `h2c` (HTTP/2 Cleartext) |
|
||||
| `--resources-path`, `-d` | | Linux/Mac: `$HOME/.dapr/components` <br/>Windows: `%USERPROFILE%\.dapr\components` | The path for components directory |
|
||||
| `--app-channel-address` | | `127.0.0.1` | The network address the application listens on |
|
||||
| `--runtime-path` | | | Dapr runtime install path |
|
||||
| `--config`, `-c` | | Linux/Mac: `$HOME/.dapr/config.yaml` <br/>Windows: `%USERPROFILE%\.dapr\config.yaml` | Dapr configuration file |
|
||||
| `--dapr-grpc-port`, `-G` | `DAPR_GRPC_PORT` | `50001` | The gRPC port for Dapr to listen on |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,117 @@
|
|||
---
|
||||
type: docs
|
||||
title: "PostgreSQL"
|
||||
linkTitle: "PostgreSQL"
|
||||
description: Detailed information on the PostgreSQL configuration store component
|
||||
aliases:
|
||||
- "/operations/components/setup-configuration-store/supported-configuration-stores/setup-postgresql/"
|
||||
- "/operations/components/setup-configuration-store/supported-configuration-stores/setup-postgres/"
|
||||
---
|
||||
|
||||
## Component format
|
||||
|
||||
To set up an PostgreSQL configuration store, create a component of type `configuration.postgresql`
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: <NAME>
|
||||
spec:
|
||||
type: configuration.postgresql
|
||||
version: v1
|
||||
metadata:
|
||||
- name: connectionString
|
||||
value: "host=localhost user=postgres password=example port=5432 connect_timeout=10 database=config"
|
||||
- name: table # name of the table which holds configuration information
|
||||
value: "[your_configuration_table_name]"
|
||||
- name: connMaxIdleTime # max timeout for connection
|
||||
value : "15s"
|
||||
|
||||
```
|
||||
|
||||
{{% 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
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| connectionString | Y | The connection string for PostgreSQL. Default pool_max_conns = 5 | `"host=localhost user=postgres password=example port=5432 connect_timeout=10 database=dapr_test pool_max_conns=10"`
|
||||
| table | Y | Table name for configuration information, must be lowercased. | `configtable`
|
||||
|
||||
## Set up PostgreSQL as Configuration Store
|
||||
|
||||
1. Start PostgreSQL Database
|
||||
1. Connect to the PostgreSQL database and setup a configuration table with following schema -
|
||||
|
||||
| Field | Datatype | Nullable |Details |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| KEY | VARCHAR | N |Holds `"Key"` of the configuration attribute |
|
||||
| VALUE | VARCHAR | N |Holds Value of the configuration attribute |
|
||||
| VERSION | VARCHAR | N | Holds version of the configuration attribute
|
||||
| METADATA | JSON | Y | Holds Metadata as JSON
|
||||
|
||||
```console
|
||||
CREATE TABLE IF NOT EXISTS table_name (
|
||||
KEY VARCHAR NOT NULL,
|
||||
VALUE VARCHAR NOT NULL,
|
||||
VERSION VARCHAR NOT NULL,
|
||||
METADATA JSON );
|
||||
```
|
||||
3. Create a TRIGGER on configuration table. An example function to create a TRIGGER is as follows -
|
||||
```console
|
||||
CREATE OR REPLACE FUNCTION configuration_event() RETURNS TRIGGER AS $$
|
||||
DECLARE
|
||||
data json;
|
||||
notification json;
|
||||
|
||||
BEGIN
|
||||
|
||||
IF (TG_OP = 'DELETE') THEN
|
||||
data = row_to_json(OLD);
|
||||
ELSE
|
||||
data = row_to_json(NEW);
|
||||
END IF;
|
||||
|
||||
notification = json_build_object(
|
||||
'table',TG_TABLE_NAME,
|
||||
'action', TG_OP,
|
||||
'data', data);
|
||||
|
||||
PERFORM pg_notify('config',notification::text);
|
||||
RETURN NULL;
|
||||
END;
|
||||
$$ LANGUAGE plpgsql;
|
||||
```
|
||||
4. Create the trigger with data encapsulated in the field labelled as `data`
|
||||
```ps
|
||||
notification = json_build_object(
|
||||
'table',TG_TABLE_NAME,
|
||||
'action', TG_OP,
|
||||
'data', data);
|
||||
```
|
||||
5. The channel mentioned as attribute to `pg_notify` should be used when subscribing for configuration notifications
|
||||
6. Since this is a generic created trigger, map this trigger to `configuration table`
|
||||
```console
|
||||
CREATE TRIGGER config
|
||||
AFTER INSERT OR UPDATE OR DELETE ON configtable
|
||||
FOR EACH ROW EXECUTE PROCEDURE notify_event();
|
||||
```
|
||||
7. In the subscribe request add an additional metadata field with key as `pgNotifyChannel` and value should be set to same `channel name` mentioned in `pg_notify`. From the above example, it should be set to `config`
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
When calling `subscribe` API, `metadata.pgNotifyChannel` should be used to specify the name of the channel to listen for notifications from PostgreSQL configuration store.
|
||||
|
||||
Any number of keys can be added to a subscription request. Each subscription uses an exclusive database connection. It is strongly recommended to subscribe to multiple keys within a single subscription. This helps optimize the number of connections to the database.
|
||||
|
||||
Example of subscribe HTTP API -
|
||||
```ps
|
||||
curl --location --request GET 'http://<host>:<dapr-http-port>/configuration/mypostgresql/subscribe?key=<keyname1>&key=<keyname2>&metadata.pgNotifyChannel=<channel name>'
|
||||
```
|
||||
{{% /alert %}}
|
||||
|
||||
## Related links
|
||||
- [Basic schema for a Dapr component]({{< ref component-schema >}})
|
||||
- [Configuration building block]({{< ref configuration-api-overview >}})
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Cryptography component specs"
|
||||
linkTitle: "Cryptography"
|
||||
weight: 7000
|
||||
description: The supported cryptography components that interface with Dapr
|
||||
no_list: true
|
||||
---
|
||||
|
||||
{{< partial "components/description.html" >}}
|
||||
|
||||
{{< partial "components/cryptography.html" >}}
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Azure Key Vault"
|
||||
linkTitle: "Azure Key Vault"
|
||||
description: Detailed information on the Azure Key Vault cryptography component
|
||||
---
|
||||
|
||||
## Component format
|
||||
|
||||
A Dapr `crypto.yaml` component file has the following structure:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: azurekeyvault
|
||||
spec:
|
||||
type: crypto.azure.keyvault
|
||||
metadata:
|
||||
- name: vaultName
|
||||
value: mykeyvault
|
||||
# See authentication section below for all options
|
||||
- name: azureTenantId
|
||||
value: ${{AzureKeyVaultTenantId}}
|
||||
- name: azureClientId
|
||||
value: ${{AzureKeyVaultServicePrincipalClientId}}
|
||||
- name: azureClientSecret
|
||||
value: ${{AzureKeyVaultServicePrincipalClientSecret}}
|
||||
```
|
||||
|
||||
{{% 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 %}}
|
||||
|
||||
## Authenticating with Azure AD
|
||||
|
||||
The Azure Key Vault cryptography component supports authentication with Azure AD only. Before you enable this component:
|
||||
|
||||
1. Read the [Authenticating to Azure]({{< ref "authenticating-azure.md" >}}) document.
|
||||
1. Create an [Azure AD application]({{< ref "howto-aad.md" >}}) (also called a Service Principal).
|
||||
1. Alternatively, create a [managed identity]({{< ref "howto-msi.md" >}}) for your application platform.
|
||||
|
||||
## Spec metadata fields
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| `vaultName` | Y | Azure Key Vault name | `"mykeyvault"` |
|
||||
| Auth metadata | Y | See [Authenticating to Azure]({{< ref "authenticating-azure.md" >}}) for more information | |
|
||||
|
||||
## Related links
|
||||
- [Cryptography building block]({{< ref cryptography >}})
|
||||
- [Authenticating to Azure]({{< ref azure-authentication >}})
|
||||
|
|
@ -0,0 +1,79 @@
|
|||
---
|
||||
type: docs
|
||||
title: "JSON Web Key Sets (JWKS)"
|
||||
linkTitle: "JSON Web Key Sets (JWKS)"
|
||||
description: Detailed information on the JWKS cryptography component
|
||||
---
|
||||
|
||||
## Component format
|
||||
|
||||
The purpose of this component is to load keys from a JSON Web Key Set ([RFC 7517](https://www.rfc-editor.org/rfc/rfc7517)). These are JSON documents that contain 1 or more keys as JWK (JSON Web Key); they can be public, private, or shared keys.
|
||||
|
||||
This component supports loading a JWKS:
|
||||
|
||||
- From a local file; in this case, Dapr watches for changes to the file on disk and reloads it automatically.
|
||||
- From a HTTP(S) URL, which is periodically refreshed.
|
||||
- By passing the actual JWKS in the `jwks` metadata property, as a string (optionally, base64-encoded).
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
This component uses the cryptographic engine in Dapr to perform operations. Although keys are never exposed to your application, Dapr has access to the raw key material.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
A Dapr `crypto.yaml` component file has the following structure:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: jwks
|
||||
spec:
|
||||
type: crypto.dapr.jwks
|
||||
version: v1
|
||||
metadata:
|
||||
# Example 1: load JWKS from file
|
||||
- name: "jwks"
|
||||
value: "fixtures/crypto/jwks/jwks.json"
|
||||
# Example 2: load JWKS from a HTTP(S) URL
|
||||
# Only "jwks" is required
|
||||
- name: "jwks"
|
||||
value: "https://example.com/.well-known/jwks.json"
|
||||
- name: "requestTimeout"
|
||||
value: "30s"
|
||||
- name: "minRefreshInterval"
|
||||
value: "10m"
|
||||
# Option 3: include the actual JWKS
|
||||
- name: "jwks"
|
||||
value: |
|
||||
{
|
||||
"keys": [
|
||||
{
|
||||
"kty": "RSA",
|
||||
"use": "sig",
|
||||
"kid": "…",
|
||||
"n": "…",
|
||||
"e": "…",
|
||||
"issuer": "https://example.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
# Option 3b: include the JWKS base64-encoded
|
||||
- name: "jwks"
|
||||
value: |
|
||||
eyJrZXlzIjpbeyJ…
|
||||
```
|
||||
|
||||
{{% 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
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| `jwks` | Y | Path to the JWKS document | Local file: `"fixtures/crypto/jwks/jwks.json"`<br>HTTP(S) URL: `"https://example.com/.well-known/jwks.json"`<br>Embedded JWKS: `{"keys": […]}` (can be base64-encoded)
|
||||
| `requestTimeout` | N | Timeout for network requests when fetching the JWKS document from a HTTP(S) URL, as a Go duration. Default: "30s" | `"5s"`
|
||||
| `minRefreshInterval` | N | Minimum interval to wait before subsequent refreshes of the JWKS document from a HTTP(S) source, as a Go duration. Default: "10m" | `"1h"`
|
||||
|
||||
## Related links
|
||||
[Cryptography building block]({{< ref cryptography >}})
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Kubernetes Secrets"
|
||||
linkTitle: "Kubernetes Secrets"
|
||||
description: Detailed information on the Kubernetes secret cryptography component
|
||||
---
|
||||
|
||||
## Component format
|
||||
|
||||
The purpose of this component is to load the Kubernetes secret named after the key name.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
This component uses the cryptographic engine in Dapr to perform operations. Although keys are never exposed to your application, Dapr has access to the raw key material.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
A Dapr `crypto.yaml` component file has the following structure:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: <NAME>
|
||||
spec:
|
||||
type: crypto.dapr.kubernetes.secrets
|
||||
version: v1
|
||||
metadata:[]
|
||||
```
|
||||
|
||||
{{% 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
|
||||
|
||||
For the Kubernetes secret store component, there are no metadata attributes.
|
||||
|
||||
## Related links
|
||||
[Cryptography building block]({{< ref cryptography >}})
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Local storage"
|
||||
linkTitle: "Local storage"
|
||||
description: Detailed information on the local storage cryptography component
|
||||
---
|
||||
|
||||
## Component format
|
||||
|
||||
The purpose of this component is to load keys from a local directory.
|
||||
|
||||
The component accepts as input the name of a folder, and loads keys from there. Each key is in its own file, and when users request a key with a given name, Dapr loads the file with that name.
|
||||
|
||||
Supported file formats:
|
||||
|
||||
- PEM with public and private keys (supports: PKCS#1, PKCS#8, PKIX)
|
||||
- JSON Web Key (JWK) containing a public, private, or symmetric key
|
||||
- Raw key data for symmetric keys
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
This component uses the cryptographic engine in Dapr to perform operations. Although keys are never exposed to your application, Dapr has access to the raw key material.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
|
||||
A Dapr `crypto.yaml` component file has the following structure:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: mycrypto
|
||||
spec:
|
||||
type: crypto.dapr.localstorage
|
||||
metadata:
|
||||
version: v1
|
||||
- name: path
|
||||
value: /path/to/folder/
|
||||
```
|
||||
|
||||
{{% 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
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| `path` | Y | Folder containing the keys to be loaded. When loading a key, the name of the key will be used as name of the file in this folder. | `/path/to/folder` |
|
||||
|
||||
**Example**
|
||||
|
||||
Let's say you've set `path=/mnt/keys`, which contains the following files:
|
||||
|
||||
- `/mnt/keys/mykey1.pem`
|
||||
- `/mnt/keys/mykey2`
|
||||
|
||||
When using the component, you can reference the keys as `mykey1.pm` and `mykey2`.
|
||||
|
||||
## Related links
|
||||
[Cryptography building block]({{< ref cryptography >}})
|
||||
|
|
@ -116,41 +116,6 @@ If using TinyGo, compile as shown below and set the spec metadata field named
|
|||
tinygo build -o router.wasm -scheduler=none --no-debug -target=wasi router.go`
|
||||
```
|
||||
|
||||
### Generating Wasm
|
||||
|
||||
This component allows you to rewrite a request URI with custom logic compiled
|
||||
to a Wasm using the waPC protocol. The `rewrite` function receives the request
|
||||
URI and returns an update as necessary.
|
||||
|
||||
To compile your Wasm, you must compile source using a waPC guest SDK such as
|
||||
[TinyGo](https://github.com/wapc/wapc-guest-tinygo).
|
||||
|
||||
Here's an example in TinyGo:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import "github.com/wapc/wapc-guest-tinygo"
|
||||
|
||||
func main() {
|
||||
wapc.RegisterFunctions(wapc.Functions{"rewrite": rewrite})
|
||||
}
|
||||
|
||||
// rewrite returns a new URI if necessary.
|
||||
func rewrite(requestURI []byte) ([]byte, error) {
|
||||
if string(requestURI) == "/v1.0/hi" {
|
||||
return []byte("/v1.0/hello"), nil
|
||||
}
|
||||
return requestURI, nil
|
||||
}
|
||||
```
|
||||
|
||||
If using TinyGo, compile as shown below and set the spec metadata field named
|
||||
"url" to the location of the output (for example, `file://example.wasm`):
|
||||
|
||||
```bash
|
||||
tinygo build -o example.wasm -scheduler=none --no-debug -target=wasi example.go
|
||||
```
|
||||
|
||||
## Related links
|
||||
|
||||
|
|
|
|||
|
|
@ -28,6 +28,8 @@ spec:
|
|||
value: "public"
|
||||
- name: token
|
||||
value: "eyJrZXlJZCI6InB1bHNhci1wajU0cXd3ZHB6NGIiLCJhbGciOiJIUzI1NiJ9.eyJzd"
|
||||
- name: consumerID
|
||||
value: "topic1"
|
||||
- name: namespace
|
||||
value: "default"
|
||||
- name: persistent
|
||||
|
|
@ -66,6 +68,7 @@ spec:
|
|||
| enableTLS | N | Enable TLS. Default: `"false"` | `"true"`, `"false"` |
|
||||
| token | N | Enable Authentication. | [How to create pulsar token](https://pulsar.apache.org/docs/en/security-jwt/#generate-tokens)|
|
||||
| tenant | N | The topic tenant within the instance. Tenants are essential to multi-tenancy in Pulsar, and spread across clusters. Default: `"public"` | `"public"` |
|
||||
| consumerID | N | Used to set the subscription name or consumer ID. | `"topic1"`
|
||||
| namespace | N | The administrative unit of the topic, which acts as a grouping mechanism for related topics. Default: `"default"` | `"default"`
|
||||
| persistent | N | Pulsar supports two kinds of topics: [persistent](https://pulsar.apache.org/docs/en/concepts-architecture-overview#persistent-storage) and [non-persistent](https://pulsar.apache.org/docs/en/concepts-messaging/#non-persistent-topics). With persistent topics, all messages are durably persisted on disks (if the broker is not standalone, messages are durably persisted on multiple disks), whereas data for non-persistent topics is not persisted to storage disks.
|
||||
| disableBatching | N | disable batching.When batching enabled default batch delay is set to 10 ms and default batch size is 1000 messages,Setting `disableBatching: true` will make the producer to send messages individually. Default: `"false"` | `"true"`, `"false"`|
|
||||
|
|
@ -74,6 +77,9 @@ spec:
|
|||
| batchingMaxSize | N | batchingMaxSize sets the maximum number of bytes permitted in a batch. If set to a value greater than 1, messages will be queued until this threshold is reached or batchingMaxMessages (see above) has been reached or the batch interval has elapsed. Default: `"128KB"` | `"131072"`|
|
||||
| <topic-name>.jsonschema | N | Enforces JSON schema validation for the configured topic. |
|
||||
| <topic-name>.avroschema | N | Enforces Avro schema validation for the configured topic. |
|
||||
| publicKey | N | A public key to be used for publisher and consumer encryption. Value can be one of two options: file path for a local PEM cert, or the cert data string value |
|
||||
| privateKey | N | A private key to be used for consumer encryption. Value can be one of two options: file path for a local PEM cert, or the cert data string value |
|
||||
| keys | N | A comma delimited string containing names of [Pulsar session keys](https://pulsar.apache.org/docs/3.0.x/security-encryption/#how-it-works-in-pulsar). Used in conjunction with `publicKey` for publisher encryption |
|
||||
|
||||
### Enabling message delivery retries
|
||||
|
||||
|
|
@ -112,6 +118,90 @@ curl -X POST http://localhost:3500/v1.0/publish/myPulsar/myTopic?metadata.delive
|
|||
}'
|
||||
```
|
||||
|
||||
### E2E Encryption
|
||||
|
||||
Dapr supports setting public and private key pairs to enable Pulsar's [end-to-end encryption feature](https://pulsar.apache.org/docs/3.0.x/security-encryption/).
|
||||
|
||||
#### Enabling publisher encryption from file certs
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: messagebus
|
||||
spec:
|
||||
type: pubsub.pulsar
|
||||
version: v1
|
||||
metadata:
|
||||
- name: host
|
||||
value: "localhost:6650"
|
||||
- name: publicKey
|
||||
value: ./public.key
|
||||
- name: keys
|
||||
value: myapp.key
|
||||
```
|
||||
|
||||
#### Enabling consumer encryption from file certs
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: messagebus
|
||||
spec:
|
||||
type: pubsub.pulsar
|
||||
version: v1
|
||||
metadata:
|
||||
- name: host
|
||||
value: "localhost:6650"
|
||||
- name: publicKey
|
||||
value: ./public.key
|
||||
- name: privateKey
|
||||
value: ./private.key
|
||||
```
|
||||
|
||||
#### Enabling publisher encryption from value
|
||||
|
||||
> Note: It is recommended to [reference the public key from a secret]({{< ref component-secrets.md >}}).
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: messagebus
|
||||
spec:
|
||||
type: pubsub.pulsar
|
||||
version: v1
|
||||
metadata:
|
||||
- name: host
|
||||
value: "localhost:6650"
|
||||
- name: publicKey
|
||||
value: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1KDAM4L8RtJ+nLaXBrBh\nzVpvTemsKVZoAct8A+ShepOHT9lgHOCGLFGWNla6K6j+b3AV/P/fAAhwj82vwTDd\nruXSflvSdmYeFAw3Ypphc1A5oM53wSRWhg63potBNWqdDzj8ApYgqjpmjYSQdL5/\na3golb36GYFrY0MLFTv7wZ87pmMIPsOgGIcPbCHker2fRZ34WXYLb1hkeUpwx4eK\njpwcg35gccvR6o/UhbKAuc60V1J9Wof2sNgtlRaQej45wnpjWYzZrIyk5qUbn0Qi\nCdpIrXvYtANq0Id6gP8zJvUEdPIgNuYxEmVCl9jI+8eGI6peD0qIt8U80hf9axhJ\n3QIDAQAB\n-----END PUBLIC KEY-----\n"
|
||||
- name: keys
|
||||
value: myapp.key
|
||||
```
|
||||
|
||||
#### Enabling consumer encryption from value
|
||||
|
||||
> Note: It is recommended to [reference the public and private keys from a secret]({{< ref component-secrets.md >}}).
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: messagebus
|
||||
spec:
|
||||
type: pubsub.pulsar
|
||||
version: v1
|
||||
metadata:
|
||||
- name: host
|
||||
value: "localhost:6650"
|
||||
- name: publicKey
|
||||
value: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1KDAM4L8RtJ+nLaXBrBh\nzVpvTemsKVZoAct8A+ShepOHT9lgHOCGLFGWNla6K6j+b3AV/P/fAAhwj82vwTDd\nruXSflvSdmYeFAw3Ypphc1A5oM53wSRWhg63potBNWqdDzj8ApYgqjpmjYSQdL5/\na3golb36GYFrY0MLFTv7wZ87pmMIPsOgGIcPbCHker2fRZ34WXYLb1hkeUpwx4eK\njpwcg35gccvR6o/UhbKAuc60V1J9Wof2sNgtlRaQej45wnpjWYzZrIyk5qUbn0Qi\nCdpIrXvYtANq0Id6gP8zJvUEdPIgNuYxEmVCl9jI+8eGI6peD0qIt8U80hf9axhJ\n3QIDAQAB\n-----END PUBLIC KEY-----\n"
|
||||
- name: privateKey
|
||||
value: "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA1KDAM4L8RtJ+nLaXBrBhzVpvTemsKVZoAct8A+ShepOHT9lg\nHOCGLFGWNla6K6j+b3AV/P/fAAhwj82vwTDdruXSflvSdmYeFAw3Ypphc1A5oM53\nwSRWhg63potBNWqdDzj8ApYgqjpmjYSQdL5/a3golb36GYFrY0MLFTv7wZ87pmMI\nPsOgGIcPbCHker2fRZ34WXYLb1hkeUpwx4eKjpwcg35gccvR6o/UhbKAuc60V1J9\nWof2sNgtlRaQej45wnpjWYzZrIyk5qUbn0QiCdpIrXvYtANq0Id6gP8zJvUEdPIg\nNuYxEmVCl9jI+8eGI6peD0qIt8U80hf9axhJ3QIDAQABAoIBAQCKuHnM4ac/eXM7\nQPDVX1vfgyHc3hgBPCtNCHnXfGFRvFBqavKGxIElBvGOcBS0CWQ+Rg1Ca5kMx3TQ\njSweSYhH5A7pe3Sa5FK5V6MGxJvRhMSkQi/lJZUBjzaIBJA9jln7pXzdHx8ekE16\nBMPONr6g2dr4nuI9o67xKrtfViwRDGaG6eh7jIMlEqMMc6WqyhvI67rlVDSTHFKX\njlMcozJ3IT8BtTzKg2Tpy7ReVuJEpehum8yn1ZVdAnotBDJxI07DC1cbOP4M2fHM\ngfgPYWmchauZuTeTFu4hrlY5jg0/WLs6by8r/81+vX3QTNvejX9UdTHMSIfQdX82\nAfkCKUVhAoGBAOvGv+YXeTlPRcYC642x5iOyLQm+BiSX4jKtnyJiTU2s/qvvKkIu\nxAOk3OtniT9NaUAHEZE9tI71dDN6IgTLQlAcPCzkVh6Sc5eG0MObqOO7WOMCWBkI\nlaAKKBbd6cGDJkwGCJKnx0pxC9f8R4dw3fmXWgWAr8ENiekMuvjSfjZ5AoGBAObd\ns2L5uiUPTtpyh8WZ7rEvrun3djBhzi+d7rgxEGdditeiLQGKyZbDPMSMBuus/5wH\nwfi0xUq50RtYDbzQQdC3T/C20oHmZbjWK5mDaLRVzWS89YG/NT2Q8eZLBstKqxkx\ngoT77zoUDfRy+CWs1xvXzgxagD5Yg8/OrCuXOqWFAoGAPIw3r6ELknoXEvihASxU\nS4pwInZYIYGXpygLG8teyrnIVOMAWSqlT8JAsXtPNaBtjPHDwyazfZrvEmEk51JD\nX0tA8M5ah1NYt+r5JaKNxp3P/8wUT6lyszyoeubWJsnFRfSusuq/NRC+1+KDg/aq\nKnSBu7QGbm9JoT2RrmBv5RECgYBRn8Lj1I1muvHTNDkiuRj2VniOSirkUkA2/6y+\nPMKi+SS0tqcY63v4rNCYYTW1L7Yz8V44U5mJoQb4lvpMbolGhPljjxAAU3hVkItb\nvGVRlSCIZHKczADD4rJUDOS7DYxO3P1bjUN4kkyYx+lKUMDBHFzCa2D6Kgt4dobS\n5qYajQKBgQC7u7MFPkkEMqNqNGu5erytQkBq1v1Ipmf9rCi3iIj4XJLopxMgw0fx\n6jwcwNInl72KzoUBLnGQ9PKGVeBcgEgdI+a+tq+1TJo6Ta+hZSx+4AYiKY18eRKG\neNuER9NOcSVJ7Eqkcw4viCGyYDm2vgNV9HJ0VlAo3RDh8x5spEN+mg==\n-----END RSA PRIVATE KEY-----\n"
|
||||
```
|
||||
|
||||
## Create a Pulsar instance
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes">}}
|
||||
|
|
|
|||
|
|
@ -371,7 +371,7 @@ To set a priority on a message, add the publish metadata key `maxPriority` to th
|
|||
{{% codetab %}}
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3601/v1.0/publish/order-pub-sub/orders?metadata.maxPriority=3 -H "Content-Type: application/json" -d '{"orderId": "100"}'
|
||||
curl -X POST http://localhost:3601/v1.0/publish/order-pub-sub/orders?metadata.priority=3 -H "Content-Type: application/json" -d '{"orderId": "100"}'
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
|
@ -385,7 +385,7 @@ with DaprClient() as client:
|
|||
topic_name=TOPIC_NAME,
|
||||
data=json.dumps(orderId),
|
||||
data_content_type='application/json',
|
||||
metadata= { 'maxPriority': '3' })
|
||||
metadata= { 'priority': '3' })
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
|
@ -393,7 +393,7 @@ with DaprClient() as client:
|
|||
{{% codetab %}}
|
||||
|
||||
```javascript
|
||||
await client.pubsub.publish(PUBSUB_NAME, TOPIC_NAME, orderId, { 'maxPriority': '3' });
|
||||
await client.pubsub.publish(PUBSUB_NAME, TOPIC_NAME, orderId, { 'priority': '3' });
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
|
@ -401,7 +401,7 @@ await client.pubsub.publish(PUBSUB_NAME, TOPIC_NAME, orderId, { 'maxPriority': '
|
|||
{{% codetab %}}
|
||||
|
||||
```go
|
||||
client.PublishEvent(ctx, PUBSUB_NAME, TOPIC_NAME, []byte(strconv.Itoa(orderId)), map[string]string{"maxPriority": "3"})
|
||||
client.PublishEvent(ctx, PUBSUB_NAME, TOPIC_NAME, []byte(strconv.Itoa(orderId)), map[string]string{"priority": "3"})
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -70,6 +70,10 @@ In order to setup Cosmos DB as a state store, you need the following properties
|
|||
- **Database**: The name of the database
|
||||
- **Collection**: The name of the collection (or container)
|
||||
|
||||
### TTLs and cleanups
|
||||
|
||||
This state store supports [Time-To-Live (TTL)]({{< ref state-store-ttl.md >}}) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to override the default TTL on the CosmodDB container, indicating when the data should be considered "expired". Note that this value _only_ takes effect if the container's `DefaultTimeToLive` field has a non-NULL value. See the [CosmosDB documentation](https://docs.microsoft.com/azure/cosmos-db/nosql/time-to-live) for more information.
|
||||
|
||||
## Best Practices for Production Use
|
||||
|
||||
Azure Cosmos DB shares a strict metadata request rate limit across all databases in a single Azure Cosmos DB account. New connections to Azure Cosmos DB assume a large percentage of the allowable request rate limit. (See the [Cosmos DB documentation](https://docs.microsoft.com/azure/cosmos-db/sql/troubleshoot-request-rate-too-large#recommended-solution-3))
|
||||
|
|
|
|||
|
|
@ -58,6 +58,7 @@ If you wish to use MySQL as an actor store, append the following to the yaml.
|
|||
| `timeoutInSeconds` | N | Timeout for all database operations. Defaults to `20` | `30` |
|
||||
| `pemPath` | N | Full path to the PEM file to use for [enforced SSL Connection](#enforced-ssl-connection) required if pemContents is not provided. Cannot be used in K8s environment | `"/path/to/file.pem"`, `"C:\path\to\file.pem"` |
|
||||
| `pemContents` | N | Contents of PEM file to use for [enforced SSL Connection](#enforced-ssl-connection) required if pemPath is not provided. Can be used in K8s environment | `"pem value"` |
|
||||
| `cleanupIntervalInSeconds` | N | Interval, in seconds, to clean up rows with an expired TTL. Default: `3600` (that is 1 hour). Setting this to values <=0 disables the periodic cleanup. | `1800`, `-1`
|
||||
|
||||
## Setup MySQL
|
||||
|
||||
|
|
@ -134,6 +135,17 @@ Replace the `<CONNECTION STRING>` value with your connection string. The connect
|
|||
|
||||
If your server requires SSL your connection string must end with `&tls=custom` for example, `"<user>:<password>@tcp(<server>:3306)/?allowNativePasswords=true&tls=custom"`. You must replace the `<PEM PATH>` with a full path to the PEM file. The connection to MySQL will require a minimum TLS version of 1.2.
|
||||
|
||||
### TTLs and cleanups
|
||||
|
||||
This state store supports [Time-To-Live (TTL)]({{< ref state-store-ttl.md >}}) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to indicate when the data should be considered "expired".
|
||||
|
||||
Because MySQL doesn't have built-in support for TTLs, this is implemented in Dapr by adding a column in the state table indicating when the data is to be considered "expired". Records that are "expired" are not returned to the caller, even if they're still physically stored in the database. A background "garbage collector" periodically scans the state table for expired rows and deletes them.
|
||||
|
||||
The interval at which the deletion of expired records happens is set with the `cleanupIntervalInSeconds` metadata property, which defaults to 3600 seconds (that is, 1 hour).
|
||||
|
||||
- Longer intervals require less frequent scans for expired rows, but can require storing expired records for longer, potentially requiring more storage space. If you plan to store many records in your state table, with short TTLs, consider setting `cleanupIntervalInSeconds` to a smaller value, for example `300` (300 seconds, or 5 minutes).
|
||||
- If you do not plan to use TTLs with Dapr and the MySQL state store, you should consider setting `cleanupIntervalInSeconds` to a value <= 0 (e.g. `0` or `-1`) to disable the periodic cleanup and reduce the load on the database.
|
||||
|
||||
## Related links
|
||||
- [Basic schema for a Dapr component]({{< ref component-schema >}})
|
||||
- Read [this guide]({{< ref "howto-get-save-state.md#step-2-save-and-retrieve-a-single-state" >}}) for instructions on configuring state store components
|
||||
|
|
|
|||
|
|
@ -92,7 +92,7 @@ Either the default "postgres" database can be used, or create a new database for
|
|||
|
||||
### TTLs and cleanups
|
||||
|
||||
This state store supports [Time-To-Live (TTL)](https://docs.dapr.io/developing-applications/building-blocks/state-management/state-store-ttl/) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to indicate after how many seconds the data should be considered "expired".
|
||||
This state store supports [Time-To-Live (TTL)]({{< ref state-store-ttl.md >}}) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to indicate after how many seconds the data should be considered "expired".
|
||||
|
||||
Because PostgreSQL doesn't have built-in support for TTLs, this is implemented in Dapr by adding a column in the state table indicating when the data is to be considered "expired". Records that are "expired" are not returned to the caller, even if they're still physically stored in the database. A background "garbage collector" periodically scans the state table for expired rows and deletes them.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
- component: Azure Key Vault
|
||||
link: azure-key-vault
|
||||
state: Alpha
|
||||
version: v1
|
||||
since: "1.11"
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
- component: JSON Web Key Sets (JWKS)
|
||||
link: json-web-key-sets
|
||||
state: Alpha
|
||||
version: v1
|
||||
since: "1.11"
|
||||
- component: Kubernetes secrets
|
||||
link: kubernetes-secrets
|
||||
state: Alpha
|
||||
version: v1
|
||||
since: "1.11"
|
||||
- component: Local storage
|
||||
link: local-storage
|
||||
state: Alpha
|
||||
version: v1
|
||||
since: "1.11"
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
{{- $groups := dict
|
||||
" Generic" $.Site.Data.components.cryptography.generic
|
||||
"Microsoft Azure" $.Site.Data.components.cryptography.azure
|
||||
|
||||
}}
|
||||
|
||||
{{ range $group, $components := $groups }}
|
||||
<h3>{{ $group }}</h3>
|
||||
<table width="100%">
|
||||
<tr>
|
||||
<th>Component</th>
|
||||
<th>Status</th>
|
||||
<th>Component version</th>
|
||||
<th>Since runtime version</th>
|
||||
</tr>
|
||||
{{ range sort $components "component" }}
|
||||
<tr>
|
||||
<td><a href="/reference/components-reference/supported-cryptography/{{ .link }}/">{{ .component }}</a>
|
||||
</td>
|
||||
<td>{{ .state }}</td>
|
||||
<td>{{ .version }}</td>
|
||||
<td>{{ .since }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</table>
|
||||
{{ end }}
|
||||
|
||||
{{ partial "components/componenttoc.html" . }}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 141 KiB After Width: | Height: | Size: 107 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 131 KiB After Width: | Height: | Size: 152 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 100 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 535 KiB After Width: | Height: | Size: 134 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 156 KiB After Width: | Height: | Size: 122 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 128 KiB After Width: | Height: | Size: 133 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 100 KiB |
Binary file not shown.
Loading…
Reference in New Issue