Skip to content

Commit 9371fb2

Browse files
denreadenrea
authored
Merge pull request #191316 from hhunter-ms/hh-1921017-daproverview
[Container Apps] Dapr w Container Apps overview doc
2 parents 8eb202c + ace5ec7 commit 9371fb2

File tree

5 files changed

+229
-0
lines changed

5 files changed

+229
-0
lines changed

‎articles/container-apps/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@
5858
href: health-probes.md
5959
- name: Authentication
6060
href: authentication.md
61+
- name: Dapr integration
62+
href: dapr-overview.md
6163
- name: How-to guides
6264
items:
6365
- name: Scale an app

‎articles/container-apps/dapr-overview.md

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
---
2+
title: Dapr integration with Azure Container Apps
3+
description: Learn more about using Dapr on your Azure Container App service to develop applications.
4+
ms.author: hannahhunter
5+
author: hhunter-ms
6+
ms.service: container-apps
7+
ms.topic: conceptual
8+
ms.date: 05/05/2022
9+
---
10+
11+
# Dapr integration with Azure Container Apps
12+
13+
The Distributed Application Runtime ([Dapr][dapr-concepts]) is a set of incrementally adoptable APIs that simplify the authoring of distributed, microservice-based applications. For example, Dapr provides capabilities for enabling application intercommunication, whether through messaging via pub/sub or reliable and secure service-to-service calls. Once enabled in Container Apps, Dapr exposes its HTTP and gRPC APIs via a sidecar: a process that runs in tandem with each of your Container Apps.
14+
15+
Dapr APIs, also referred to as building blocks, are built on best practice industry standards, that:
16+
17+
- Seamlessly fit with your preferred language or framework
18+
- Are incrementally adoptable; you can use one, several, or all of the building blocks depending on your needs
19+
20+
## Dapr building blocks
21+
22+
:::image type="content" source="media/dapr-overview/building_blocks.png" alt-text="Diagram that shows Dapr building blocks.":::
23+
24+
| Building block | Description |
25+
| -------------- | ----------- |
26+
| [**Service-to-service invocation**][dapr-serviceinvo] | Discover services and perform reliable, direct service-to-service calls with automatic mTLS authentication and encryption. |
27+
| [**State management**][dapr-statemgmt] | Provides state management capabilities for transactions and CRUD operations. |
28+
| [**Pub/sub**][dapr-pubsub] | Allows publisher and subscriber container apps to intercommunicate via an intermediary message broker. |
29+
| [**Bindings**][dapr-bindings] | Trigger your application with incoming or outgoing events, without SDK or library dependencies. |
30+
| [**Actors**][dapr-actors] | Dapr actors apply the scalability and reliability that the underlying platform provides. |
31+
| [**Observability**](./observability.md) | Send tracing information to an Application Insights backend. |
32+
33+
## Dapr settings
34+
35+
The following Pub/sub example demonstrates how Dapr works alongside your container app:
36+
37+
:::image type="content" source="media/dapr-overview/dapr-in-aca.png" alt-text="Diagram demonstrating Dapr pub/sub and how it works with Container Apps.":::
38+
39+
| Label | Dapr settings | Description |
40+
| ----- | ------------- | ----------- |
41+
| 1 | Container Apps with Dapr enabled | Dapr is enabled at the container app level by configuring Dapr settings. Dapr settings exist at the app-level, meaning they apply across revisions. |
42+
| 2 | Dapr sidecar | Fully managed Dapr APIs are exposed to your container app via the Dapr sidecar. These APIs are available through HTTP and gRPC protocols. By default, the sidecar runs on port 3500 in Container Apps. |
43+
| 3 | Dapr component | Dapr components can be shared by multiple container apps. Using scopes, the Dapr sidecar will determine which components to load for a given container app at runtime. |
44+
45+
### Enable Dapr
46+
47+
You can define the Dapr configuration for a container app through the Azure CLI or using Infrastructure as Code templates like bicep or ARM. With the following settings, you enable Dapr on your app:
48+
49+
| Field | Description |
50+
| ----- | ----------- |
51+
| `--enable-dapr` / `enabled` | Enables Dapr on the container app. |
52+
| `--dapr-app-port` / `appPort` | Identifies which port your application is listening. |
53+
| `--dapr-app-protocol` / `appProtocol` | Tells Dapr which protocol your application is using. Valid options are `http` or `grpc`. Default is `http`. |
54+
| `--dapr-app-id` / `appId` | The unique ID of the application. Used for service discovery, state encapsulation, and the pub/sub consumer ID. |
55+
56+
Since Dapr settings are considered application-scope changes, new revisions aren't created when you change Dapr settings. However, when changing a Dapr setting, the container app instance and revisions are automatically restarted.
57+
58+
### Configure Dapr components
59+
60+
Once Dapr is enabled on your container app, you're able to plug in and use the [Dapr APIs](#dapr-building-blocks) as needed. You can also create **Dapr components**, which are specific implementations of a given building block. Dapr components are environment-level resources, meaning they can be shared across Dapr-enabled container apps. Components are pluggable modules that:
61+
62+
- Allow you to use the individual Dapr building block APIs.
63+
- Can be scoped to specific container apps.
64+
- Can be easily modified to point to any one of the component implementations.
65+
- Can reference secure configuration values using Container Apps secrets.
66+
67+
Based on your needs, you can "plug in" certain Dapr component types like state stores, pub/sub brokers, and more. In the examples below, you will find the various schemas available for defining a Dapr component in Azure Container Apps. The Container Apps manifests differ sightly from the Dapr OSS manifests in order to simplify the component creation experience.
68+
69+
> [!NOTE]
70+
> By default, all Dapr-enabled container apps within the same environment will load the full set of deployed components. By adding scopes to a component, you tell the Dapr sidecars for each respective container app which components to load at runtime. Using scopes is recommended for production workloads.
71+
72+
# [YAML](#tab/yaml)
73+
74+
When defining a Dapr component via YAML, you will pass your component manifest into the Azure CLI. For example, deploy a `pubsub.yaml` component using the following command:
75+
76+
```azurecli
77+
az containerapp env dapr-component set --name ENVIRONMENT_NAME --resource-group RESOURCE_GROUP_NAME --dapr-component-name pubsub--yaml "./pubsub.yaml"
78+
```
79+
80+
The `pubsub.yaml` spec will be scoped to the dapr-enabled container apps with app ids `publisher-app` and `subscriber-app`.
81+
82+
```yaml
83+
# pubsub.yaml for Azure Service Bus component
84+
- name: dapr-pubsub
85+
type: pubsub.azure.servicebus
86+
version: v1
87+
metadata:
88+
- name: connectionString
89+
secretRef: sb-root-connectionstring
90+
secrets:
91+
- name: sb-root-connectionstring
92+
value: "value"
93+
# Application scopes
94+
scopes:
95+
- publisher-app
96+
- subscriber-app
97+
```
98+
99+
# [Bicep](#tab/bicep)
100+
101+
This resource defines a Dapr component called `dapr-pubsub` via Bicep. The Dapr component is defined as a child resource of your Container Apps environment. The `dapr-pubsub` component is scoped to the Dapr-enabled container apps with app ids `publisher-app` and `subscriber-app`:
102+
103+
```bicep
104+
resource daprComponent 'daprComponents@2022-01-01-preview' = {
105+
name: 'dapr-pubsub'
106+
properties: {
107+
componentType: 'pubsub.azure.servicebus'
108+
version: 'v1'
109+
secrets: [
110+
{
111+
name: 'sb-root-connectionstring'
112+
value: 'value'
113+
}
114+
]
115+
metadata: [
116+
{
117+
name: 'connectionString'
118+
secretRef: 'sb-root-connectionstring'
119+
}
120+
]
121+
// Application scopes
122+
scopes: [
123+
'publisher-app'
124+
'subscriber-app'
125+
]
126+
}
127+
}
128+
```
129+
130+
# [ARM](#tab/arm)
131+
132+
This resource defines a Dapr component called `dapr-pubsub` via ARM. The Dapr component is defined as a child resource of your Container Apps environment. The `dapr-pubsub` component will be scoped to the Dapr-enabled container apps with app ids `publisher-app` and `subscriber-app`:
133+
134+
```json
135+
{
136+
"resources": [
137+
{
138+
"type": "daprComponents",
139+
"name": "dapr-pubsub",
140+
"properties": {
141+
"componentType": "pubsub.azure.servicebus",
142+
"version": "v1",
143+
"secrets": [
144+
{
145+
"name": "sb-root-connectionstring",
146+
"value": "value"
147+
}
148+
],
149+
"metadata": [
150+
{
151+
"name": "connectionString",
152+
"secretRef": "sb-root-connectionstring"
153+
}
154+
],
155+
// Application scopes
156+
"scopes": ["publisher-app", "subscriber-app"]
157+
158+
}
159+
}
160+
]
161+
}
162+
```
163+
164+
---
165+
166+
For comparison, a Dapr OSS `pubsub.yaml` file would include:
167+
168+
```yml
169+
apiVersion: dapr.io/v1alpha1
170+
kind: Component
171+
metadata:
172+
name: dapr-pubsub
173+
spec:
174+
type: pubsub.azure.servicebus
175+
version: v1
176+
metadata:
177+
- name: connectionString
178+
secretKeyRef:
179+
name: sb-root-connectionstring
180+
key: "value"
181+
# Application scopes
182+
scopes:
183+
- publisher-app
184+
- subscriber-app
185+
```
186+
187+
## Current supported Dapr version
188+
189+
Azure Container Apps supports Dapr version 1.4.2.
190+
191+
Version upgrades are handled transparently by Azure Container Apps. You can find the current version via the Azure portal and the CLI. See [known limitations](#limitations) around versioning.
192+
193+
## Limitations
194+
195+
### Unsupported Dapr capabilities
196+
197+
- **Dapr Secrets Management API**: Use [Container Apps secret mechanism][aca-secrets] as an alternative.
198+
- **Custom configuration for Dapr Observability**: Instrument your environment with Application Insights to visualize distributed tracing.
199+
- **Dapr Configuration spec**: Any capabilities that require use of the Dapr configuration spec, which includes preview features.
200+
- **Advanced Dapr sidecar configurations**: Container Apps allows you to specify sidecar settings including `app-protocol`, `app-port`, and `app-id`. For a list of unsupported configuration options, see [the Dapr documentation](https://docs.dapr.io/reference/arguments-annotations-overview/).
201+
- **Dapr APIs in Preview state**
202+
203+
### Known limitations
204+
205+
- **Declarative pub/sub subscriptions**
206+
- **Actor reminders**: Require a minReplicas of 1+ to ensure reminders will always be active and fire correctly.
207+
208+
## Next Steps
209+
210+
Now that you've learned about Dapr and some of the challenges it solves, try [Deploying a Dapr application to Azure Container Apps using the Azure CLI][dapr-quickstart] or [Azure Resource Manager][dapr-arm-quickstart].
211+
212+
<!-- Links Internal -->
213+
[dapr-quickstart]: ./microservices-dapr.md
214+
[dapr-arm-quickstart]: ./microservices-dapr-azure-resource-manager.md
215+
[aca-secrets]: ./manage-secrets.md
216+
217+
<!-- Links External -->
218+
[dapr-concepts]: https://docs.dapr.io/concepts/overview/
219+
[dapr-pubsub]: https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-overview
220+
[dapr-statemgmt]: https://docs.dapr.io/developing-applications/building-blocks/state-management/state-management-overview/
221+
[dapr-serviceinvo]: https://docs.dapr.io/developing-applications/building-blocks/service-invocation/service-invocation-overview/
222+
[dapr-bindings]: https://docs.dapr.io/developing-applications/building-blocks/bindings/bindings-overview/
223+
[dapr-actors]: https://docs.dapr.io/developing-applications/building-blocks/actors/actors-overview/

‎articles/container-apps/index.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,10 @@ landingContent:
6161
url: connect-apps.md
6262
- text: Use a custom VNET
6363
url: vnet-custom.md
64+
- linkListType: concept
65+
links:
66+
- text: Dapr integration
67+
url: dapr-overview.md
6468
- title: Apps and microservices
6569
linkLists:
6670
- linkListType: tutorial

‎articles/container-apps/media/dapr-overview/building_blocks.png

97.4 KB
Loading

‎articles/container-apps/media/dapr-overview/dapr-in-aca.png

35.9 KB
Loading

0 commit comments

Comments
 (0)