Skip to content

Commit 4d9c5fa

Browse files
hhunter-mshhunter-ms
authored
Merge branch 'v1.12' into placement_tables_pt2
2 parents d2fc066 + 70e3a5e commit 4d9c5fa

File tree

5 files changed

+271
-20
lines changed

5 files changed

+271
-20
lines changed

‎daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-overview.md‎

Lines changed: 90 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,24 @@ description: Run multiple applications with one CLI command
77
---
88

99
{{% alert title="Note" color="primary" %}}
10-
Multi-App Run is currently a preview feature only supported in Linux/MacOS.
10+
Multi-App Run for **Kubernetes** is currently a preview feature.
1111
{{% /alert %}}
1212

13-
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.
13+
Let's say you want to run several applications locally to test them together, similar to a production scenario. Multi-App Run allows you to start and stop a set of applications simultaneously, either:
14+
- Locally/self-hosted with processes, or
15+
- By building container images and deploying to a Kubernetes cluster
16+
- You can use a local Kubernetes cluster (KiND) or one deploy to a Cloud (AKS, EKS, and GKE).
1417

15-
Instead, you simply want to run them as local executables in self-hosted mode. However, self-hosted mode requires you to:
18+
The Multi-App Run template file describes how to start multiple applications as if you had run many separate CLI `run` commands. By default, this template file is called `dapr.yaml`.
1619

17-
- Run multiple `dapr run` commands
18-
- Keep track of all ports opened (you cannot have duplicate ports for different applications).
19-
- Remember the resources folders and configuration files that each application refers to.
20-
- 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.)
20+
{{< tabs Self-hosted Kubernetes>}}
2121

