Dapr Integration Troubleshooting Lab¶

Diagnose and fix Dapr sidecar port misconfiguration issues in Azure Container Apps.

Lab Metadata¶

1) Background¶

This lab starts with a working Dapr configuration: Dapr is enabled, appId is set, and appPort matches the application listening port. The trigger changes Dapr appPort from 8000 to 8081, so the sidecar keeps running but can no longer forward service invocation traffic to the application process.

The key troubleshooting lesson is that ingress targetPort and Dapr appPort are separate settings. An app can still be reachable through ingress while Dapr-to-app communication is broken.

Architecture¶

flowchart LR
    A[External Request] --> B[Ingress :8000]
    B --> C[App Container :8000]
    D[Dapr Sidecar :3500] --> E[App Container :appPort]
    F[Other Dapr Apps] --> D
    E -. correct .-> C
    D -. wrong appPort 8081 .-> G[Connection failure]

Dapr App Port Configuration¶

2) Hypothesis¶

IF Dapr is enabled but appPort is changed from the app's real listening port 8000 to 8081, THEN Dapr sidecar health and service invocation checks will fail even though the app configuration still shows Dapr enabled.

3) Runbook¶

Deploy baseline infrastructure¶

Prerequisites:

• Azure CLI with the Container Apps extension
• Basic understanding of Dapr concepts such as sidecars, appId, and appPort

az extension add --name containerapp --upgrade
az login

export RG="rg-aca-lab-dapr"
export LOCATION="koreacentral"

az group create --name "$RG" --location "$LOCATION"

az deployment group create \
    --name "lab-dapr" \
    --resource-group "$RG" \
    --template-file "./labs/dapr-integration/infra/main.bicep" \
    --parameters baseName="labdapr"

Expected output:

• Resource group creation succeeds.
• Deployment completes successfully with Dapr enabled on the app.

Capture deployment outputs¶

export APP_NAME="$(az deployment group show \
    --resource-group "$RG" \
    --name "lab-dapr" \
    --query "properties.outputs.containerAppName.value" \
    --output tsv)"

export ENVIRONMENT_NAME="$(az deployment group show \
    --resource-group "$RG" \
    --name "lab-dapr" \
    --query "properties.outputs.containerAppsEnvironmentName.value" \
    --output tsv)"

Expected output:

• Commands return no console output.
• Variables resolve to the app and environment names.

Verify baseline Dapr configuration¶

az containerapp show \
    --name "$APP_NAME" \
    --resource-group "$RG" \
    --query "properties.configuration.dapr" \
    --output json

Expected output:

{
  "appId": "dapr-labdapr-xxxxxx",
  "appPort": 8000,
  "appProtocol": "http",
  "enabled": true
}

Trigger the failure¶

./labs/dapr-integration/trigger.sh

The trigger uses:

az containerapp update \
    --name "$APP_NAME" \
    --resource-group "$RG" \
    --dapr-app-port 8081

Expected output:

• The script prints Changed Dapr appPort to 8081 to break service invocation.
• A new revision applies the broken Dapr port value.

Observe the broken state¶

az containerapp show \
    --name "$APP_NAME" \
    --resource-group "$RG" \
    --query "properties.configuration.dapr" \
    --output json

az containerapp logs show \
    --name "$APP_NAME" \
    --resource-group "$RG" \
    --type system \
    --tail 50

Expected output:

{
  "appId": "dapr-labdapr-xxxxxx",
  "appPort": 8081,
  "appProtocol": "http",
  "enabled": true
}

Look for errors such as connection refused, port unreachable, or health probe failures on port 8081.

Verify failure and fix the configuration¶

./labs/dapr-integration/verify.sh

Before the fix, the verification script should fail with output like:

FAIL: Dapr appPort is '8081'; expected 8000

Restore the correct port:

az containerapp update \
    --name "$APP_NAME" \
    --resource-group "$RG" \
    --dapr-app-port 8000

Useful debugging commands:

az containerapp show --name "$APP_NAME" --resource-group "$RG" --query "properties.configuration.dapr"
az containerapp show --name "$APP_NAME" --resource-group "$RG" --query "properties.configuration.ingress.targetPort"
az containerapp logs show --name "$APP_NAME" --resource-group "$RG" --type system --tail 100
az containerapp env dapr-component list --name "$ENVIRONMENT_NAME" --resource-group "$RG" --output table

Expected output:

• appPort returns to 8000.
• Sidecar-to-app communication succeeds again.

Verify recovery¶

./labs/dapr-integration/verify.sh

Expected output:

• az containerapp exec against http://127.0.0.1:3500/v1.0/healthz succeeds.
• The script prints PASS: Dapr is enabled, appPort is correct, and the health endpoint responded successfully.

4) Experiment Log¶

Expected Evidence¶

Before trigger¶

During incident¶

After fix¶

Clean Up¶

az group delete --name "$RG" --yes --no-wait

Related Playbook¶

• Dapr Sidecar or Component Failure

See Also¶

• Probe Failure and Slow Start
• Traffic Routing and Canary Failure Lab

Sources¶

• Dapr integration with Azure Container Apps
• Dapr components in Azure Container Apps