mirror of https://github.com/dapr/docs.git
Merge pull request #2215 from hhunter-ms/pubsubquickstarts
[Pub/sub] Quickstarts & TOC restructure - without Go example
This commit is contained in:
greenie-msft
GitHub
commit
e1a71d56bb
|
|
@ -3,24 +3,18 @@ type: docs
|
|||
title: "Getting started with Dapr"
|
||||
linkTitle: "Getting started"
|
||||
weight: 20
|
||||
description: "How to get up and running with Dapr in minutes"
|
||||
no_list: true
|
||||
description: "Get up and running with Dapr in minutes"
|
||||
---
|
||||
|
||||
Welcome to the Dapr getting started guide!
|
||||
|
||||
{{% alert title="Dapr Concepts" color="primary" %}}
|
||||
If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{<ref concepts>}}).
|
||||
If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, we recommend starting with the [concepts section]({{<ref concepts>}}).
|
||||
{{% /alert %}}
|
||||
|
||||
This guide will walk you through a series of steps to install, initialize and start using Dapr. The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}})) which includes the Dapr CLI, Dapr sidecar binaries, and some default components that can help you start using Dapr quickly.
|
||||
Our getting started guide will walk you through a series of steps to install, initialize, experiment with, and start using Dapr.
|
||||
|
||||
The following steps in this guide are:
|
||||
1. Install the Dapr CLI
|
||||
1. Initialize Dapr
|
||||
1. Use the Dapr API
|
||||
1. Configure a component
|
||||
1. Explore Dapr quickstarts
|
||||
<br>
|
||||
|
||||
{{< button text="First step: Install the Dapr CLI >>" page="install-dapr-cli" >}}
|
||||
<br><br>
|
||||
|
|
@ -1,243 +0,0 @@
|
|||
---
|
||||
type: docs
|
||||
title: "How-To: Configure state store and pub/sub message broker"
|
||||
linkTitle: "(optional) Configure state & pub/sub"
|
||||
weight: 80
|
||||
description: "Configure state store and pub/sub message broker components for Dapr"
|
||||
aliases:
|
||||
- /getting-started/configure-redis/
|
||||
---
|
||||
|
||||
In order to get up and running with the state and pub/sub building blocks two components are needed:
|
||||
|
||||
1. A state store component for persistence and restoration
|
||||
2. As pub/sub message broker component for async-style message delivery
|
||||
|
||||
A full list of supported components can be found here:
|
||||
- [Supported state stores]({{< ref supported-state-stores >}})
|
||||
- [Supported pub/sub message brokers]({{< ref supported-pubsub >}})
|
||||
|
||||
The rest of this page describes how to get up and running with Redis.
|
||||
|
||||
{{% alert title="Self-hosted mode" color="warning" %}}
|
||||
When initialized in self-hosted mode, Dapr automatically runs a Redis container and sets up the required component yaml files. You can skip this page and go to [next steps](#next-steps)
|
||||
{{% /alert %}}
|
||||
|
||||
## Create a Redis store
|
||||
|
||||
Dapr can use any Redis instance - either containerized on your local dev machine or a managed cloud service. If you already have a Redis store, move on to the [configuration](#configure-dapr-components) section.
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes" "Azure" "AWS" "GCP" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
Redis is automatically installed in self-hosted environments by the Dapr CLI as part of the initialization process. You are all set and can skip to the [next steps](#next-steps)
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
You can use [Helm](https://helm.sh/) to quickly create a Redis instance in our Kubernetes cluster. This approach requires [Installing Helm v3](https://github.com/helm/helm#install).
|
||||
|
||||
1. Install Redis into your cluster:
|
||||
|
||||
```bash
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
helm repo update
|
||||
helm install redis bitnami/redis
|
||||
```
|
||||
|
||||
Note that you will need a Redis version greater than 5, which is what Dapr's pub/sub functionality requires. If you're intending on using Redis as just a state store (and not for pub/sub) a lower version can be used.
|
||||
|
||||
2. Run `kubectl get pods` to see the Redis containers now running in your cluster:
|
||||
|
||||
```bash
|
||||
$ kubectl get pods
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
redis-master-0 1/1 Running 0 69s
|
||||
redis-replicas-0 1/1 Running 0 69s
|
||||
redis-replicas-1 1/1 Running 0 22s
|
||||
```
|
||||
|
||||
Note that the hostname is `redis-master.default.svc.cluster.local:6379`, and a Kubernetes secret, `redis`, is created automatically.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
This method requires having an Azure Subscription.
|
||||
|
||||
1. Open the [Azure Portal](https://ms.portal.azure.com/#create/Microsoft.Cache) to start the Azure Redis Cache creation flow. Log in if necessary.
|
||||
1. Fill out the necessary information
|
||||
- Dapr pub/sub uses [Redis streams](https://redis.io/topics/streams-intro) that was introduced by Redis 5.0. If you would like to use Azure Redis Cache for pub/sub make sure to set the version to (PREVIEW) 6.
|
||||
1. Click "Create" to kickoff deployment of your Redis instance.
|
||||
1. You'll need the hostname of your Redis instance, which you can retrieve from the "Overview" in Azure. It should look like `xxxxxx.redis.cache.windows.net:6380`. Note this for later.
|
||||
1. Once your instance is created, you'll need to grab your access key. Navigate to "Access Keys" under "Settings" and create a Kubernetes secret to store your Redis password:
|
||||
```bash
|
||||
kubectl create secret generic redis --from-literal=redis-password=*********
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
1. Visit [AWS Redis](https://aws.amazon.com/redis/) to deploy a Redis instance
|
||||
1. Note the Redis hostname in the AWS portal for use later
|
||||
1. Create a Kubernetes secret to store your Redis password:
|
||||
```bash
|
||||
kubectl create secret generic redis --from-literal=redis-password=*********
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
1. Visit [GCP Cloud MemoryStore](https://cloud.google.com/memorystore/) to deploy a MemoryStore instance
|
||||
1. Note the Redis hostname in the GCP portal for use later
|
||||
1. Create a Kubernetes secret to store your Redis password:
|
||||
```bash
|
||||
kubectl create secret generic redis --from-literal=redis-password=*********
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Configure Dapr components
|
||||
|
||||
Dapr uses components to define what resources to use for building block functionality. These steps go through how to connect the resources you created above to Dapr for state and pub/sub.
|
||||
|
||||
In self-hosted mode, component files are automatically created under:
|
||||
- **Windows**: `%USERPROFILE%\.dapr\components\`
|
||||
- **Linux/MacOS**: `$HOME/.dapr/components`
|
||||
|
||||
For Kubernetes, files can be created in any directory, as they are applied with `kubectl`.
|
||||
|
||||
### Create State store component
|
||||
|
||||
Create a file named `redis-state.yaml`, and paste the following:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
namespace: default
|
||||
spec:
|
||||
type: state.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <REPLACE WITH HOSTNAME FROM ABOVE - for Redis on Kubernetes it is redis-master.default.svc.cluster.local:6379>
|
||||
- name: redisPassword
|
||||
secretKeyRef:
|
||||
name: redis
|
||||
key: redis-password
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
This example uses the kubernetes secret that was created when setting up a cluster with the above instructions.
|
||||
|
||||
{{% alert title="Other stores" color="primary" %}}
|
||||
If using a state store other than Redis, refer to the [supported state stores]({{< ref supported-state-stores >}}) for information on what options to set.
|
||||
{{% /alert %}}
|
||||
|
||||
### Create Pub/sub message broker component
|
||||
|
||||
Create a file called redis-pubsub.yaml, and paste the following:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: pubsub
|
||||
namespace: default
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <REPLACE WITH HOSTNAME FROM ABOVE - for Redis on Kubernetes it is redis-master.default.svc.cluster.local:6379>
|
||||
- name: redisPassword
|
||||
secretKeyRef:
|
||||
name: redis
|
||||
key: redis-password
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
This example uses the kubernetes secret that was created when setting up a cluster with the above instructions.
|
||||
|
||||
{{% alert title="Other stores" color="primary" %}}
|
||||
If using a pub/sub message broker other than Redis, refer to the [supported pub/sub message brokers]({{< ref supported-pubsub >}}) for information on what options to set.
|
||||
{{% /alert %}}
|
||||
|
||||
### Hard coded passwords (not recommended)
|
||||
|
||||
For development purposes only you can skip creating kubernetes secrets and place passwords directly into the Dapr component file:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
namespace: default
|
||||
spec:
|
||||
type: state.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <HOST>
|
||||
- name: redisPassword
|
||||
value: <PASSWORD>
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: pubsub
|
||||
namespace: default
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <HOST>
|
||||
- name: redisPassword
|
||||
value: <PASSWORD>
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
## Apply the configuration
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes">}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
By default the Dapr CLI creates a local Redis instance when you run `dapr init`. However, if you want to configure a different Redis instance you can either:
|
||||
- Update the existing component files or create new ones in the default components directory
|
||||
- **Linux/MacOS:** `$HOME/.dapr/components`
|
||||
- **Windows:** `%USERPROFILE%\.dapr\components`
|
||||
- Create a new `components` directory in your app folder containing the YAML files and provide the path to the `dapr run` command with the flag `--components-path`
|
||||
|
||||
{{% alert title="Self-hosted slim mode" color="primary" %}}
|
||||
If you initialized Dapr in [slim mode]({{< ref self-hosted-no-docker.md >}}) (without Docker) you need to manually create the default directory, or always specify a components directory using `--components-path`.
|
||||
{{% /alert %}}
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
Run `kubectl apply -f <FILENAME>` for both state and pubsub files:
|
||||
|
||||
```bash
|
||||
kubectl apply -f redis-state.yaml
|
||||
kubectl apply -f redis-pubsub.yaml
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Next steps
|
||||
- [Try out a Dapr quickstart]({{< ref quickstarts.md >}})
|
||||
|
|
@ -3,27 +3,40 @@ type: docs
|
|||
title: "Use the Dapr API"
|
||||
linkTitle: "Use the Dapr API"
|
||||
weight: 30
|
||||
description: "Run a Dapr sidecar and try out the state API"
|
||||
---
|
||||
|
||||
After running the `dapr init` command in the [previous step]({{<ref install-dapr-selfhost.md>}}), your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. You can learn more about the state building block and how it works in [these docs]({{< ref state-management >}}).
|
||||
Running [`dapr init`]({{<ref install-dapr-selfhost.md>}}) loads your local environment with:
|
||||
|
||||
You will now run the sidecar and call the API directly (simulating what an application would do).
|
||||
- The Dapr sidecar binaries.
|
||||
- Default Redis component definitions for both:
|
||||
- State management, and
|
||||
- A message broker.
|
||||
|
||||
## Step 1: Run the Dapr sidecar
|
||||
With this setup, run Dapr using the Dapr CLI and try out the state API to store and retrieve a state. [Learn more about the state building block and how it works in our concept docs]({{< ref state-management >}}).
|
||||
|
||||
One of the most useful Dapr CLI commands is [`dapr run`]({{< ref dapr-run.md >}}). This command launches an application together with a sidecar. For the purpose of this tutorial you'll run the sidecar without an application.
|
||||
In this guide, you will simulate an application by running the sidecar and calling the API directly. For the purpose of this tutorial you'll run the sidecar without an application.
|
||||
|
||||
Run the following command to launch a Dapr sidecar that will listen on port 3500 for a blank application named myapp:
|
||||
### Step 1: Run the Dapr sidecar
|
||||
|
||||
One of the most useful Dapr CLI commands is [`dapr run`]({{< ref dapr-run.md >}}). This command launches an application, together with a sidecar.
|
||||
|
||||
Launch a Dapr sidecar that will listen on port 3500 for a blank application named `myapp`:
|
||||
|
||||
```bash
|
||||
dapr run --app-id myapp --dapr-http-port 3500
|
||||
```
|
||||
|
||||
With this command, no custom component folder was defined, so Dapr uses the default component definitions that were created during the init flow (these can be found under `$HOME/.dapr/components` on Linux or MacOS and under `%USERPROFILE%\.dapr\components` on Windows). These tell Dapr to use the local Redis Docker container as a state store and message broker.
|
||||
Since no custom component folder was defined with the above command, Dapr uses the default component definitions created during the [`dapr init` flow]({{< ref install-dapr-selfhost.md >}}), found:
|
||||
|
||||
## Step 2: Save state
|
||||
- On Windows, under `%UserProfile%\.dapr\components`
|
||||
- On Linux/MacOS, under `~/.dapr/components`
|
||||
|
||||
We will now update the state with an object. The new state will look like this:
|
||||
These tell Dapr to use the local Docker container for Redis as a state store and message broker.
|
||||
|
||||
### Step 2: Save state
|
||||
|
||||
Update the state with an object. The new state will look like this:
|
||||
|
||||
```json
|
||||
[
|
||||
|
|
@ -36,7 +49,7 @@ We will now update the state with an object. The new state will look like this:
|
|||
|
||||
Notice, the object contained in the state has a `key` assigned with the value `name`. You will use the key in the next step.
|
||||
|
||||
Run the command shown below to store the new state.
|
||||
Store the new state using the following command:
|
||||
|
||||
{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}}
|
||||
{{% codetab %}}
|
||||
|
|
@ -55,45 +68,46 @@ Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key":
|
|||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Step 3: Get state
|
||||
### Step 3: Get state
|
||||
|
||||
Now get the object you just stored in the state by using the state management API with the key `name`:
|
||||
Retrieve the object you just stored in the state by using the state management API with the key `name`. Run the following code with the same Dapr instance you ran earlier. :
|
||||
|
||||
{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}}
|
||||
|
||||
{{% codetab %}}
|
||||
With the same Dapr instance running from above run:
|
||||
|
||||
```bash
|
||||
curl http://localhost:3500/v1.0/state/statestore/name
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
With the same Dapr instance running from above run:
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/name'
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Step 4: See how the state is stored in Redis
|
||||
### Step 4: See how the state is stored in Redis
|
||||
|
||||
You can look in the Redis container and verify Dapr is using it as a state store. Run the following to use the Redis CLI:
|
||||
Look in the Redis container and verify Dapr is using it as a state store. Use the Redis CLI with the following command:
|
||||
|
||||
```bash
|
||||
docker exec -it dapr_redis redis-cli
|
||||
```
|
||||
|
||||
List the redis keys to see how Dapr created a key value pair (with the app-id you provided to `dapr run` as a prefix to the key):
|
||||
List the Redis keys to see how Dapr created a key value pair with the app-id you provided to `dapr run` as the key's prefix:
|
||||
|
||||
```bash
|
||||
keys *
|
||||
```
|
||||
|
||||
```
|
||||
1) "myapp||name"
|
||||
```
|
||||
**Output:**
|
||||
`1) "myapp||name"`
|
||||
|
||||
View the state value by running:
|
||||
|
||||
|
|
@ -101,12 +115,11 @@ View the state value by running:
|
|||
hgetall "myapp||name"
|
||||
```
|
||||
|
||||
```
|
||||
1) "data"
|
||||
2) "\"Bruce Wayne\""
|
||||
3) "version"
|
||||
4) "1"
|
||||
```
|
||||
**Output:**
|
||||
`1) "data"`
|
||||
`2) "\"Bruce Wayne\""`
|
||||
`3) "version"`
|
||||
`4) "1"`
|
||||
|
||||
Exit the redis-cli with:
|
||||
|
||||
|
|
@ -114,4 +127,4 @@ Exit the redis-cli with:
|
|||
exit
|
||||
```
|
||||
|
||||
{{< button text="Next step: Define a component >>" page="get-started-component" >}}
|
||||
{{< button text="Next step: Dapr Quickstarts >>" page="getting-started/quickstarts" >}}
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Define a component"
|
||||
linkTitle: "Define a component"
|
||||
weight: 40
|
||||
---
|
||||
|
||||
In the [previous step]({{<ref get-started-api.md>}}) you called the Dapr HTTP API to store and retrieve a state from a Redis backed state store. Dapr knew to use the Redis instance that was configured locally on your machine through default component definition files that were created when Dapr was initialized.
|
||||
|
||||
When building an app, you most likely would create your own component file definitions depending on the building block and specific component that you'd like to use.
|
||||
|
||||
As an example of how to define custom components for your application, you will now create a component definition file to interact with the [secrets building block]({{< ref secrets >}}).
|
||||
|
||||
In this guide you will:
|
||||
- Create a local JSON secret store
|
||||
- Register the secret store with Dapr using a component definition file
|
||||
- Obtain the secret using the Dapr HTTP API
|
||||
|
||||
## Step 1: Create a JSON secret store
|
||||
|
||||
While Dapr supports [many types of secret stores]({{< ref supported-secret-stores >}}), the easiest way to get started is a local JSON file with your secret (note this secret store is meant for development purposes and is not recommended for production use cases as it is not secured).
|
||||
|
||||
Begin by saving the following JSON contents into a file named `mysecrets.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"my-secret" : "I'm Batman"
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2: Create a secret store Dapr component
|
||||
|
||||
Create a new directory named `my-components` to hold the new component file:
|
||||
|
||||
```bash
|
||||
mkdir my-components
|
||||
```
|
||||
|
||||
Inside this directory create a new file `localSecretStore.yaml` with the following contents:
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: my-secret-store
|
||||
namespace: default
|
||||
spec:
|
||||
type: secretstores.local.file
|
||||
version: v1
|
||||
metadata:
|
||||
- name: secretsFile
|
||||
value: <PATH TO SECRETS FILE>/mysecrets.json
|
||||
- name: nestedSeparator
|
||||
value: ":"
|
||||
```
|
||||
|
||||
You can see that the above file definition has a `type: secretstores.local.file` which tells Dapr to use the local file component as a secret store. The metadata fields provide component specific information needed to work with this component (in this case, the path to the secret store JSON is relative to where you call `dapr run` from.)
|
||||
|
||||
## Step 3: Run the Dapr sidecar
|
||||
|
||||
Run the following command to launch a Dapr sidecar that will listen on port 3500 for a blank application named myapp:
|
||||
|
||||
```bash
|
||||
dapr run --app-id myapp --dapr-http-port 3500 --components-path ./my-components
|
||||
```
|
||||
|
||||
> If you encounter a error message stating the app ID is already in use, it may be that the sidecar you ran in the previous step is still running. Make sure you stop the sidecar before running the above command (e.g. using "Control-C").
|
||||
|
||||
## Step 4: Get a secret
|
||||
|
||||
In a separate terminal run:
|
||||
|
||||
{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}}
|
||||
{{% codetab %}}
|
||||
|
||||
```bash
|
||||
curl http://localhost:3500/v1.0/secrets/my-secret-store/my-secret
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/secrets/my-secret-store/my-secret'
|
||||
```
|
||||
{{% /codetab %}}
|
||||
{{< /tabs >}}
|
||||
|
||||
You should see output with the secret you stored in the JSON file.
|
||||
|
||||
```json
|
||||
{"my-secret":"I'm Batman"}
|
||||
```
|
||||
|
||||
{{< button text="Next step: Explore Dapr quickstarts >>" page="quickstarts" >}}
|
||||
|
|
@ -3,100 +3,131 @@ type: docs
|
|||
title: "Install the Dapr CLI"
|
||||
linkTitle: "Install Dapr CLI"
|
||||
weight: 10
|
||||
description: "Install the Dapr CLI as the main tool for running Dapr-related tasks"
|
||||
---
|
||||
|
||||
The Dapr CLI is the main tool you'll be using for various Dapr related tasks. You can use it to run an application with a Dapr sidecar, as well as review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments.
|
||||
You'll use the Dapr CLI as the main tool for various Dapr-related tasks. You can use it to:
|
||||
|
||||
Begin by downloading and installing the Dapr CLI:
|
||||
- Run an application with a Dapr sidecar.
|
||||
- Review sidecar logs.
|
||||
- List running services.
|
||||
- Run the Dapr dashboard.
|
||||
|
||||
The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments.
|
||||
|
||||
### Step 1: Install the Dapr CLI
|
||||
|
||||
{{< tabs Linux Windows MacOS Binaries>}}
|
||||
|
||||
{{% codetab %}}
|
||||
### Install from Terminal
|
||||
|
||||
This command installs the latest linux Dapr CLI to `/usr/local/bin`:
|
||||
#### Install from Terminal
|
||||
|
||||
Install the latest Linux Dapr CLI to `/usr/local/bin`:
|
||||
|
||||
```bash
|
||||
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
|
||||
```
|
||||
|
||||
### Install without `sudo`
|
||||
If you do not have access to the `sudo` command or your username is not in the `sudoers` file you can install Dapr to an alternate directory via the `DAPR_INSTALL_DIR` environment variable.
|
||||
#### Install without `sudo`
|
||||
|
||||
If you do not have access to the `sudo` command or your username is not in the `sudoers` file, you can install Dapr to an alternate directory via the `DAPR_INSTALL_DIR` environment variable.
|
||||
|
||||
```bash
|
||||
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | DAPR_INSTALL_DIR="$HOME/dapr" /bin/bash
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
### Install from Command Prompt
|
||||
This Command Prompt command installs the latest windows Dapr cli to `C:\dapr` and adds this directory to User PATH environment variable.
|
||||
|
||||
#### Install from Command Prompt
|
||||
|
||||
Install the latest windows Dapr cli to `C:\dapr` and add this directory to the User PATH environment variable:
|
||||
|
||||
```powershell
|
||||
powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
|
||||
```
|
||||
|
||||
### Install without administrative rights
|
||||
If you do not have admin rights you can install Dapr to an alternate directory via the `DAPR_INSTALL_DIR` environment variable.
|
||||
#### Install without administrative rights
|
||||
|
||||
If you do not have admin rights, you can install Dapr to an alternate directory via the `DAPR_INSTALL_DIR` environment variable.
|
||||
|
||||
```powershell
|
||||
$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList "", "$HOME/dapr"
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
### Install from Terminal
|
||||
This command installs the latest darwin Dapr CLI to `/usr/local/bin`:
|
||||
|
||||
Install the latest Darwin Dapr CLI to `/usr/local/bin`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | /bin/bash
|
||||
```
|
||||
#### Note for ARM64 Macs
|
||||
Support for ARM64 Macs is available as a Preview feature. When installing from the terminal, native ARM64 binaries are downloaded when available. For older releases, AMD64 binaries are downloaded, which must be run with Rosetta2 emulation enabled. To install Rosetta emulation:
|
||||
|
||||
**For ARM64 Macs:**
|
||||
|
||||
ARM64 Macs support is available as a *preview feature*. When installing from the terminal, native ARM64 binaries are downloaded once available. For older releases, AMD64 binaries are downloaded and must be run with Rosetta2 emulation enabled.
|
||||
|
||||
To install Rosetta emulation:
|
||||
|
||||
```bash
|
||||
softwareupdate --install-rosetta
|
||||
```
|
||||
|
||||
### Install from Homebrew
|
||||
You can install via [Homebrew](https://brew.sh):
|
||||
#### Install from Homebrew
|
||||
|
||||
Install via [Homebrew](https://brew.sh):
|
||||
|
||||
```bash
|
||||
brew install dapr/tap/dapr-cli
|
||||
```
|
||||
|
||||
#### Note for ARM64 Macs
|
||||
**For ARM64 Macs:**
|
||||
|
||||
For ARM64 Macs, only Homebrew 3.0 and higher versions are supported. Please update Homebrew to 3.0.0 or higher and then run the command below:
|
||||
|
||||
```bash
|
||||
arch -arm64 brew install dapr/tap/dapr-cli
|
||||
```
|
||||
|
||||
### Install without `sudo`
|
||||
If you do not have access to the `sudo` command or your username is not in the `sudoers` file you can install Dapr to an alternate directory via the `DAPR_INSTALL_DIR` environment variable.
|
||||
#### Install without `sudo`
|
||||
If you do not have access to the `sudo` command or your username is not in the `sudoers` file, you can install Dapr to an alternate directory via the `DAPR_INSTALL_DIR` environment variable.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | DAPR_INSTALL_DIR="$HOME/dapr" /bin/bash
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
Each release of Dapr CLI includes various OSes and architectures. These binary versions can be manually downloaded and installed.
|
||||
Each release of Dapr CLI includes various OSes and architectures. You can manually download and install these binary versions.
|
||||
|
||||
1. Download the desired Dapr CLI from the latest [Dapr Release](https://github.com/dapr/cli/releases)
|
||||
2. Unpack it (e.g. dapr_linux_amd64.tar.gz, dapr_windows_amd64.zip)
|
||||
1. Download the desired Dapr CLI from the latest [Dapr Release](https://github.com/dapr/cli/releases).
|
||||
2. Unpack it (e.g. dapr_linux_amd64.tar.gz, dapr_windows_amd64.zip).
|
||||
3. Move it to your desired location.
|
||||
- For Linux/MacOS `/usr/local/bin` is recommended.
|
||||
- For Windows, create a directory and add this to your System PATH. For example create a directory called `C:\dapr` and add this directory to your User PATH, by editing your system environment variable.
|
||||
{{% /codetab %}}
|
||||
{{< /tabs >}}
|
||||
- For Linux/MacOS, we recommend `/usr/local/bin`.
|
||||
- For Windows, create a directory and add this to your System PATH. For example:
|
||||
- Create a directory called `C:\dapr`.
|
||||
- Add your newly created directory to your User PATH, by editing your system environment variable.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
### Step 2: Verify the installation
|
||||
|
||||
You can verify the CLI is installed by restarting your terminal/command prompt and running the following:
|
||||
Verify the CLI is installed by restarting your terminal/command prompt and running the following:
|
||||
|
||||
```bash
|
||||
dapr
|
||||
```
|
||||
|
||||
The output should look like this:
|
||||
|
||||
**Output:**
|
||||
|
||||
```md
|
||||
__
|
||||
|
|
|
|||
|
|
@ -3,38 +3,52 @@ type: docs
|
|||
title: "Initialize Dapr in your local environment"
|
||||
linkTitle: "Init Dapr locally"
|
||||
weight: 20
|
||||
description: "Fetch the Dapr sidecar binaries and install them locally using `dapr-init`"
|
||||
aliases:
|
||||
- /getting-started/install-dapr/
|
||||
- /getting-started/set-up-dapr/install-dapr/
|
||||
---
|
||||
|
||||
Now that you have the [Dapr CLI installed]({{<ref install-dapr-cli.md>}}), it's time to initialize Dapr on your local machine using the CLI.
|
||||
Now that you've [installed the Dapr CLI]({{<ref install-dapr-cli.md>}}), use the CLI to initialize Dapr on your local machine.
|
||||
|
||||
Dapr runs as a sidecar alongside your application, and in self-hosted mode this means it is a process on your local machine. Therefore, initializing Dapr includes fetching the Dapr sidecar binaries and installing them locally.
|
||||
Dapr runs as a sidecar alongside your application. In self-hosted mode, this means it is a process on your local machine. By initializing Dapr, you:
|
||||
|
||||
In addition, the default initialization process also creates a development environment that helps streamline application development with Dapr. This includes the following steps:
|
||||
- Fetch and install the Dapr sidecar binaries locally.
|
||||
- Create a development environment that streamlines application development with Dapr.
|
||||
|
||||
1. Running a **Redis container instance** to be used as a local state store and message broker
|
||||
1. Running a **Zipkin container instance** for observability
|
||||
1. Creating a **default components folder** with component definitions for the above
|
||||
1. Running a **Dapr placement service container instance** for local actor support
|
||||
Dapr initialization includes:
|
||||
|
||||
1. Running a **Redis container instance** to be used as a local state store and message broker.
|
||||
1. Running a **Zipkin container instance** for observability.
|
||||
1. Creating a **default components folder** with component definitions for the above.
|
||||
1. Running a **Dapr placement service container instance** for local actor support.
|
||||
|
||||
{{% alert title="Docker" color="primary" %}}
|
||||
This recommended development environment requires [Docker](https://docs.docker.com/install/). It is possible to initialize Dapr without a dependency on Docker (see [this guidance]({{<ref self-hosted-no-docker.md>}})) but next steps in this guide assume the recommended development environment.
|
||||
The recommended development environment requires [Docker](https://docs.docker.com/install/). While you can [initialize Dapr without a dependency on Docker]({{<ref self-hosted-no-docker.md>}})), the next steps in this guide assume the recommended Docker development environment.
|
||||
{{% /alert %}}
|
||||
|
||||
### Step 1: Open an elevated terminal
|
||||
|
||||
{{< tabs "Linux/MacOS" "Windows">}}
|
||||
{{< tabs "Linux/MacOS" "Windows">}}
|
||||
|
||||
{{% codetab %}}
|
||||
If you run your Docker commands with sudo, or the install path is `/usr/local/bin` (default install path), you will need to use `sudo` below.
|
||||
{{% /codetab %}}
|
||||
{{% codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
Make sure that you run Command Prompt as administrator (right click, run as administrator)
|
||||
{{% /codetab %}}
|
||||
You will need to use `sudo` for this quickstart if:
|
||||
|
||||
{{< /tabs >}}
|
||||
- You run your Docker commands with `sudo`, or
|
||||
- The install path is `/usr/local/bin` (default install path).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
Run Windows Terminal or command prompt as administrator.
|
||||
|
||||
1. Right click on the Windows Terminal or command prompt icon.
|
||||
1. Select **Run as administrator**.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
### Step 2: Run the init CLI command
|
||||
|
||||
|
|
@ -50,63 +64,65 @@ dapr init
|
|||
dapr --version
|
||||
```
|
||||
|
||||
Output should look like this:
|
||||
```
|
||||
CLI version: {{% dapr-latest-version cli="true" %}}
|
||||
Runtime version: {{% dapr-latest-version long="true" %}}
|
||||
```
|
||||
**Output:**
|
||||
|
||||
`CLI version: {{% dapr-latest-version cli="true" %}}` <br>
|
||||
`Runtime version: {{% dapr-latest-version long="true" %}}`
|
||||
|
||||
### Step 4: Verify containers are running
|
||||
|
||||
As mentioned above, the `dapr init` command launches several containers that will help you get started with Dapr. Verify this by running:
|
||||
As mentioned earlier, the `dapr init` command launches several containers that will help you get started with Dapr. Verify you have container instances with `daprio/dapr`, `openzipkin/zipkin`, and `redis` images running:
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
```
|
||||
|
||||
Make sure that instances with `daprio/dapr`, `openzipkin/zipkin`, and `redis` images are all running:
|
||||
**Output:**
|
||||
|
||||
```
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
0dda6684dc2e openzipkin/zipkin "/busybox/sh run.sh" 2 minutes ago Up 2 minutes 9410/tcp, 0.0.0.0:9411->9411/tcp dapr_zipkin
|
||||
9bf6ef339f50 redis "docker-entrypoint.s…" 2 minutes ago Up 2 minutes 0.0.0.0:6379->6379/tcp dapr_redis
|
||||
8d993e514150 daprio/dapr "./placement" 2 minutes ago Up 2 minutes 0.0.0.0:6050->50005/tcp dapr_placement
|
||||
```
|
||||
<img src="/images/install-dapr-selfhost/docker-containers.png" width=800>
|
||||
|
||||
### Step 5: Verify components directory has been initialized
|
||||
|
||||
On `dapr init`, the CLI also creates a default components folder which includes several YAML files with definitions for a state store, pub/sub and zipkin. These will be read by the Dapr sidecar, telling it to use the Redis container for state management and messaging and the Zipkin container for collecting traces.
|
||||
On `dapr init`, the CLI also creates a default components folder that contains several YAML files with definitions for a state store, Pub/sub, and Zipkin. The Dapr sidecar will read these components and use:
|
||||
|
||||
- In Linux/MacOS Dapr is initialized with default components and files in `$HOME/.dapr`.
|
||||
- For Windows Dapr is initialized to `%USERPROFILE%\.dapr\`
|
||||
- The Redis container for state management and messaging.
|
||||
- The Zipkin container for collecting traces.
|
||||
|
||||
Verify by opening your components directory:
|
||||
|
||||
- On Windows, under `%UserProfile%\.dapr`
|
||||
- On Linux/MacOS, under `~/.dapr`
|
||||
|
||||
{{< tabs "Linux/MacOS" "Windows">}}
|
||||
|
||||
{{% codetab %}}
|
||||
Run:
|
||||
|
||||
```bash
|
||||
ls $HOME/.dapr
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
bin components config.yaml
|
||||
```
|
||||
**Output:**
|
||||
|
||||
`bin components config.yaml`
|
||||
|
||||
<br>
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
Using Command Prompt (not PowerShell), open `%USERPROFILE%\.dapr\` in file explorer:
|
||||
|
||||
```powershell
|
||||
explorer "%USERPROFILE%\.dapr\"
|
||||
```
|
||||
|
||||
You will see the Dapr config, Dapr binaries directory, and the default components directory for Dapr:
|
||||
**Result:**
|
||||
|
||||
<img src="/images/install-dapr-selfhost/windows-view-components.png" width=600>
|
||||
|
||||
<img src="/images/install-dapr-selfhost-windows.png" width=500>
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
{{< button text="Next step: Use the Dapr API >>" page="get-started-api" >}}
|
||||
<br>
|
||||
|
||||
{{< button text="Next step: Try Dapr quickstarts >>" page="getting-started/_index.md" >}}
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Try out Dapr quickstarts to learn core concepts"
|
||||
linkTitle: "Dapr Quickstarts"
|
||||
weight: 60
|
||||
description: "Tutorials with code samples that are aimed to get you started quickly with Dapr"
|
||||
---
|
||||
|
||||
The [Dapr Quickstarts](https://github.com/dapr/quickstarts/tree/v1.5.0) are a collection of tutorials with code samples that are aimed to get you started quickly with Dapr, each highlighting a different Dapr capability.
|
||||
|
||||
- A good place to start is the hello-world quickstart, it demonstrates how to run Dapr in standalone mode locally on your machine and demonstrates state management and service invocation in a simple application.
|
||||
- Next, if you are familiar with Kubernetes and want to see how to run the same application in a Kubernetes environment, look for the hello-kubernetes quickstart. Other quickstarts such as pub-sub, bindings and the distributed-calculator quickstart explore different Dapr capabilities include instructions for running both locally and on Kubernetes and can be completed in any order. A full list of the quickstarts can be found below.
|
||||
- At anytime, you can explore the Dapr documentation or SDK specific samples and come back to try additional quickstarts.
|
||||
- When you're done, consider exploring the [Dapr samples repository](https://github.com/dapr/samples) for additional code samples contributed by the community that show more advanced or specific usages of Dapr.
|
||||
|
||||
## Quickstarts
|
||||
|
||||
| Quickstart | Description |
|
||||
|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| [Hello World](https://github.com/dapr/quickstarts/tree/v1.6.0/hello-world) | Demonstrates how to run Dapr locally. Highlights service invocation and state management. |
|
||||
| [Hello Kubernetes](https://github.com/dapr/quickstarts/tree/v1.6.0/hello-kubernetes) | Demonstrates how to run Dapr in Kubernetes. Highlights service invocation and state management. |
|
||||
| [Distributed Calculator](https://github.com/dapr/quickstarts/tree/v1.6.0/distributed-calculator) | Demonstrates a distributed calculator application that uses Dapr services to power a React web app. Highlights polyglot (multi-language) programming, service invocation and state management. |
|
||||
| [Pub/Sub](https://github.com/dapr/quickstarts/tree/v1.6.0/pub-sub) | Demonstrates how to use Dapr to enable pub-sub applications. Uses Redis as a pub-sub component. |
|
||||
| [Bindings](https://github.com/dapr/quickstarts/tree/v1.6.0/bindings) | Demonstrates how to use Dapr to create input and output bindings to other components. Uses bindings to Kafka. |
|
||||
| [Observability](https://github.com/dapr/quickstarts/tree/v1.6.0/observability) | Demonstrates Dapr tracing capabilities. Uses Zipkin as a tracing component. |
|
||||
| [Secret Store](https://github.com/dapr/quickstarts/tree/v1.6.0/secretstore) | Demonstrates the use of Dapr Secrets API to access secret stores. |
|
||||
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Dapr Quickstarts"
|
||||
linkTitle: "Dapr Quickstarts"
|
||||
weight: 70
|
||||
description: "Try out Dapr quickstarts with code samples that are aimed to get you started quickly with Dapr"
|
||||
no_list: true
|
||||
---
|
||||
|
||||
Hit the ground running with our Dapr quickstarts, complete with code samples aimed to get you started quickly with Dapr.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
We are actively working on adding to our quickstart library. In the meantime, you can explore Dapr through our [tutorials]({{< ref "getting-started/tutorials/_index.md" >}}).
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
#### Before you begin
|
||||
|
||||
- [Set up your local Dapr environment]({{< ref "install-dapr-cli.md" >}}).
|
||||
|
||||
## Quickstarts
|
||||
|
||||
| Quickstarts | Description |
|
||||
| ----------- | ----------- |
|
||||
| [Publish and Subscribe]({{< ref pubsub-quickstart.md >}}) | Get started with Dapr's Publish and Subscribe building block. |
|
||||
| State Management | While we work on quickstarts for Dapr's State Management, get started with our [examples on GitHub](https://github.com/dapr/quickstarts/state_management). |
|
||||
| Service Invocation | While we work on quickstarts for Dapr's Service Invocation, get started with our [examples on GitHub](https://github.com/dapr/quickstarts/service_invocation). |
|
||||
| Bindings | Coming soon. |
|
||||
| Actors | Coming soon. |
|
||||
| Observability | Coming soon. |
|
||||
| Secrets Management | Coming soon. |
|
||||
| Configuration | Coming soon. |
|
||||
|
|
@ -0,0 +1,599 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Quickstart: Publish and Subscribe"
|
||||
linkTitle: "Publish and Subscribe"
|
||||
weight: 70
|
||||
description: "Get started with Dapr's Publish and Subscribe building block"
|
||||
---
|
||||
|
||||
Let's take a look at Dapr's [Publish and Subscribe (Pub/sub) building block]({{< ref pubsub >}}). In this quickstart, you will run a publisher microservice and a subscriber microservice to demonstrate how Dapr enables a Pub/sub pattern.
|
||||
|
||||
1. Using a publisher service, developers can repeatedly publish messages to a topic.
|
||||
1. [A Pub/sub component](https://docs.dapr.io/concepts/components-concept/#pubsub-brokers) queues or brokers those messages. Our example below uses Redis, you can use RabbitMQ, Kafka, etc.
|
||||
1. The subscriber to that topic pulls messages from the queue and processes them.
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-diagram.png" width=800 style="padding-bottom:15px;">
|
||||
|
||||
Select your preferred language-specific Dapr SDK before proceeding with the quickstart.
|
||||
|
||||
{{< tabs "Python" "JavaScript" ".NET" "Java" >}}
|
||||
<!-- Python -->
|
||||
{{% codetab %}}
|
||||
|
||||
### Pre-requisites
|
||||
|
||||
For this example, you will need:
|
||||
|
||||
- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
|
||||
- [Python 3.7+ installed](https://www.python.org/downloads/).
|
||||
- [Docker Desktop](https://www.docker.com/products/docker-desktop).
|
||||
|
||||
### Step 1: Set up the environment
|
||||
|
||||
Clone the sample we've provided.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/dapr/quickstarts.git
|
||||
```
|
||||
|
||||
### Step 2: Publish a topic
|
||||
|
||||
In a terminal window, navigate to the `checkout` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/python/sdk/checkout
|
||||
```
|
||||
|
||||
Install the dependencies:
|
||||
|
||||
```bash
|
||||
pip3 install -r requirements.txt
|
||||
```
|
||||
|
||||
Run the `checkout` publisher service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-id checkout --components-path ../components -- python3 app.py
|
||||
```
|
||||
|
||||
In the `checkout` publisher, we're publishing the orderId message to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop:
|
||||
|
||||
```python
|
||||
while True:
|
||||
order = {'orderid': random.randint(1, 1000)}
|
||||
|
||||
with DaprClient() as client:
|
||||
# Publish an event/message using Dapr PubSub
|
||||
result = client.publish_event(
|
||||
pubsub_name='order_pub_sub',
|
||||
topic_name='orders',
|
||||
data=json.dumps(order),
|
||||
data_content_type='application/json',
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3: Subscribe to topics
|
||||
|
||||
In a new terminal window, navigate to the `order-processor` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/python/sdk/order-processor
|
||||
```
|
||||
|
||||
Install the dependencies:
|
||||
|
||||
```bash
|
||||
pip3 install -r requirements.txt
|
||||
```
|
||||
|
||||
Run the `order-processor` subscriber service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-id order-processor --app-port 5001 --components-path ../../components -- python3 app.py
|
||||
```
|
||||
|
||||
In the `order-processor` subscriber, we're subscribing to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar.
|
||||
|
||||
```py
|
||||
# Register Dapr pub/sub subscriptions
|
||||
@app.route('/dapr/subscribe', methods=['GET'])
|
||||
def subscribe():
|
||||
subscriptions = [{
|
||||
'pubsubname': 'order_pub_sub',
|
||||
'topic': 'orders',
|
||||
'route': 'orders'
|
||||
}]
|
||||
print('Dapr pub/sub is subscribed to: ' + json.dumps(subscriptions))
|
||||
return jsonify(subscriptions)
|
||||
|
||||
|
||||
# Dapr subscription in /dapr/subscribe sets up this route
|
||||
@app.route('/orders', methods=['POST'])
|
||||
def orders_subscriber():
|
||||
event = from_http(request.headers, request.get_data())
|
||||
print('Subscriber received : ' + event.data['orderid'], flush=True)
|
||||
return json.dumps({'success': True}), 200, {
|
||||
'ContentType': 'application/json'}
|
||||
|
||||
|
||||
app.run(port=5001)
|
||||
```
|
||||
|
||||
### Step 4: View the Pub/sub outputs
|
||||
|
||||
Notice, as specified in the code above, the publisher pushes a random number to the Dapr sidecar while the subscriber receives it.
|
||||
|
||||
Publisher output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-python-publisher-output.png" width=600 style="padding-bottom:15px;">
|
||||
|
||||
Subscriber output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-python-subscriber-output.png" width=600 style="padding-bottom:25px;">
|
||||
|
||||
#### `pubsub.yaml` component file
|
||||
|
||||
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
|
||||
|
||||
- On Windows, under `%UserProfile%\.dapr\components\pubsub.yaml`
|
||||
- On Linux/MacOS, under `~/.dapr/components/pubsub.yaml`
|
||||
|
||||
With the `pubsub.yaml` component, you can easily swap out underlying components without application code changes.
|
||||
|
||||
The Redis `pubsub.yaml` file included for this quickstart contains the following:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: order_pub_sub
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: localhost:6379
|
||||
- name: redisPassword
|
||||
value: ""
|
||||
```
|
||||
|
||||
In the YAML file:
|
||||
|
||||
- `metadata/name` is how your application talks to the component.
|
||||
- `spec/metadata` defines the connection to the instance of the component.
|
||||
- `scopes` specify which application can use the component.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
<!-- JavaScript -->
|
||||
{{% codetab %}}
|
||||
|
||||
### Pre-requisites
|
||||
|
||||
For this example, you will need:
|
||||
|
||||
- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
|
||||
- [Latest Node.js installed](https://nodejs.org/en/download/).
|
||||
- [Docker Desktop](https://www.docker.com/products/docker-desktop).
|
||||
|
||||
### Step 1: Set up the environment
|
||||
|
||||
Clone the sample we've set up:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/dapr/quickstarts.git
|
||||
```
|
||||
|
||||
### Step 2: Publish a topic
|
||||
|
||||
In a terminal window, navigate to the `checkout` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/javascript/sdk/checkout
|
||||
```
|
||||
|
||||
Install dependencies, which will include the `dapr-client` package from the JavaScript SDK:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Verify you have the following files included in the service directory:
|
||||
|
||||
- `package.json`
|
||||
- `package-lock.json`
|
||||
|
||||
Run the `checkout` publisher service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-id checkout --app-protocol http --dapr-http-port 3500 --components-path ../../../components -- npm run start
|
||||
```
|
||||
|
||||
In the `checkout` publisher service, we're publishing the orderId message to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop:
|
||||
|
||||
```js
|
||||
await client.pubsub.publish(PUBSUB_NAME, PUBSUB_TOPIC, order);
|
||||
console.log("Published data: " + JSON.stringify(order));
|
||||
```
|
||||
|
||||
### Step 3: Subscribe to topics
|
||||
|
||||
In a new terminal window, navigate to the `order-processor` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/javascript/sdk/order-processor
|
||||
```
|
||||
|
||||
Install dependencies, which will include the `dapr-client` package from the JavaScript SDK:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Verify you have the following files included in the service directory:
|
||||
|
||||
- `package.json`
|
||||
- `package-lock.json`
|
||||
|
||||
Run the `order-processor` subscriber service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-port 5001 --app-id order-processing --app-protocol http --dapr-http-port 3501 --components-path ../../../components -- npm run start
|
||||
```
|
||||
|
||||
In the `order-processor` subscriber, we're subscribing to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar.
|
||||
|
||||
```js
|
||||
server.pubsub.subscribe("order_pub_sub", "orders", (data) => console.log("Subscriber received: " + JSON.stringify(data)));
|
||||
```
|
||||
|
||||
### Step 4: View the Pub/sub outputs
|
||||
|
||||
Notice, as specified in the code above, the publisher pushes a random number to the Dapr sidecar while the subscriber receives it.
|
||||
|
||||
Publisher output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-js-publisher-output.png" width=600 style="padding-bottom:15px;">
|
||||
|
||||
Subscriber output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-js-subscriber-output.png" width=600 style="padding-bottom:25px;">
|
||||
|
||||
#### `pubsub.yaml` component file
|
||||
|
||||
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
|
||||
|
||||
- On Windows, under `%UserProfile%\.dapr\components\pubsub.yaml`
|
||||
- On Linux/MacOS, under `~/.dapr/components/pubsub.yaml`
|
||||
|
||||
With the `pubsub.yaml` component, you can easily swap out underlying components without application code changes.
|
||||
|
||||
The Redis `pubsub.yaml` file included for this quickstart contains the following:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: order_pub_sub
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: localhost:6379
|
||||
- name: redisPassword
|
||||
value: ""
|
||||
```
|
||||
|
||||
In the YAML file:
|
||||
|
||||
- `metadata/name` is how your application talks to the component.
|
||||
- `spec/metadata` defines the connection to the instance of the component.
|
||||
- `scopes` specify which application can use the component.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
<!-- .NET -->
|
||||
{{% codetab %}}
|
||||
|
||||
### Pre-requisites
|
||||
|
||||
For this example, you will need:
|
||||
|
||||
- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
|
||||
- [.NET SDK or .NET 6 SDK installed](https://dotnet.microsoft.com/en-us/download).
|
||||
- [Docker Desktop](https://www.docker.com/products/docker-desktop).
|
||||
|
||||
### Step 1: Set up the environment
|
||||
|
||||
Clone the sample we've set up:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/dapr/quickstarts.git
|
||||
```
|
||||
|
||||
### Step 2: Publish a topic
|
||||
|
||||
In a terminal window, navigate to the `checkout` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/csharp/sdk/checkout
|
||||
```
|
||||
|
||||
Recall NuGet packages:
|
||||
|
||||
```bash
|
||||
dotnet restore
|
||||
dotnet build
|
||||
```
|
||||
|
||||
Run the `checkout` publisher service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-id checkout --components-path ../../components -- dotnet run
|
||||
```
|
||||
|
||||
In the `checkout` publisher, we're publishing the orderId message to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop:
|
||||
|
||||
```cs
|
||||
while(true) {
|
||||
Random random = new Random();
|
||||
var order = new Order(random.Next(1,1000));
|
||||
using var client = new DaprClientBuilder().Build();
|
||||
|
||||
// Publish an event/message using Dapr PubSub
|
||||
await client.PublishEventAsync("order_pub_sub", "orders", order);
|
||||
Console.WriteLine("Published data: " + order);
|
||||
|
||||
await Task.Delay(TimeSpan.FromSeconds(1));
|
||||
}
|
||||
|
||||
public record Order([property: JsonPropertyName("orderId")] int OrderId);
|
||||
```
|
||||
|
||||
### Step 3: Subscribe to topics
|
||||
|
||||
In a new terminal window, navigate to the `order-processor` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/csharp/sdk/order-processor
|
||||
```
|
||||
|
||||
Recall NuGet packages:
|
||||
|
||||
```bash
|
||||
dotnet restore
|
||||
dotnet build
|
||||
```
|
||||
|
||||
Run the `order-processor` subscriber service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-id order-processor --components-path ../../components --app-port 5001 -- dotnet run
|
||||
```
|
||||
|
||||
In the `order-processor` subscriber, we're subscribing to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar.
|
||||
|
||||
```cs
|
||||
// Dapr subscription in [Topic] routes orders topic to this route
|
||||
app.MapPost("/orders", [Topic("order_pub_sub", "orders")] (Order order) => {
|
||||
Console.WriteLine("Subscriber received : " + order);
|
||||
return Results.Ok(order);
|
||||
});
|
||||
|
||||
public record Order([property: JsonPropertyName("orderId")] int OrderId);
|
||||
```
|
||||
|
||||
### Step 4: View the Pub/sub outputs
|
||||
|
||||
Notice, as specified in the code above, the publisher pushes a random number to the Dapr sidecar while the subscriber receives it.
|
||||
|
||||
Publisher output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-dotnet-publisher-output.png" width=600 style="padding-bottom:15px;">
|
||||
|
||||
Subscriber output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-dotnet-subscriber-output.png" width=600 style="padding-bottom:25px;">
|
||||
|
||||
#### `pubsub.yaml` component file
|
||||
|
||||
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
|
||||
|
||||
- On Windows, under `%UserProfile%\.dapr\components\pubsub.yaml`
|
||||
- On Linux/MacOS, under `~/.dapr/components/pubsub.yaml`
|
||||
|
||||
With the `pubsub.yaml` component, you can easily swap out underlying components without application code changes.
|
||||
|
||||
The Redis `pubsub.yaml` file included for this quickstart contains the following:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: order_pub_sub
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: localhost:6379
|
||||
- name: redisPassword
|
||||
value: ""
|
||||
```
|
||||
|
||||
In the YAML file:
|
||||
|
||||
- `metadata/name` is how your application talks to the component.
|
||||
- `spec/metadata` defines the connection to the instance of the component.
|
||||
- `scopes` specify which application can use the component.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
<!-- Java -->
|
||||
{{% codetab %}}
|
||||
|
||||
### Pre-requisites
|
||||
|
||||
For this example, you will need:
|
||||
|
||||
- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started).
|
||||
- Java JDK 11 (or greater):
|
||||
- [Oracle JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html#JDK11), or
|
||||
- [OpenJDK](https://jdk.java.net/13/)
|
||||
- [Apache Maven](https://maven.apache.org/install.html), version 3.x.
|
||||
- [Docker Desktop](https://www.docker.com/products/docker-desktop).
|
||||
|
||||
### Step 1: Set up the environment
|
||||
|
||||
Clone the sample we've provided.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/dapr/quickstarts.git
|
||||
```
|
||||
|
||||
### Step 2: Publish a topic
|
||||
|
||||
In a terminal window, navigate to the `checkout` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/java/sdk/checkout
|
||||
```
|
||||
|
||||
Install the dependencies:
|
||||
|
||||
```bash
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
Run the `checkout` publisher service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-id checkout --components-path ../../../components -- java -jar target/CheckoutService-0.0.1-SNAPSHOT.jar
|
||||
```
|
||||
|
||||
In the `checkout` publisher, we're publishing the orderId message to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. As soon as the service starts, it publishes in a loop:
|
||||
|
||||
```java
|
||||
public static void main(String[] args) throws InterruptedException{
|
||||
String TOPIC_NAME = "orders";
|
||||
String PUBSUB_NAME = "order_pub_sub";
|
||||
|
||||
for (int i = 0; i <= 10; i++) {
|
||||
int orderId = i;
|
||||
Order order = new Order(orderId);
|
||||
DaprClient client = new DaprClientBuilder().build();
|
||||
|
||||
// Publish an event/message using Dapr PubSub
|
||||
client.publishEvent(
|
||||
PUBSUB_NAME,
|
||||
TOPIC_NAME,
|
||||
order).block();
|
||||
logger.info("Published data: " + order.getOrderId());
|
||||
TimeUnit.MILLISECONDS.sleep(5000);
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Subscribe to topics
|
||||
|
||||
In a new terminal window, navigate to the `order-processor` directory.
|
||||
|
||||
```bash
|
||||
cd pub_sub/java/sdk/order-processor
|
||||
```
|
||||
|
||||
Install the dependencies:
|
||||
|
||||
```bash
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
Run the `order-processor` subscriber service alongside a Dapr sidecar.
|
||||
|
||||
```bash
|
||||
dapr run --app-port 8080 --app-id order-processor --components-path ../../../components -- java -jar target/OrderProcessingService-0.0.1-SNAPSHOT.jar
|
||||
```
|
||||
|
||||
In the `order-processor` subscriber, we're subscribing to the Redis instance called `order_pub_sub` [(as defined in the `pubsub.yaml` component)]({{< ref "#pubsubyaml-component-file" >}}) and topic `orders`. This enables your app code to talk to the Redis component instance through the Dapr sidecar.
|
||||
|
||||
```java
|
||||
@Topic(name = "orders", pubsubName = "order_pub_sub")
|
||||
@PostMapping(path = "/orders", consumes = MediaType.ALL_VALUE)
|
||||
public Mono<ResponseEntity> getCheckout(@RequestBody(required = false) CloudEvent<Order> cloudEvent) {
|
||||
return Mono.fromSupplier(() -> {
|
||||
try {
|
||||
logger.info("Subscriber received: " + cloudEvent.getData().getOrderId());
|
||||
return ResponseEntity.ok("SUCCESS");
|
||||
} catch (Exception e) {
|
||||
throw new RuntimeException(e);
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: View the Pub/sub outputs
|
||||
|
||||
Notice, as specified in the code above, the publisher pushes a random number to the Dapr sidecar while the subscriber receives it.
|
||||
|
||||
Publisher output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-java-publisher-output.png" width=600 style="padding-bottom:15px;">
|
||||
|
||||
Subscriber output:
|
||||
|
||||
<img src="/images/pubsub-quickstart/pubsub-java-subscriber-output.png" width=600 style="padding-bottom:25px;">
|
||||
|
||||
#### `pubsub.yaml` component file
|
||||
|
||||
When you run `dapr init`, Dapr creates a default Redis `pubsub.yaml` and runs a Redis container on your local machine, located:
|
||||
|
||||
- On Windows, under `%UserProfile%\.dapr\components\pubsub.yaml`
|
||||
- On Linux/MacOS, under `~/.dapr/components/pubsub.yaml`
|
||||
|
||||
With the `pubsub.yaml` component, you can easily swap out underlying components without application code changes.
|
||||
|
||||
The Redis `pubsub.yaml` file included for this quickstart contains the following:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: order_pub_sub
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: localhost:6379
|
||||
- name: redisPassword
|
||||
value: ""
|
||||
scopes:
|
||||
- orderprocessing
|
||||
- checkout
|
||||
```
|
||||
|
||||
In the YAML file:
|
||||
|
||||
- `metadata/name` is how your application talks to the component.
|
||||
- `spec/metadata` defines the connection to the instance of the component.
|
||||
- `scopes` specify which application can use the component.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Next steps
|
||||
|
||||
- Set up Pub/sub using HTTP instead of an SDK.
|
||||
- [Python](https://github.com/dapr/quickstarts/tree/feature/new_quickstarts/pub_sub/python/http)
|
||||
- [JavaScript](https://github.com/dapr/quickstarts/tree/feature/new_quickstarts/pub_sub/javascript/http)
|
||||
- [.NET](https://github.com/dapr/quickstarts/tree/feature/new_quickstarts/pub_sub/csharp/http)
|
||||
- [Java](https://github.com/dapr/quickstarts/tree/feature/new_quickstarts/pub_sub/java/http)
|
||||
- Learn about [Pub/sub routing]({{< ref howto-route-messages >}})
|
||||
- Learn about [topic scoping]({{< ref pubsub-scopes.md >}})
|
||||
- Learn about [message time-to-live]({{< ref pubsub-message-ttl.md >}})
|
||||
- Learn [how to configure Pub/sub components with multiple namespaces]({{< ref pubsub-namespaces.md >}})
|
||||
- List of [Pub/sub components]({{< ref setup-pubsub >}})
|
||||
- Read the [API reference]({{< ref pubsub_api.md >}})
|
||||
|
||||
{{< button text="Explore Dapr tutorials >>" page="getting-started/tutorials/_index.md" >}}
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Dapr Tutorials"
|
||||
linkTitle: "Dapr Tutorials"
|
||||
weight: 70
|
||||
description: "Walk through in-depth examples to learn more about how to work with Dapr concepts"
|
||||
no_list: true
|
||||
---
|
||||
|
||||
Now that you've already initialized Dapr and experimented with some of Dapr's building blocks, walk through our more detailed tutorials.
|
||||
|
||||
#### Before you begin
|
||||
|
||||
- [Set up your local Dapr environment]({{< ref "install-dapr-cli.md" >}}).
|
||||
- [Explore one of Dapr's building blocks via our quickstarts]({{< ref "getting-started/quickstarts/_index.md" >}}).
|
||||
|
||||
## Tutorials
|
||||
|
||||
Thanks to our expansive Dapr community, we offer tutorials hosted both on Dapr Docs and on our [GitHub repository](https://github.com/dapr/quickstarts).
|
||||
|
||||
| Dapr Docs tutorials | Description |
|
||||
|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| [Define a component]({{< ref get-started-component.md >}}) | Create a component definition file to interact with the Secrets building block.
|
||||
| [Configure State & Pub/sub]({{< ref configure-state-pubsub.md >}}) | Configure State Store and Pub/sub message broker components for Dapr.
|
||||
|
||||
| GitHub tutorials | Description |
|
||||
|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| [Hello World](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-world) | *Recommended* <br> Demonstrates how to run Dapr locally. Highlights service invocation and state management. |
|
||||
| [Hello World Kubernetes](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-kubernetes) | *Recommended* <br> Demonstrates how to run Dapr in Kubernetes. Highlights service invocation and state management. |
|
||||
| [Distributed Calculator](https://github.com/dapr/quickstarts/tree/master/tutorials/distributed-calculator) | Demonstrates a distributed calculator application that uses Dapr services to power a React web app. Highlights polyglot (multi-language) programming, service invocation and state management. |
|
||||
| [Pub/Sub](https://github.com/dapr/quickstarts/tree/master/tutorials/pub-sub) | Demonstrates how to use Dapr to enable pub-sub applications. Uses Redis as a pub-sub component. |
|
||||
| [Bindings](https://github.com/dapr/quickstarts/tree/master/tutorials/bindings) | Demonstrates how to use Dapr to create input and output bindings to other components. Uses bindings to Kafka. |
|
||||
| [Observability](https://github.com/dapr/quickstarts/tree/master/tutorials/observability) | Demonstrates Dapr tracing capabilities. Uses Zipkin as a tracing component. |
|
||||
| [Secret Store](https://github.com/dapr/quickstarts/tree/master/tutorials/secretstore) | Demonstrates the use of Dapr Secrets API to access secret stores. |
|
||||
|
|
@ -0,0 +1,339 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Tutorial: Configure state store and pub/sub message broker"
|
||||
linkTitle: "Configure state & pub/sub"
|
||||
weight: 80
|
||||
description: "Configure state store and pub/sub message broker components for Dapr"
|
||||
aliases:
|
||||
- /getting-started/tutorials/configure-redis/
|
||||
---
|
||||
|
||||
To get up and running with the state and Pub/sub building blocks, you'll need two components:
|
||||
|
||||
- A state store component for persistence and restoration.
|
||||
- As pub/sub message broker component for async-style message delivery.
|
||||
|
||||
A full list of supported components can be found here:
|
||||
- [Supported state stores]({{< ref supported-state-stores >}})
|
||||
- [Supported pub/sub message brokers]({{< ref supported-pubsub >}})
|
||||
|
||||
For this tutorial, we describe how to get up and running with Redis.
|
||||
|
||||
### Step 1: Create a Redis store
|
||||
|
||||
Dapr can use any Redis instance, either:
|
||||
|
||||
- Containerized on your local dev machine, or
|
||||
- A managed cloud service.
|
||||
|
||||
If you already have a Redis store, move on to the [configuration](#configure-dapr-components) section.
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes" "Azure" "AWS" "GCP" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
Redis is automatically installed in self-hosted environments by the Dapr CLI as part of the initialization process. You are all set! Skip ahead to the [next steps](#next-steps).
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
You can use [Helm](https://helm.sh/) to create a Redis instance in our Kubernetes cluster. Before beginning, [install Helm v3](https://github.com/helm/helm#install).
|
||||
|
||||
Install Redis into your cluster:
|
||||
|
||||
```bash
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
helm repo update
|
||||
helm install redis bitnami/redis
|
||||
```
|
||||
|
||||
For Dapr's Pub/sub functionality, you'll need at least Redis version 5. For state store, you can use a lower version.
|
||||
|
||||
Run `kubectl get pods` to see the Redis containers now running in your cluster:
|
||||
|
||||
```bash
|
||||
$ kubectl get pods
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
redis-master-0 1/1 Running 0 69s
|
||||
redis-replicas-0 1/1 Running 0 69s
|
||||
redis-replicas-1 1/1 Running 0 22s
|
||||
```
|
||||
|
||||
For Kubernetes:
|
||||
- The hostname is `redis-master.default.svc.cluster.local:6379`
|
||||
- The secret, `redis`, is created automatically.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
Verify you have an [Azure subscription](https://azure.microsoft.com/en-us/free/).
|
||||
|
||||
1. Open and log into the [Azure portal](https://ms.portal.azure.com/#create/Microsoft.Cache) to start the Azure Redis Cache creation flow.
|
||||
1. Fill out the necessary information.
|
||||
- Dapr Pub/sub uses [Redis streams](https://redis.io/topics/streams-intro) introduced by Redis 5.0. To use Azure Redis Cache for Pub/sub, set the version to *(PREVIEW) 6*.
|
||||
1. Click **Create** to kickoff deployment of your Redis instance.
|
||||
1. Make note of the Redis instance hostname from the **Overview** page in Azure portal for later.
|
||||
- It should look like `xxxxxx.redis.cache.windows.net:6380`.
|
||||
1. Once your instance is created, grab your access key:
|
||||
1. Navigate to **Access Keys** under **Settings**.
|
||||
1. Create a Kubernetes secret to store your Redis password:
|
||||
|
||||
```bash
|
||||
kubectl create secret generic redis --from-literal=redis-password=*********
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
1. Deploy a Redis instance from [AWS Redis](https://aws.amazon.com/redis/).
|
||||
1. Note the Redis hostname in the AWS portal for later.
|
||||
1. Create a Kubernetes secret to store your Redis password:
|
||||
|
||||
```bash
|
||||
kubectl create secret generic redis --from-literal=redis-password=*********
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
1. Deploy a MemoryStore instance from [GCP Cloud MemoryStore](https://cloud.google.com/memorystore/).
|
||||
1. Note the Redis hostname in the GCP portal for later.
|
||||
1. Create a Kubernetes secret to store your Redis password:
|
||||
|
||||
```bash
|
||||
kubectl create secret generic redis --from-literal=redis-password=*********
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
### Step 2: Configure Dapr components
|
||||
|
||||
Dapr defines resources to use for building block functionality with components. These steps go through how to connect the resources you created above to Dapr for state and pub/sub.
|
||||
|
||||
#### Locate your component filese
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
In self-hosted mode, component files are automatically created under:
|
||||
- **Windows**: `%USERPROFILE%\.dapr\components\`
|
||||
- **Linux/MacOS**: `$HOME/.dapr/components`
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
Since Kubernetes files are applied with `kubectl`, they can be created in any directory.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
#### Create State store component
|
||||
|
||||
Create a file named `redis-state.yaml`, and paste the following:
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
namespace: default
|
||||
spec:
|
||||
type: state.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: localhost:6379
|
||||
- name: redisPassword
|
||||
secretKeyRef:
|
||||
name: redis
|
||||
key: redis-password
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
namespace: default
|
||||
spec:
|
||||
type: state.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <REPLACE WITH HOSTNAME FROM ABOVE - for Redis on Kubernetes it is redis-master.default.svc.cluster.local:6379>
|
||||
- name: redisPassword
|
||||
secretKeyRef:
|
||||
name: redis
|
||||
key: redis-password
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
Note the above code example uses the Kubernetes secret you created earlier when setting up a cluster.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
{{% alert title="Other stores" color="primary" %}}
|
||||
If using a state store other than Redis, refer to the [supported state stores]({{< ref supported-state-stores >}}) for information on options to set.
|
||||
{{% /alert %}}
|
||||
|
||||
#### Create Pub/sub message broker component
|
||||
|
||||
Create a file called `redis-pubsub.yaml`, and paste the following:
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: pubsub
|
||||
namespace: default
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: localhost:6379
|
||||
- name: redisPassword
|
||||
secretKeyRef:
|
||||
name: redis
|
||||
key: redis-password
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: pubsub
|
||||
namespace: default
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <REPLACE WITH HOSTNAME FROM ABOVE - for Redis on Kubernetes it is redis-master.default.svc.cluster.local:6379>
|
||||
- name: redisPassword
|
||||
secretKeyRef:
|
||||
name: redis
|
||||
key: redis-password
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
Note the above code example uses the Kubernetes secret you created earlier when setting up a cluster.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
{{% alert title="Other stores" color="primary" %}}
|
||||
If using a pub/sub message broker other than Redis, refer to the [supported pub/sub message brokers]({{< ref supported-pubsub >}}) for information on options to set.
|
||||
{{% /alert %}}
|
||||
|
||||
#### Hard coded passwords (not recommended)
|
||||
|
||||
For development purposes *only*, you can skip creating Kubernetes secrets and place passwords directly into the Dapr component file:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
namespace: default
|
||||
spec:
|
||||
type: state.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <HOST>
|
||||
- name: redisPassword
|
||||
value: <PASSWORD>
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: pubsub
|
||||
namespace: default
|
||||
spec:
|
||||
type: pubsub.redis
|
||||
version: v1
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <HOST>
|
||||
- name: redisPassword
|
||||
value: <PASSWORD>
|
||||
# uncomment below for connecting to redis cache instances over TLS (ex - Azure Redis Cache)
|
||||
# - name: enableTLS
|
||||
# value: true
|
||||
```
|
||||
|
||||
### Step 3: Apply the configuration
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes">}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
When you run `dapr init`, Dapr creates a default redis `pubsub.yaml` on your local machine. Verify by opening your components directory:
|
||||
|
||||
- On Windows, under `%UserProfile%\.dapr\components\pubsub.yaml`
|
||||
- On Linux/MacOS, under `~/.dapr/components/pubsub.yaml`
|
||||
|
||||
For new component files:
|
||||
|
||||
1. Create a new `components` directory in your app folder containing the YAML files.
|
||||
1. Provide the path to the `dapr run` command with the flag `--components-path`
|
||||
|
||||
If you initialized Dapr in [slim mode]({{< ref self-hosted-no-docker.md >}}) (without Docker), you need to manually create the default directory, or always specify a components directory using `--components-path`.
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
Run `kubectl apply -f <FILENAME>` for both state and pubsub files:
|
||||
|
||||
```bash
|
||||
kubectl apply -f redis-state.yaml
|
||||
kubectl apply -f redis-pubsub.yaml
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Next steps
|
||||
[Try out a Dapr quickstart]({{< ref quickstarts.md >}})
|
||||
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Quickstart: Define a component"
|
||||
linkTitle: "Define a component"
|
||||
weight: 70
|
||||
description: "Create a component definition file to interact with the Secrets building block"
|
||||
---
|
||||
|
||||
When building an app, you'd most likely create your own component file definitions, depending on the building block and specific component that you'd like to use.
|
||||
|
||||
In this quickstart, you will create a component definition file to interact with the [Secrets building block]({{< ref secrets >}}):
|
||||
|
||||
- Create a local JSON secret store.
|
||||
- Register the secret store with Dapr using a component definition file.
|
||||
- Obtain the secret using the Dapr HTTP API.
|
||||
|
||||
## Step 1: Create a JSON secret store
|
||||
|
||||
Dapr supports [many types of secret stores]({{< ref supported-secret-stores >}}), but for this quickstart, create a local JSON file named `mysecrets.json` with the following secret:
|
||||
|
||||
```json
|
||||
{
|
||||
"my-secret" : "I'm Batman"
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2: Create a secret store Dapr component
|
||||
|
||||
1. Create a new directory named `my-components` to hold the new component file:
|
||||
|
||||
```bash
|
||||
mkdir my-components
|
||||
```
|
||||
|
||||
1. Navigate into this directory.
|
||||
|
||||
```bash
|
||||
cd my-components
|
||||
```
|
||||
|
||||
1. Create a new file `localSecretStore.yaml` with the following contents:
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: my-secret-store
|
||||
namespace: default
|
||||
spec:
|
||||
type: secretstores.local.file
|
||||
version: v1
|
||||
metadata:
|
||||
- name: secretsFile
|
||||
value: <PATH TO SECRETS FILE>/mysecrets.json
|
||||
- name: nestedSeparator
|
||||
value: ":"
|
||||
```
|
||||
|
||||
In the above file definition:
|
||||
- `type: secretstores.local.file` tells Dapr to use the local file component as a secret store.
|
||||
- The metadata fields provide component-specific information needed to work with this component. In this case, the secret store JSON path is relative to where you call `dapr run`.
|
||||
|
||||
## Step 3: Run the Dapr sidecar
|
||||
|
||||
Launch a Dapr sidecar that will listen on port 3500 for a blank application named `myapp`:
|
||||
|
||||
```bash
|
||||
dapr run --app-id myapp --dapr-http-port 3500 --components-path ./my-components
|
||||
```
|
||||
|
||||
{{% alert title="Tip" color="primary" %}}
|
||||
If an error message occurs, stating the `app-id` is already in use, you may need to stop any currently running Dapr sidecars. Stop the sidecar before running the next `dapr run` command by either:
|
||||
|
||||
- Pressing Ctrl+C or Command+C.
|
||||
- Running the `dapr stop` command in the terminal.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
## Step 4: Get a secret
|
||||
|
||||
In a separate terminal, run:
|
||||
|
||||
{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}}
|
||||
{{% codetab %}}
|
||||
|
||||
```bash
|
||||
curl http://localhost:3500/v1.0/secrets/my-secret-store/my-secret
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/secrets/my-secret-store/my-secret'
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
{{< /tabs >}}
|
||||
|
||||
**Output:**
|
||||
|
||||
```json
|
||||
{"my-secret":"I'm Batman"}
|
||||
```
|
||||
|
||||
{{< button text="Next step: Set up a Pub/sub broker >>" page="pubsub-quickstart" >}}
|
||||
|
|
@ -43,7 +43,7 @@ kubectl create namespace namespace-a
|
|||
kubectl config set-context --current --namespace=namespace-a
|
||||
```
|
||||
|
||||
Install Redis (master and slave) on `namespace-a`, following [these instructions]({{< ref "configure-state-pubsub.md" >}}).
|
||||
Install Redis (master and slave) on `namespace-a`, following [these instructions]({{< ref "getting-started/tutorials/configure-state-pubsub.md" >}}).
|
||||
|
||||
Now, configure `deploy/redis.yaml`, paying attention to the hostname containing `namespace-a`.
|
||||
|
||||
|
|
|
|||
|
|
@ -173,4 +173,4 @@ dapr-sentry-9435776c7f-8f7yd 1/1 Running 0 40s
|
|||
|
||||
## Next steps
|
||||
|
||||
- [Configure state store & pubsub message broker]({{< ref configure-state-pubsub.md >}})
|
||||
- [Configure state store & pubsub message broker]({{< ref "getting-started/tutorials/configure-state-pubsub.md" >}})
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 116 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Loading…
Reference in New Issue