Grafana Azure Deployment Skill

Deploy Grafana OSS to Azure Container Apps using Bicep and Azure Developer CLI (azd).

Reproducibility Verified: This deployment has been tested multiple times from scratch. Deploy time: ~2 minutes.

Overview

Grafana is an open-source observability platform for metrics, logs, and traces visualization. This skill deploys Grafana OSS (not Azure Managed Grafana) to Azure Container Apps.

azure.yaml has no services: block. The Container App's public image is set in Bicep, so azd has nothing to package. A service with image: makes azd pull the image through local Docker, which fails on Windows hosts running Windows containers and makes Docker a requirement. See the container-apps-deployment skill.

Prerequisites and Portability

Require Azure CLI, Azure Developer CLI 1.28.0 or later, and Node.js LTS or later for portable verification. Don't require OpenSSL, Bash command substitution, or host-specific shell scripts. See ../../../docs/tool-installation.md.

Critical: Infrastructure Generation

This skill provides Grafana-specific configuration only. Infrastructure (Bicep, azure.yaml) should be generated fresh each time by the official azure-prepare → azure-validate → azure-deploy pipeline. Do NOT rely on pre-existing infra code.

Validate the pinned AVM interface

Check parameters, outputs, and defaults against the exact version in each br/public:avm/...:<version> reference before generating module calls. The upstream repository's main branch may describe a newer interface than the published version. For example, the Grafana run hit BCP037 because workspace module 0.9.1 didn't accept the features parameter shown in newer source. Use the pinned version's supported configuration rather than assuming the latest source applies. Compile Bicep and run azd provision --preview --no-prompt before deployment.

Defer Log Analytics lookups until its module completes

When a monitoring module creates Log Analytics, put the Container Apps environment in a separate module with an explicit dependency on the monitoring module. Pass the workspace name to that later module, and resolve the existing workspace's customerId and listKeys() inside it.

Don't resolve those values in the parent deployment and pass them as module parameters. A constant-name workspace lookup can be evaluated before the monitoring module finishes, causing ResourceNotFound on a fresh deployment even when preview succeeds. The verified pattern is: monitoring module completes, environment module resolves workspace settings and creates the environment, then the Container App uses the environment module's resource-ID output.

Critical: Subscription Context

ALWAYS set AZURE_SUBSCRIPTION_ID explicitly before running azd up. Read it with az account show --query id -o tsv, then pass the returned value to azd env set AZURE_SUBSCRIPTION_ID <subscription-id>.

Without this, azd and Azure MCP tools will fail silently or produce incomplete deployments. The azure_deploy_app_logs tool also requires subscription context.

Critical: Bicep Output Naming

Bicep outputs MUST use SCREAMING_SNAKE_CASE (e.g., GRAFANA_URL, GRAFANA_FQDN) for azd to map them into environment values. Without this, azd env get-value returns "key not found".

Architecture

graph TB
    subgraph RG["Azure Resource Group"]
        LA["Log Analytics Workspace"]
        subgraph CAE["Container Apps Environment"]
            GF["Grafana Container App<br/>Port 3000 · SQLite (default)<br/>Scale 0-1 replicas"]
        end
    end

    LA -->|logs & metrics| CAE

Quick Start (Verified)

# 1. Register providers (one-time per subscription)
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

# 2. Create environment
azd env new my-grafana-env

# 3. Set required variables (replace placeholders)
azd env set AZURE_SUBSCRIPTION_ID "<subscription-id>"
azd env set AZURE_LOCATION "westus"
azd env set GRAFANA_ADMIN_PASSWORD "<securely-generated-secret>"

# 4. Deploy (~2 minutes)
azd up

# 5. Access Grafana
azd env get-value GRAFANA_URL
# Login: admin / <your GRAFANA_ADMIN_PASSWORD>

Deployment time breakdown:

• Resource Group: ~4s
• Log Analytics: ~25s
• Container Apps Environment: ~38s
• Grafana Container App: ~10s
• Total: ~2 minutes

Environment Variables

Grafana is configured via environment variables in the Container App:

See config/environment-variables.md for full list.

Health Probes

Outputs

After deployment:

• GRAFANA_URL: Public HTTPS URL
• GRAFANA_FQDN: Container App FQDN
• GRAFANA_ADMIN_USER: Admin username

Verification

Run the checked-in verifier from the repository root:

node .github/scripts/verify-grafana.mjs

The verifier reads GRAFANA_URL through azd, requires HTTP 200 from /api/health, asserts database: "ok", and prints the deployment URL. Verify authenticated browser login separately with the deployed admin credentials. Retrieve a generated password only in a private terminal, and never print or paste it into the agent session or shared logs.

For SQLite, also inspect the deployed Container App's properties.template.scale.maxReplicas through Azure CLI and require it to equal 1. The HTTP verifier doesn't check scaling configuration.

Scaling

• Min replicas: 0 (scale to zero when idle)
• Max replicas: 1 (required for SQLite)
• Scaling rule: HTTP concurrent requests (10 per replica)

Generate maxReplicas: 1 whenever Grafana uses SQLite, including when SQLite is persisted on Azure Files. Separate container-local databases cause inconsistent dashboards, users, and sessions across replicas. Keep this cap when temporarily setting minReplicas: 1 for verification. Multiple Grafana replicas require a shared PostgreSQL or MySQL database; don't add one to the default SQLite lab.

Storage Considerations

By default, Grafana uses SQLite which stores data in the container. For production:

1. Add Azure Files for persistent storage
2. Or use PostgreSQL/MySQL backend

Tear Down

azd down --force --purge

Note: Teardown takes 3-5 minutes (Container Apps environment deletion is slow).

Azure MCP Tools

Use these Azure MCP Server tools for Grafana deployments:

Troubleshooting

See troubleshooting.md for common issues and lessons learned.