Merge pull request #3093 from hhunter-ms/issue_3047

`dapr run -f` docs
This commit is contained in:
Hannah Hunter 2023-02-07 11:55:49 -06:00 committed by GitHub
commit 211fa537b5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 249 additions and 9 deletions

View File

@ -0,0 +1,7 @@
---
type: docs
title: "Multi-App Run"
linkTitle: "Multi-App Run"
weight: 300
description: "Support for running multiple Dapr applications with one command"
---

View File

@ -0,0 +1,85 @@
---
type: docs
title: Multi-App Run overview
linkTitle: Multi-App Run overview
weight: 1000
description: Run multiple applications with one CLI command
---
{{% alert title="Note" color="primary" %}}
Multi-App Run is currently a preview feature only supported in Linux/MacOS.
{{% /alert %}}
Let's say you want to run several applications locally to test them together, similar to a production scenario. With a local Kubernetes cluster, you'd be able to do this with helm/deployment YAML files. You'd also have to build them as containers and set up Kubernetes, which can add some complexity.
Instead, you simply want to run them as local executables in self-hosted mode. However, self-hosted mode requires you to:
- Run multiple `dapr run` commands
- Keep track of all ports opened (you cannot have duplicate ports for different applications).
- Remember the resources folders and configuration files that each application refers to.
- Recall all of the additional flags you used to tweak the `dapr run` command behavior (`--app-health-check-path`, `--dapr-grpc-port`, `--unix-domain-socket`, etc.)
With Multi-App Run, you can start multiple applications in self-hosted mode using a single `dapr run -f` command using a template file. The template file describes how to start multiple applications as if you had run many separate CLI `run`commands. By default, this template file is called `dapr.yaml`.
## Multi-App Run template file
When you execute `dapr run -f .`, it uses the multi-app template file (named `dapr.yaml`) present in the current directory to run all the applications.
You can name template file with preferred name other than the default. For example `dapr run -f ./<your-preferred-file-name>.yaml`.
The following example includes some of the template properties you can customize for your applications. In the example, you can simultaneously launch 2 applications with app IDs of `processor` and `emit-metrics`.
```yaml
version: 1
apps:
- appID: processor
appDirPath: ../apps/processor/
appPort: 9081
daprHTTPPort: 3510
command: ["go","run", "app.go"]
- appID: emit-metrics
appDirPath: ../apps/emit-metrics/
daprHTTPPort: 3511
env:
DAPR_HOST_ADD: localhost
command: ["go","run", "app.go"]
```
For a more in-depth example and explanation of the template properties, see [Multi-app template]({{< ref multi-app-template.md >}}).
## Locations for resources and configuration files
You have options on where to place your applications' resources and configuration files when using Multi-App Run.
### Point to one file location (with convention)
You can set all of your applications resources and configurations at the `~/.dapr` root. This is helpful when all applications share the same resources path, like when testing on a local machine.
### Separate file locations for each application (with convention)
When using Multi-App Run, each application directory can have a `.dapr` folder, which contains a `config.yaml` file and a `resources` directory. Otherwise, if the `.dapr` directory is not present within the app directory, the default `~/.dapr/resources/` and `~/.dapr/config.yaml` locations are used.
If you decide to add a `.dapr` directory in each application directory, with a `/resources` directory and `config.yaml` file, you can specify different resources paths for each application. This approach remains within convention by using the default `~/.dapr`.
### Point to separate locations (custom)
You can also name each app directory's `.dapr` directory something other than `.dapr`, such as, `webapp`, or `backend`. This helps if you'd like to be explicit about resource or application directory paths.
## Logs
Logs for application and `daprd` are captured in separate files. These log files are created automatically under `.dapr/logs` directory under each application directory (`appDirPath` in the template). These log file names follow the pattern seen below:
- `<appID>_app_<timestamp>.log` (file name format for `app` log)
- `<appID>_daprd_<timestamp>.log` (file name format for `daprd` log)
Even if you've decided to rename your resources folder to something other than `.dapr`, the log files are written only to the `.dapr/logs` folder (created in the application directory).
## Watch the demo
Watch [this video for an overview on Multi-App Run](https://youtu.be/s1p9MNl4VGo?t=2456):
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/s1p9MNl4VGo?start=2456" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Next steps
[Learn the Multi-App Run template file structure and its properties]({{< ref multi-app-template.md >}})

View File

@ -0,0 +1,145 @@
---
type: docs
title: "How to: Use the Multi-App Run template file"
linkTitle: "How to: Use the Multi-App Run template"
weight: 2000
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.
{{% /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
- View started applications
- Stop the multi-app template
- Stucture the multi-app template file
## Use the multi-app template
You can use the multi-app template file in one of the following two ways:
### Execute by providing a directory path
When you provide a directory path, the CLI will try to locate the Multi-App Run template file, named `dapr.yaml` by default in the directory. If the file is not found, the CLI will return an error.
Execute the following CLI command to read the Multi-App Run template file, named `dapr.yaml` by default:
```cmd
# the template file needs to be called `dapr.yaml` by default if a directory path is given
dapr run -f <dir_path>
```
### Execute by providing a file path
If the Multi-App Run template file is named something other than `dapr.yaml`, then you can provide the relative or absolute file path to the command:
```cmd
dapr run -f ./path/to/<your-preferred-file-name>.yaml
```
## View the started applications
Once the multi-app template is running, you can view the started applications with the following command:
```cmd
dapr list
```
## Stop the multi-app template
Stop the multi-app run template anytime with either of the following commands:
```cmd
# the template file needs to be called `dapr.yaml` by default if a directory path is given
dapr stop -f
```
or:
```cmd
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.
```yaml
version: 1
common: # optional section for variables shared across apps
resourcesPath: ./app/components # any dapr resources to be shared across apps
env: # any environment variable shared across apps
- DEBUG: true
apps:
- appID: webapp # optional
appDirPath: .dapr/webapp/ # REQUIRED
resourcesPath: .dapr/resources # (optional) can be default 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"
command: ["python3" "app.py"]
- appID: backend # optional
appDirPath: .dapr/backend/ # REQUIRED
appProtocol: GRPC
appPort: 3000
unixDomainSocket: "/tmp/test-socket"
env:
- DEBUG: false
command: ["./backend"]
```
{{% alert title="Important" color="warning" %}}
The following rules apply for all the paths present in the template file:
- If the path is absolute, it is used as is.
- All relative paths under comman section should be provided relative to the template file path.
- `appDirPath` under apps section should be provided relative to the template file path.
- All relative paths under app section should be provided relative to the appDirPath.
{{% /alert %}}
## 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" >}}).
| 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 | Path to your Dapr resources. Can be default by convention; ignore if directory isn't found | `./app/components`, `./webapp/components` |
| `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` |
| `daprHTTPPort` | N | Dapr HTTP port | |
| `daprGRPCPort` | N | Dapr GRPC port | |
| `daprInternalGRPCPort` | N | gRPC port for the Dapr Internal API to listen on; used when parsing the value from a local DNS component | |
| `metricsPort` | N | The port that Dapr sends its metrics information to | |
| `unixDomainSocket` | N | Path to a unix domain socket dir mount. If specified, communication with the Dapr sidecar uses unix domain sockets for lower latency and greater throughput when compared to using TCP ports. Not available on Windows. | `/tmp/test-socket` |
| `profilePort` | N | The port for the profile server to listen on | |
| `enableProfiling` | N | Enable profiling via an HTTP endpoint | |
| `apiListenAddresses` | N | Dapr API listen addresses | |
| `logLevel` | N | The log verbosity. | |
| `appMaxConcurrency` | N | The concurrency level of the application; default is unlimited | |
| `placementHostAddress` | N | | |
| `appSSL` | N | Enable https when Dapr invokes the application | |
| `daprHTTPMaxRequestSize` | N | Max size of the request body in MB. | |
| `daprHTTPReadBufferSize` | N | Max size of the HTTP read buffer in KB. This also limits the maximum size of HTTP headers. The default 4 KB | |
| `enableAppHealthCheck` | N | Enable the app health check on the application | `true`, `false` |
| `appHealthCheckPath` | N | Path to the health check file | `/healthz` |
| `appHealthProbeInterval` | N | Interval to probe for the health of the app in seconds
| |
| `appHealthProbeTimeout` | N | Timeout for app health probes in milliseconds | |
| `appHealthThreshold` | N | Number of consecutive failures for the app to be considered unhealthy | |
| `enableApiLogging` | N | Enable the logging of all API calls from application to Dapr | |
| `runtimePath` | N | Dapr runtime install path | |
| `env` | N | Map to environment variable; environment variables applied per application will overwrite environment variables shared across applications | `DEBUG`, `DAPR_HOST_ADD` |
## Next steps
Watch [this video for an overview on Multi-App Run](https://youtu.be/s1p9MNl4VGo?t=2456):
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/s1p9MNl4VGo?start=2456" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

View File

@ -29,4 +29,3 @@ Hit the ground running with our Dapr quickstarts, complete with code samples aim
| [Secrets Management]({{< ref secrets-quickstart.md >}}) | Securely fetch secrets. |
| [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. |

View File

@ -15,7 +15,8 @@ For CLI there is no explicit opt-in, just the version that this was first made a
| Feature | Description | Setting | Documentation | Version introduced |
| ---------- |-------------|---------|---------------|-----------------|
| **App Middleware** | Allow middleware components to be executed when making service-to-service calls | N/A | [App Middleware]({{< ref "middleware.md#app-middleware" >}}) | v1.9 |
| **App health checks** | Allows configuring app health checks | `AppHealthCheck` | [App health checks]({{< ref "app-health.md" >}}) | v1.9 |
| **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 |
| **App Middleware** | Allow middleware components to be executed when making service-to-service calls | N/A | [App Middleware]({{<ref "middleware.md#app-middleware" >}}) | v1.9 |
| **App health checks** | Allows configuring app health checks | `AppHealthCheck` | [App health checks]({{<ref "app-health.md" >}}) | v1.9 |
| **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 |

View File

@ -29,11 +29,13 @@ dapr run [flags] [command]
| `--app-protocol`, `-P` | | `http` | The protocol Dapr uses to talk to the application. Valid values are: `http` or `grpc` |
| `--app-ssl` | | `false` | Enable https when Dapr invokes the application |
| `--resources-path`, `-d` | | Linux/Mac: `$HOME/.dapr/components` <br/>Windows: `%USERPROFILE%\.dapr\components` | The path for components directory |
| `--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` | `DAPR_GRPC_PORT` | `50001` | The gRPC port for Dapr to listen on |
| `--dapr-http-port` | `DAPR_HTTP_PORT` | `3500` | The HTTP port for Dapr to listen on |
| `--enable-profiling` | | `false` | Enable "pprof" profiling via an HTTP endpoint |
| `--help`, `-h` | | | Print the help message |
| `--help`, `-h` | | | Print the help message |
| `--run-file`, `-f` | | Linux/MacOS: `$HOME/.dapr/dapr.yaml` | Run multiple applications at once using a Multi-App Run template file. Currently in [alpha]({{< ref "support-preview-features.md" >}}) and only availale in Linux/MacOS |
| `--image` | | | Use a custom Docker image. Format is `repository/image` for Docker Hub, or `example.com/repository/image` for a custom registry. |
| `--log-level` | | `info` | The log verbosity. Valid values are: `debug`, `info`, `warn`, `error`, `fatal`, or `panic` |
| `--enable-api-logging` | | `false` | Enable the logging of all API calls from application to Dapr |

View File

@ -21,10 +21,11 @@ dapr stop [flags]
### Flags
| Name | Environment Variable | Default | Description |
| ---------------- | -------------------- | ------- | -------------------------------- |
| `--app-id`, `-a` | `APP_ID` | | The application id to be stopped |
| `--help`, `-h` | | | Print this help message |
| Name | Environment Variable | Default | Description |
| -------------------- | -------------------- | ------- | -------------------------------- |
| `--app-id`, `-a` | `APP_ID` | | The application id to be stopped |
| `--help`, `-h` | | | Print this help message |
| `--run-file`, `-f` | | | Stop running multiple applications at once using a Multi-App Run template file. Currently in [alpha]({{< ref "support-preview-features.md" >}}) and only availale in Linux/MacOS |
### Examples

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB