Observability (Managed Grafana)¶

Dit runbook is voor het platformteam. Het behandelt de optionele observability-tier: een Azure Managed Grafana-instance per omgeving die Log Analytics leest en de gezondheid van Fabric-pipelines toont. Workload teams lezen Monitoring.

Wat wordt uitgerold¶

De tier is een aparte Terraform-root (infra/deploy/observability) met een eigen state (observability.tfstate), dus met een eigen lifecycle. De enige afhankelijkheid is de Log Analytics workspace van de spoke, die eerst moet bestaan.

flowchart LR
    fp["Fabric pipelines"] --> lh["pipeline_logs Lakehouse"]
    lh --> law["Log Analytics workspace"]
    law --> g["Managed Grafana (KQL dashboards)"]
    law --> alert["Scheduled query rule: pipeline failures"]
    law -->|"data export rule (optional)"| st["Storage account: cool, then archive, then delete"]

Resource	Opmerkingen
Resource group	`rg-<workload>-observability-<env>-<region>-001`
Managed Grafana	`grafana-<workload>-<env>-<region>`, SKU `Standard`, standaard grootte `X1`, major versie `12`, system-assigned identity, deterministische uitgaande IP's aan, API-sleutels uit, publieke toegang standaard aan, zoneredundantie standaard uit
Role assignments voor de Grafana-identity	Monitoring Reader en Log Analytics Reader op elke gekoppelde Log Analytics workspace
Role assignments voor groepen	Grafana Admin, Grafana Editor en Grafana Viewer voor de groepen in `grafana_rbac`
Private endpoint (optioneel)	In het private endpoint-subnet van de spoke. Private DNS wordt door policy ingesteld, dus Terraform negeert wijzigingen aan de DNS zone group.
Diagnostic setting	Auditlogs en metrics van Grafana naar de eerste Log Analytics workspace
Alert rule en action group	`alert-pipeline-failure-grafana-...` en `ag-pipeline-alerts-grafana-...`
Opslag van historische logs (optioneel)	Een storage account met een data export rule en een lifecycle policy

Ontwerpbeslissingen¶

Beslissing	Reden
Eigen resource group en state	Isoleert observability van workloadresources en geeft een onafhankelijke lifecycle
System-assigned managed identity	Grafana leest Log Analytics zonder credentials, over de Azure-backbone
Deterministische uitgaande IP's	Egress-adressen liggen vast, zodat ze in logs kunnen worden herkend en in firewalls kunnen worden toegestaan
Alleen Entra ID, geen API-sleutels	Alle toegang loopt via Entra ID met MFA via Conditional Access. Automatisering gebruikt een service principal of managed identity.
Aparte groepen voor Grafana	Andere blast radius: toegang tot Grafana is geen toegang tot Fabric
Standaard publiek, private endpoint optioneel	Ontwikkeling gebruikt publieke toegang met Entra ID en MFA. Productie kan beperken tot het VNet.
Dashboards als code	JSON-templates in de configuratierepository, geprovisioned met de Grafana Terraform-provider

Vereisten¶

Securitygroepen¶

Maak vóór het deployen drie Entra ID-securitygroepen per workload aan. Ze staan los van de Fabric-workspacegroepen.

Groep (naamgevingspatroon)	Grafana-rol	Beoogde leden
`sg-fabric-<workload>-grafana-admins`	Admin	Engineers van het platformteam
`sg-fabric-<workload>-grafana-editors`	Editor	Data engineers en analisten van het workload team
`sg-fabric-<workload>-grafana-viewers`	Viewer	Businessstakeholders, management

Voor het aanmaken van groepen is de rol Groups Administrator of Global Administrator in Entra ID nodig.

WORKLOAD="<workload>"
for role in admins editors viewers; do
  az ad group create \
    --display-name "sg-fabric-${WORKLOAD}-grafana-${role}" \
    --mail-nickname "sg-fabric-${WORKLOAD}-grafana-${role}" \
    --security-enabled true --query id -o tsv
done

Voeg leden toe met az ad group member add --group <name> --member-id <object id>. Zet de object-ID's in de variabelen:

grafana_rbac = {
  admins  = ["<admins group object id>", "<deploying service principal object id>"]
  editors = ["<editors group object id>"]
  viewers = ["<viewers group object id>"]
}

De deployende service principal moet Grafana Admin zijn

De dashboards worden via de Grafana API geprovisioned. Daarvoor is de rol Grafana Admin op de instance nodig, een aparte assignment naast de Contributor-rechten waarmee de instance wordt aangemaakt. Zet de object-ID van de deployende service principal in grafana_rbac.admins.

Overig¶

De ID's van de Log Analytics workspaces die je wilt koppelen (log_analytics_workspace_ids). De eerste wordt gebruikt voor diagnostics, de alert rule, de data export rule en de templatevariabele van het dashboard.
Optioneel het subnet en de private DNS-zone voor een private endpoint.

Variabelen¶

Variabele	Doel en standaardwaarde
`grafana_config`	`sku` (`Standard`), `sku_size` (`X1`), `api_key_enabled` (`false`), `deterministic_outbound_ip_enabled` (`true`), `public_network_access` (`true`), `zone_redundancy` (`false`), `grafana_major_version` (`"12"`)
`grafana_private_endpoint`	`enabled` (`false`), `subnet_id`, `private_dns_zone_id`
`grafana_rbac`	Lijsten met object-ID's voor `admins`, `editors`, `viewers`
`alert_rules`	`pipeline_failure_enabled` (`false`), `pipeline_failure_interval` (300 seconden), `pipeline_failure_lookback` (3600 seconden), `notification_contact_emails`
`dashboard_definitions`	`enabled` (`false`)
`dashboard_path`	Map met de dashboards. Door de pipeline ingesteld via de omgevingsvariabele `TF_VAR_dashboard_path`.
`historical_log_storage`	Zie Bewaren van historische logs

