How to: Use the Multi-App Run template file

Unpack the Multi-App Run template file and its properties

Note

Multi-App Run for Kubernetes is currently a preview feature.

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:

  1. # the template file needs to be called `dapr.yaml` by default if a directory path is given
  2. dapr run -f <dir_path>
  1. dapr run -f -k <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:

  1. dapr run -f ./path/to/<your-preferred-file-name>.yaml
  1. dapr run -f -k ./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:

  1. dapr list

Stop the multi-app template

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

  1. # the template file needs to be called `dapr.yaml` by default if a directory path is given
  2. dapr stop -f

or:

  1. dapr stop -f ./path/to/<your-preferred-file-name>.yaml
  1. # the template file needs to be called `dapr.yaml` by default if a directory path is given
  2. dapr stop -f -k

or:

  1. dapr stop -f -k ./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.

  1. version: 1
  2. common: # optional section for variables shared across apps
  3. resourcesPath: ./app/components # any dapr resources to be shared across apps
  4. env: # any environment variable shared across apps
  5. DEBUG: true
  6. apps:
  7. - appID: webapp # optional
  8. appDirPath: .dapr/webapp/ # REQUIRED
  9. resourcesPath: .dapr/resources # deprecated
  10. resourcesPaths: .dapr/resources # comma separated resources paths. (optional) can be left to default value by convention.
  11. appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention.
  12. configFilePath: .dapr/config.yaml # (optional) can be default by convention too, ignore if file is not found.
  13. appProtocol: http
  14. appPort: 8080
  15. appHealthCheckPath: "/healthz"
  16. command: ["python3", "app.py"]
  17. appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole.
  18. daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file.
  19. - appID: backend # optional
  20. appDirPath: .dapr/backend/ # REQUIRED
  21. appProtocol: grpc
  22. appPort: 3000
  23. unixDomainSocket: "/tmp/test-socket"
  24. env:
  25. DEBUG: false
  26. command: ["./backend"]

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 command 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.
  1. version: 1
  2. common: # optional section for variables shared across apps
  3. env: # any environment variable shared across apps
  4. DEBUG: true
  5. apps:
  6. - appID: webapp # optional
  7. appDirPath: .dapr/webapp/ # REQUIRED
  8. appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention.
  9. appProtocol: http
  10. appPort: 8080
  11. appHealthCheckPath: "/healthz"
  12. appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole.
  13. daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file.
  14. 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.
  15. createService: true # (optional) Create a Kubernetes service for the application when deploying to dev/test environment.
  16. - appID: backend # optional
  17. appDirPath: .dapr/backend/ # REQUIRED
  18. appProtocol: grpc
  19. appPort: 3000
  20. unixDomainSocket: "/tmp/test-socket"
  21. env:
  22. DEBUG: false

The following rules apply for all the paths present in the template file:

  • If the path is absolute, it is used as is.
  • 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.

Template properties

The properties for the Multi-App Run template align with the dapr run CLI flags, listed in the CLI reference documentation.