22-
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`.
22+
{{% codetab %}}
23+
<!--selfhosted-->
2324

2425
## Multi-App Run template file
2526

26-
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.
27+
When you execute `dapr run -f .`, it starts the multi-app template file (named `dapr.yaml`) present in the current directory to run all the applications.
2728

2829
You can name template file with preferred name other than the default. For example `dapr run -f ./<your-preferred-file-name>.yaml`.
2930

@@ -71,9 +72,9 @@ The run template provides two log destination fields for each application and it
7172

7273
1. `appLogDestination` : This field configures the log destination for the application. The possible values are `console`, `file` and `fileAndConsole`. The default value is `fileAndConsole` where application logs are written to both console and to a file by default.
7374

74-
2. `daprdLogDestination` : This field configures the log destination for the `daprd` process. The possible values are `console`, `file` and `fileAndConsole`. The default value is `file` where the `daprd` logs are written to a file by default.
75+
1. `daprdLogDestination` : This field configures the log destination for the `daprd` process. The possible values are `console`, `file` and `fileAndConsole`. The default value is `file` where the `daprd` logs are written to a file by default.
7576

76-
#### Log file format
77+
### Log file format
7778

7879
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:
7980

@@ -82,14 +83,90 @@ Logs for application and `daprd` are captured in separate files. These log files
8283

8384
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).
8485

85-
8686
## Watch the demo
8787

8888
Watch [this video for an overview on Multi-App Run](https://youtu.be/s1p9MNl4VGo?t=2456):
8989

9090
<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>
9191

92+
{{% /codetab %}}
93+
94+
{{% codetab %}}
95+
<!--kubernetes-->
96+
97+
## Multi-App Run template file
98+
99+
When you execute `dapr run -k -f .` or `dapr run -k -f dapr.yaml`, the applications defined in the `dapr.yaml` Multi-App Run template file starts in Kubernetes default namespace.
100+
101+
> **Note:** Currently, the Multi-App Run template can only start applications in the default Kubernetes namespace.
102+
103+
The necessary default service and deployment definitions for Kubernetes are generated within the `.dapr/deploy` folder for each app in the `dapr.yaml` template.
104+
105+
If the `createService` field is set to `true` in the `dapr.yaml` template for an app, then the `service.yaml` file is generated in the `.dapr/deploy` folder of the app.
106+
107+
Otherwise, only the `deployment.yaml` file is generated for each app that has the `containerImage` field set.
108+
109+
The files `service.yaml` and `deployment.yaml` are used to deploy the applications in `default` namespace in Kubernetes. This feature is specifically targeted only for running multiple apps in a dev/test environment in Kubernetes.
110+
111+
You can name the template file with any preferred name other than the default. For example:
112+
113+
```bash
114+
dapr run -k -f ./<your-preferred-file-name>.yaml
115+
```
116+
117+
The following example includes some of the template properties you can customize for your applications. In the example, you can simultaneously launch 2 applications with app IDs of `nodeapp` and `pythonapp`.
118+
119+
```yaml
120+
version: 1
121+
common:
122+
apps:
123+
- appID: nodeapp
124+
appDirPath: ./nodeapp/
125+
appPort: 3000
126+
containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest
127+
createService: true
128+
env:
129+
APP_PORT: 3000
130+
- appID: pythonapp
131+
appDirPath: ./pythonapp/
132+
containerImage: ghcr.io/dapr/samples/hello-k8s-python:latest
133+
```
134+
135+
> **Note:**
136+
> - If the `containerImage` field is not specified, `dapr run -k -f` produces an error.
137+
> - The `createService` field defines a basic service in Kubernetes (ClusterIP or LoadBalancer) that targets the `--app-port` specified in the template. If `createService` isn't specified, the application is not accessible from outside the cluster.
138+
139+
For a more in-depth example and explanation of the template properties, see [Multi-app template]({{< ref multi-app-template.md >}}).
140+
141+
## Logs
142+
143+
The run template provides two log destination fields for each application and its associated daprd process:
144+
145+
1. `appLogDestination` : This field configures the log destination for the application. The possible values are `console`, `file` and `fileAndConsole`. The default value is `fileAndConsole` where application logs are written to both console and to a file by default.
146+
147+
2. `daprdLogDestination` : This field configures the log destination for the `daprd` process. The possible values are `console`, `file` and `fileAndConsole`. The default value is `file` where the `daprd` logs are written to a file by default.
148+
149+
### Log file format
150+
151+
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:
152+
153+
- `<appID>_app_<timestamp>.log` (file name format for `app` log)
154+
- `<appID>_daprd_<timestamp>.log` (file name format for `daprd` log)
155+
156+
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).
157+
158+
## Watch the demo
159+
160+
Watch [this video for an overview on Multi-App Run in Kubernetes](https://youtu.be/nWatANwaAik?si=O8XR-TUaiY0gclgO&t=1024):
161+
162+
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/nWatANwaAik?si=O8XR-TUaiY0gclgO&amp;start=1024" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
163+
164+
{{% /codetab %}}
165+
166+
{{< /tabs >}}
167+
92168
## Next steps
93169

94170
- [Learn the Multi-App Run template file structure and its properties]({{< ref multi-app-template.md >}})
95-
- [Try out the Multi-App Run template with the Service Invocation quickstart]({{< ref serviceinvocation-quickstart.md >}})
171+
- [Try out the self-hosted Multi-App Run template with the Service Invocation quickstart]({{< ref serviceinvocation-quickstart.md >}})
172+
- [Try out the Kubernetes Multi-App Run template with the `hello-kubernetes` tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-kubernetes)

‎daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md‎

Lines changed: 169 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: Unpack the Multi-App Run template file and its properties
77
---
88

99
{{% alert title="Note" color="primary" %}}
10-
Multi-App Run is currently a preview feature only supported in Linux/MacOS.
10+
Multi-App Run for **Kubernetes** is currently a preview feature.
1111
{{% /alert %}}
1212

1313
The Multi-App Run template file is a YAML file that you can use to run multiple applications at once. In this guide, you'll learn how to:
@@ -26,20 +26,53 @@ When you provide a directory path, the CLI will try to locate the Multi-App Run
2626

2727
Execute the following CLI command to read the Multi-App Run template file, named `dapr.yaml` by default:
2828

29+
{{< tabs Self-hosted Kubernetes>}}
30+
31+
{{% codetab %}}
32+
<!--selfhosted-->
33+
2934
```cmd
3035
# the template file needs to be called `dapr.yaml` by default if a directory path is given
3136
3237
dapr run -f <dir_path>
3338
```
39+
{{% /codetab %}}
40+
41+
{{% codetab %}}
42+
<!--kubernetes-->
43+
44+
```cmd
45+
dapr run -f -k <dir_path>
46+
```
47+
{{% /codetab %}}
48+
49+
{{< /tabs >}}
3450

3551
### Execute by providing a file path
3652

3753
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:
3854

55+
{{< tabs Self-hosted Kubernetes>}}
56+
57+
{{% codetab %}}
58+
<!--selfhosted-->
59+
3960
```cmd
4061
dapr run -f ./path/to/<your-preferred-file-name>.yaml
4162
```
4263

64+
{{% /codetab %}}
65+
66+
{{% codetab %}}
67+
<!--kubernetes-->
68+
69+
```cmd
70+
dapr run -f -k ./path/to/<your-preferred-file-name>.yaml
71+
```
72+
{{% /codetab %}}
73+
74+
{{< /tabs >}}
75+
4376
## View the started applications
4477

4578
Once the multi-app template is running, you can view the started applications with the following command:
@@ -52,6 +85,11 @@ dapr list
5285

5386
Stop the multi-app run template anytime with either of the following commands:
5487

88+
{{< tabs Self-hosted Kubernetes>}}
89+
90+
{{% codetab %}}
91+
<!--selfhosted-->
92+
5593
```cmd
5694
# the template file needs to be called `dapr.yaml` by default if a directory path is given
5795
@@ -63,10 +101,36 @@ or:
63101
dapr stop -f ./path/to/<your-preferred-file-name>.yaml
64102
```
65103

104+
{{% /codetab %}}
105+
106+
{{% codetab %}}
107+
<!--kubernetes-->
108+
109+
```cmd
110+
# the template file needs to be called `dapr.yaml` by default if a directory path is given
111+
112+
dapr stop -f -k
113+
```
114+
or:
115+
116+
```cmd
117+
dapr stop -f -k ./path/to/<your-preferred-file-name>.yaml
118+
```
119+
120+
{{% /codetab %}}
121+
122+
{{< /tabs >}}
123+
124+
66125
## Template file structure
67126

68127
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.
69128

129+
{{< tabs Self-hosted Kubernetes>}}
130+
131+
{{% codetab %}}
132+
<!--selfhosted-->
133+
70134
```yaml
71135
version: 1
72136
common: # optional section for variables shared across apps
@@ -96,19 +160,61 @@ apps:
96160
command: ["./backend"]
97161
```
98162
99-
{{% alert title="Important" color="warning" %}}
100163
The following rules apply for all the paths present in the template file:
101164
- If the path is absolute, it is used as is.
102-
- All relative paths under comman section should be provided relative to the template file path.
165+
- All relative paths under command section should be provided relative to the template file path.
103166
- `appDirPath` under apps section should be provided relative to the template file path.
104-
- All relative paths under app section should be provided relative to the appDirPath.
167+
- All relative paths under app section should be provided relative to the `appDirPath`.
105168

106-
{{% /alert %}}
169+
{{% /codetab %}}
170+
171+
{{% codetab %}}
172+
<!--kubernetes-->
173+
174+
```yaml
175+
version: 1
176+
common: # optional section for variables shared across apps
177+
env: # any environment variable shared across apps
178+
DEBUG: true
179+
apps:
180+
- appID: webapp # optional
181+
appDirPath: .dapr/webapp/ # REQUIRED
182+
appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention.
183+
appProtocol: http
184+
appPort: 8080
185+
appHealthCheckPath: "/healthz"
186+
appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole.
187+
daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file.
188+
containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest # (optional) URI of the container image to be used when deploying to Kubernetes dev/test environment.
189+
createService: true # (optional) Create a Kubernetes service for the application when deploying to dev/test environment.
190+
- appID: backend # optional
191+
appDirPath: .dapr/backend/ # REQUIRED
192+
appProtocol: grpc
193+
appPort: 3000
194+
unixDomainSocket: "/tmp/test-socket"
195+
env:
196+
- DEBUG: false
197+
```
198+
199+
The following rules apply for all the paths present in the template file:
200+
- If the path is absolute, it is used as is.
201+
- `appDirPath` under apps section should be provided relative to the template file path.
202+
- All relative paths under app section should be provided relative to the `appDirPath`.
203+
204+
{{% /codetab %}}
205+
206+
{{< /tabs >}}
107207

108208
## Template properties
109209

210+
{{< tabs Self-hosted Kubernetes>}}
211+
212+
{{% codetab %}}
213+
<!--selfhosted-->
214+
110215
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" >}}).
111216

217+
{{< table "table table-white table-striped table-bordered" >}}
112218

113219
| Properties | Required | Details | Example |
114220
|--------------------------|:--------:|--------|---------|
@@ -146,8 +252,66 @@ The properties for the Multi-App Run template align with the `dapr run` CLI flag
146252
| `appLogDestination` | N | Log destination for outputting app logs; Its value can be file, console or fileAndConsole. Default is fileAndConsole | `file`, `console`, `fileAndConsole` |
147253
| `daprdLogDestination` | N | Log destination for outputting daprd logs; Its value can be file, console or fileAndConsole. Default is file | `file`, `console`, `fileAndConsole` |
148254

255+
{{< /table >}}
256+
149257
## Next steps
150258

151259
Watch [this video for an overview on Multi-App Run](https://youtu.be/s1p9MNl4VGo?t=2456):
152260

153261
<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>
262+
{{% /codetab %}}
263+
264+
{{% codetab %}}
265+
<!--kubernetes-->
266+
267+
The properties for the Multi-App Run template align with the `dapr run -k` CLI flags, [listed in the CLI reference documentation]({{< ref "dapr-run.md#flags" >}}).
268+
269+
{{< table "table table-white table-striped table-bordered" >}}
270+
271+
| Properties | Required | Details | Example |
272+
|--------------------------|:--------:|--------|---------|
273+
| `appDirPath` | Y | Path to the your application code | `./webapp/`, `./backend/` |
274+
| `appID` | N | Application's app ID. If not provided, will be derived from `appDirPath` | `webapp`, `backend` |
275+
| `appChannelAddress` | N | The network address the application listens on. Can be left to the default value by convention. | `127.0.0.1` | `localhost` |
276+
| `appProtocol` | N | The protocol Dapr uses to talk to the application. | `http`, `grpc` |
277+
| `appPort` | N | The port your application is listening on | `8080`, `3000` |
278+
| `daprHTTPPort` | N | Dapr HTTP port | |
279+
| `daprGRPCPort` | N | Dapr GRPC port | |
280+
| `daprInternalGRPCPort` | N | gRPC port for the Dapr Internal API to listen on; used when parsing the value from a local DNS component | |
281+
| `metricsPort` | N | The port that Dapr sends its metrics information to | |
282+
| `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` |
283+
| `profilePort` | N | The port for the profile server to listen on | |
284+
| `enableProfiling` | N | Enable profiling via an HTTP endpoint | |
285+
| `apiListenAddresses` | N | Dapr API listen addresses | |
286+
| `logLevel` | N | The log verbosity. | |
287+
| `appMaxConcurrency` | N | The concurrency level of the application; default is unlimited | |
288+
| `placementHostAddress` | N | | |
289+
| `appSSL` | N | Enable https when Dapr invokes the application | |
290+
| `daprHTTPMaxRequestSize` | N | Max size of the request body in MB. | |
291+
| `daprHTTPReadBufferSize` | N | Max size of the HTTP read buffer in KB. This also limits the maximum size of HTTP headers. The default 4 KB | |
292+
| `enableAppHealthCheck` | N | Enable the app health check on the application | `true`, `false` |
293+
| `appHealthCheckPath` | N | Path to the health check file | `/healthz` |
294+
| `appHealthProbeInterval` | N | Interval to probe for the health of the app in seconds
295+
| |
296+
| `appHealthProbeTimeout` | N | Timeout for app health probes in milliseconds | |
297+
| `appHealthThreshold` | N | Number of consecutive failures for the app to be considered unhealthy | |
298+
| `enableApiLogging` | N | Enable the logging of all API calls from application to Dapr | |
299+
| `env` | N | Map to environment variable; environment variables applied per application will overwrite environment variables shared across applications | `DEBUG`, `DAPR_HOST_ADD` |
300+
| `appLogDestination` | N | Log destination for outputting app logs; Its value can be file, console or fileAndConsole. Default is fileAndConsole | `file`, `console`, `fileAndConsole` |
301+
| `daprdLogDestination` | N | Log destination for outputting daprd logs; Its value can be file, console or fileAndConsole. Default is file | `file`, `console`, `fileAndConsole` |
302+
| `containerImage`| N | URI of the container image to be used when deploying to Kubernetes dev/test environment. | `ghcr.io/dapr/samples/hello-k8s-python:latest`
303+
| `createService`| N | Create a Kubernetes service for the application when deploying to dev/test environment. | `true`, `false` |
304+
305+
{{< /table >}}
306+
307+
## Next steps
308+
309+
Watch [this video for an overview on Multi-App Run in Kubernetes](https://youtu.be/nWatANwaAik?si=O8XR-TUaiY0gclgO&t=1024):
310+
311+
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/nWatANwaAik?si=O8XR-TUaiY0gclgO&amp;start=1024" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
312+
313+
{{% /codetab %}}
314+
315+
{{< /tabs >}}
316+
317+

0 commit comments

Comments
 (0)