Toegestane regio's en omgevingen zijn dezelfde als voor de andere tiers (Platformconfiguratie).

Deployment¶

De pipeline heeft een run-optie om de observability-tier te deployen. De pipelinedefinities maken geen deel uit van de bron van deze oplossing, dus de exacte naam van de optie hangt af van je pipeline.

Twee fasen bij de eerste deployment. De Grafana-provider heeft de URL nodig van een instance die nog niet bestaat.

Fase	Wat er gebeurt
Eerste run	De Grafana-instance, role assignments, diagnostics en alert rule worden aangemaakt. De dashboardresources mislukken omdat er nog geen endpoint is. Dit is te verwachten.
Tweede run	De pipeline leest de output `grafana_endpoint`, haalt een token op voor de Azure Managed Grafana-applicatie (omgevingsvariabelen `GRAFANA_URL` en `GRAFANA_AUTH`) en de dashboards worden geprovisioned

Daarna is elke run één fase. Data engineers voegen dashboards toe in de configuratierepository en zetten dashboard_definitions.enabled = true.

De dashboardmap heeft één submap per Grafana-folder en één .json-bestand per dashboard. De module vindt alle */*.json-bestanden, dus configuratie per bestand is niet nodig. Het bestand is een Terraform-template met één variabele: ${LAW_RESOURCE_ID}. Template-variabelen van Grafana moeten worden ge-escaped ($${...}).

Securitymaatregelen¶

Maatregel	Implementatie
Authenticatie	Entra ID SSO, geen lokale accounts
MFA	Conditional Access-policies
API-sleutels	Standaard uitgeschakeld. Indien ingeschakeld is rotatie handmatig.
Auditlogging	Diagnostic settings naar Log Analytics (auditlogs, alle logs, metrics)
Uitgaande IP's	Deterministisch
TLS	Alleen HTTPS
Scope van het DNS-label	`TenantReuse`, wat een voorspelbare DNS-naam geeft
Private DNS	Beheerd door policy

Bewaren van historische logs¶

Logs kunnen in tiers worden opgeslagen voor goedkopere retentie op lange termijn. Dit staat standaard uit (historical_log_storage.enabled = false).

Tier	Duur	Opslag	Bevragen
Hot	0 tot 30 dagen	Log Analytics workspace	Interactieve KQL
Cool	31 tot 90 dagen	Blob storage, cool	Log search jobs of restore
Archive	91 tot 365 dagen	Blob storage, archive	Eerst rehydrate (duurt uren)

Instelling	Standaard
`export_tables`	`["FabricPipelineRuns_CL"]`
`archive_after_days`	`90`
`delete_after_days`	`365`
`law_resource_group_name`	Resource group van de Log Analytics workspace, nodig voor de export rule

Het storage account is Standard, LRS, StorageV2, access tier Cool, met soft delete van 7 dagen voor blobs en containers. Een lifecycle rule verplaatst blobs naar archive en verwijdert ze na het ingestelde aantal dagen. Vereisten: de custom tabel moet in Log Analytics bestaan voordat de export rule kan worden aangemaakt, en export rules ondersteunen alleen custom tabellen op basis van DCR (achtervoegsel _CL). Deploy de opslag voor historische logs nadat de data engineers de pipeline voor log-ingestie hebben ingericht.

Problemen oplossen¶

Symptoom	Oorzaak	Oplossing
"No data" in alle panelen	De tabel `FabricPipelineRuns` bestaat nog niet	De data engineering-pipeline heeft Log Analytics nog niet gevuld
"No data" in sommige panelen	Tijdsbereik te smal, of geen runs met die status	Vergroot het tijdsbereik, controleer of pipelines hebben gedraaid
"Insufficient permissions" op de databron	De role assignments van de Grafana-identity zijn nog niet doorgevoerd	Wacht 10 minuten na de deployment
Aanmelden lukt niet (403)	Gebruiker zit niet in een Grafana-groep	Voeg de gebruiker toe aan een groep
Aanmelden lukt niet (timeout) in private modus	VPN of ExpressRoute is niet verbonden, of DNS geeft geen privé-IP terug	Verbind en controleer DNS
"Datasource not found"	De Azure Monitor-databron is niet geconfigureerd	Controleer of de Grafana-identity Monitoring Reader heeft op de workspace
Alert gaat niet af	Regel uitgeschakeld, of geen e-mail geconfigureerd	Controleer `pipeline_failure_enabled` en `notification_contact_emails`
Deployment mislukt op `grafana_major_version`	De Standard SKU heeft een ondersteunde major versie nodig	Zet `grafana_major_version = "12"`
Terraform wil `private_dns_zone_group` wijzigen	Policy heeft de DNS zone group na het aanmaken ingesteld	Verwacht gedrag. Houd het lifecycle-blok `ignore_changes`.

Bekende beperkingen¶

Geen rechten op folder- of dashboardniveau in Azure Managed Grafana. Opties als je scheiding nodig hebt: één instance per team (elk met eigen groepen en Log Analytics-koppelingen), een gedeelde instance accepteren, of je eigen Grafana Enterprise draaien (meer kosten en beheer).
Geen geautomatiseerde rotatie van Grafana API-sleutels, als je ze inschakelt.
Alerts voor pipelinefouten sturen alleen e-mail als notification_contact_emails is gevuld.
Alleen de eerste Log Analytics workspace wordt gebruikt voor de alert rule en de dashboardvariabele.