PropertiesRequiredDetailsExample
appDirPathYPath to the your application code./webapp/, ./backend/
appIDNApplication’s app ID. If not provided, will be derived from appDirPathwebapp, backend
resourcesPathNDeprecated. Path to your Dapr resources. Can be default value by convention./app/components, ./webapp/components
resourcesPathsNComma separated paths to your Dapr resources. Can be default value by convention./app/components, ./webapp/components
appChannelAddressNThe network address the application listens on. Can be left to the default value by convention.127.0.0.1
configFilePathNPath to your application’s configuration file./webapp/config.yaml
appProtocolNThe protocol Dapr uses to talk to the application.http, grpc
appPortNThe port your application is listening on8080, 3000
daprHTTPPortNDapr HTTP port
daprGRPCPortNDapr GRPC port
daprInternalGRPCPortNgRPC port for the Dapr Internal API to listen on; used when parsing the value from a local DNS component
metricsPortNThe port that Dapr sends its metrics information to
unixDomainSocketNPath 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
profilePortNThe port for the profile server to listen on
enableProfilingNEnable profiling via an HTTP endpoint
apiListenAddressesNDapr API listen addresses
logLevelNThe log verbosity.
appMaxConcurrencyNThe concurrency level of the application; default is unlimited
placementHostAddressN
appSSLNEnable https when Dapr invokes the application
daprHTTPMaxRequestSizeNMax size of the request body in MB.
daprHTTPReadBufferSizeNMax size of the HTTP read buffer in KB. This also limits the maximum size of HTTP headers. The default 4 KB
enableAppHealthCheckNEnable the app health check on the applicationtrue, false
appHealthCheckPathNPath to the health check file/healthz
appHealthProbeIntervalNInterval to probe for the health of the app in seconds
appHealthProbeTimeoutNTimeout for app health probes in milliseconds
appHealthThresholdNNumber of consecutive failures for the app to be considered unhealthy
enableApiLoggingNEnable the logging of all API calls from application to Dapr
runtimePathNDapr runtime install path
envNMap to environment variable; environment variables applied per application will overwrite environment variables shared across applicationsDEBUG, DAPR_HOST_ADD
appLogDestinationNLog destination for outputting app logs; Its value can be file, console or fileAndConsole. Default is fileAndConsolefile, console, fileAndConsole
daprdLogDestinationNLog destination for outputting daprd logs; Its value can be file, console or fileAndConsole. Default is filefile, console, fileAndConsole

Next steps

Watch this video for an overview on Multi-App Run:

The properties for the Multi-App Run template align with the dapr run -k CLI flags, listed in the CLI reference documentation.

PropertiesRequiredDetailsExample
appDirPathYPath to the your application code./webapp/, ./backend/
appIDNApplication’s app ID. If not provided, will be derived from appDirPathwebapp, backend
appChannelAddressNThe network address the application listens on. Can be left to the default value by convention.127.0.0.1
appProtocolNThe protocol Dapr uses to talk to the application.http, grpc
appPortNThe port your application is listening on8080, 3000
daprHTTPPortNDapr HTTP port
daprGRPCPortNDapr GRPC port
daprInternalGRPCPortNgRPC port for the Dapr Internal API to listen on; used when parsing the value from a local DNS component
metricsPortNThe port that Dapr sends its metrics information to
unixDomainSocketNPath 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
profilePortNThe port for the profile server to listen on
enableProfilingNEnable profiling via an HTTP endpoint
apiListenAddressesNDapr API listen addresses
logLevelNThe log verbosity.
appMaxConcurrencyNThe concurrency level of the application; default is unlimited
placementHostAddressN
appSSLNEnable https when Dapr invokes the application
daprHTTPMaxRequestSizeNMax size of the request body in MB.
daprHTTPReadBufferSizeNMax size of the HTTP read buffer in KB. This also limits the maximum size of HTTP headers. The default 4 KB
enableAppHealthCheckNEnable the app health check on the applicationtrue, false
appHealthCheckPathNPath to the health check file/healthz
appHealthProbeIntervalNInterval to probe for the health of the app in seconds
appHealthProbeTimeoutNTimeout for app health probes in milliseconds
appHealthThresholdNNumber of consecutive failures for the app to be considered unhealthy
enableApiLoggingNEnable the logging of all API calls from application to Dapr
envNMap to environment variable; environment variables applied per application will overwrite environment variables shared across applicationsDEBUG, DAPR_HOST_ADD
appLogDestinationNLog destination for outputting app logs; Its value can be file, console or fileAndConsole. Default is fileAndConsolefile, console, fileAndConsole
daprdLogDestinationNLog destination for outputting daprd logs; Its value can be file, console or fileAndConsole. Default is filefile, console, fileAndConsole
containerImageNURI of the container image to be used when deploying to Kubernetes dev/test environment.ghcr.io/dapr/samples/hello-k8s-python:latest
createServiceNCreate a Kubernetes service for the application when deploying to dev/test environment.true, false

Next steps

Watch this video for an overview on Multi-App Run in Kubernetes:

Last modified October 12, 2023: Update config.toml (#3826) (0ffc2e7)