Azure Integration - Atatus Docs

Atatus connects to Azure with an Entra ID App Registration. Once connected, Atatus collects Azure Monitor metrics, resource metadata, and (if you turn it on) resource logs, Activity Log, and Entra ID sign-in logs. There are two ways to set it up:

Setup	Use it when
Quickstart (recommended)	You can run one command in Azure Cloud Shell. It creates the identity, assigns the roles, deploys the log forwarder, and connects your resource logs, reporting progress to Atatus as it goes.
Manual	Your organization separates directory administration from subscription administration, or you want to create and review each object yourself.

Azure onboarding uses an Azure Cloud Shell script instead of an ARM template because the App Registration is an Entra ID directory object rather than an Azure resource. ARM templates cannot directly create Entra ID App Registrations.

How the connection works

Metrics and logs reach Atatus by two different mechanisms, and it matters when you come to remove the integration.

METRICS   Atatus ──pull──▶ Azure Monitor        nothing is deployed in your subscription

LOGS      Your resources ──▶ Diagnostic Settings ──▶ Blob Storage ──▶ Container Apps job ──▶ Atatus
          Log Analytics   ──▶ Data Export rule   ──▶       (all inside your own subscription)
          Microsoft Entra ──▶ Diagnostic Settings ──▶

Metrics are a pull. Atatus authenticates as the service principal and calls Azure Monitor. There is nothing running in your subscription for metrics. Logs are pushed from inside your subscription. Azure writes logs to a storage account in a resource group called atatus-log-forwarder, and a Container Apps job in that same group ships them to Atatus. Atatus never reaches into your subscription to fetch them. You keep control the whole time. Removing the role assignments, or deleting the App Registration, cuts Atatus off immediately.

Before you start

Make sure you have:

An Azure subscription, and permission to create an App Registration in the tenant. Application Developer in Entra ID, or an equivalent, is enough.
Permission to assign roles on the subscriptions you want to monitor: User Access Administrator or Owner.
Access to the Atatus dashboard.

For log collection you also need permission to create a resource group, a storage account, and Container Apps resources in the subscription.

Whoever evaluates Atatus is often not whoever owns the subscription. If the quickstart cannot assign a role it does not fail silently. It prints the exact az role assignment create commands for a subscription owner to run, and you re-run the quickstart afterwards.

Set up the integration

Pick a path. The tabs below hold the full steps for each one.

Quickstart
Manual integration

Step 1: Start in Atatus

In Atatus, go to Settings → Integrations and select Azure.
Click Add Azure Subscription.
Choose the subscriptions to monitor.
Choose what to collect:
- Metrics: Azure Monitor metrics and resource metadata. Nothing is deployed into your subscription.
- Logs: deploys the log forwarder and connects your resource logs.
Copy the command shown on screen with the Copy button.

Use the Copy button rather than selecting the text. The command carries a workflow id and a one-time setup nonce; a partially copied command aborts before it creates anything.

Step 2: Run the command in Cloud Shell

Open Azure Cloud Shell and choose Bash.
Paste the command and press Enter.

The script prints each stage as it completes, and the Atatus setup screen tracks the same stages live:

Stage	What happens
Run Quickstart in Cloud Shell	Confirms the session is authenticated and lists the subscriptions it can see.
Create Entra ID App Registration	Creates the app `atatus-integration`, its service principal, and a client secret.
Assign Monitoring Reader Role	Assigns the roles on every selected subscription.
Deploy Log Forwarder	Creates the `atatus-log-forwarder` resource group and its contents. Log collection only.
Connect Resource Logs	Attaches Diagnostic Settings to your resources. Log collection only.
Complete Quickstart Setup	Reports the service principal back to Atatus.
Create Atatus Integration	Atatus proves the credentials against Azure and starts collecting.

A metrics-only onboarding skips the two log stages entirely and does not render them.Typical runtime is one to three minutes for metrics only, and five to fifteen minutes with log collection on a large subscription.

Keep the Cloud Shell tab open until the script prints that it has finished. Cloud Shell ends idle sessions, and a session that ends mid-run leaves an App Registration with no roles. Re-running the quickstart is safe: it updates the objects it made last time rather than creating a second set.

Step 3: Confirm in Atatus

When the script reports completion, the Atatus tab moves to Create Atatus Integration and then to connected. Metrics appear within about ten minutes.

What the quickstart creates

Identity

Object	Name	Notes
App Registration	`atatus-integration`	One per tenant. Its client secret is valid for two years, or less if a tenant policy caps credential lifetime.
Service principal	(same app)	The object the role assignments actually bind to.

The client secret is sent to Atatus in the final status report and nowhere else. It is never echoed, never logged, and never passed on a command line.

Roles

Role	Scope	When	Why
`Monitoring Reader`	Each selected subscription	Always	Reads the metrics.
`Reader`	Each selected subscription	Always	Enumerates the resources those metrics belong to.
`Monitoring Contributor`	Each selected subscription	Log collection only	Replaces Monitoring Reader. Adds `Microsoft.Insights/diagnosticSettings/write`, the one action that lets the forwarder connect resources created after onboarding.
`Contributor`	The `atatus-log-forwarder` resource group only	Log collection only	Lets the forwarder deploy into a new region you expand into later. Scoped to the group Atatus created, never wider.

Monitoring Contributor is a materially larger consent than Monitoring Reader, so it is requested only when log collection is switched on. A metrics-only onboarding is read-only.

Log forwarding infrastructure

Everything lives in one resource group, atatus-log-forwarder:

Resource	Purpose
Storage account	Landing zone. Azure writes log blobs here; the forwarder drains them. Blobs are deleted after 1 day by a lifecycle rule.
Container Apps job (forward)	Runs every minute. Ships new blob content to Atatus, resuming from a byte offset.
Container Apps job (reconcile)	Runs every ten minutes. Keeps Diagnostic Settings matching your current resources, and asks Atatus whether it should still be collecting.
Container Apps job (teardown)	Runs on demand, when the integration is deleted.
Diagnostic Setting `atatus-logs`	On each loggable resource.
Diagnostic Setting `atatus-activity-log`	On the subscription itself, for the Activity Log.
Data export rule `atatus-logs`	On each Log Analytics workspace, for tables that exist only inside the workspace.

The container image is docker.io/atatus/azure-log-forwarder:latest, pulled anonymously from Docker Hub.

The reconciler is what a one-shot installer cannot be. Diagnostic Settings only exist on the resources that existed when you ran the quickstart. Without the reconciler, everything created afterwards emits nothing, forever, while the integration still reports success.

Run these as a user who can create an App Registration and assign roles. Replace the placeholders as you go.

Step 1: Create the App Registration

APP_ID=$(az ad app create --display-name atatus-integration --query appId -o tsv)
az ad sp create --id "$APP_ID"
SP_OBJECT_ID=$(az ad sp show --id "$APP_ID" --query id -o tsv)

# Save this. It is shown once and cannot be retrieved again.
az ad app credential reset --id "$APP_ID" --years 2 --query password -o tsv

az account show --query tenantId -o tsv   # your tenant id

Step 2: Assign the roles

For each subscription you want to monitor:

SUBSCRIPTION=<subscription-id>

# Metrics only, read-only:
az role assignment create --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Monitoring Reader" --scope "/subscriptions/${SUBSCRIPTION}"

# With log collection, use this instead of Monitoring Reader:
az role assignment create --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Monitoring Contributor" --scope "/subscriptions/${SUBSCRIPTION}"

# Always:
az role assignment create --assignee-object-id "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Reader" --scope "/subscriptions/${SUBSCRIPTION}"

Entra ID replicates a new service principal asynchronously. A role assignment made seconds after the principal is created can fail with PrincipalNotFound. Wait a few seconds and retry. The quickstart retries six times for this reason.

For metrics only, stop here and go to Step 5.

Step 3: Deploy the log forwarder

az deployment sub create \
  --location <region> \
  --template-uri https://atatus-cloudformation-templates.s3.us-east-1.amazonaws.com/azure/atatus_log_forwarder_containerapp.json \
  --parameters \
    atatusApiKey=<your-atatus-api-key> \
    atatusLogsUrl=https://log-ingest.atatus.com/v1/azure/logs \
    reconcilerTenantId=<tenant-id> \
    reconcilerClientId="$APP_ID" \
    reconcilerClientSecret=<client-secret> \
    reconcilerPrincipalId="$SP_OBJECT_ID" \
    reconcilerSubscriptionIds=<comma-separated-subscription-ids>

Useful parameters:

Parameter	Default	Meaning
`resourceGroupName`	`atatus-log-forwarder`	Created if absent.
`logRetentionDays`	`1`	How long a blob is kept before the lifecycle rule deletes it. The forwarder ships within a minute, so one day is already a large margin. A blob that expires before it is drained is lost.
`forwarderCron`	`* * * * *`	How often the forward job runs. Every minute is the shortest Container Apps allows.
`forwarderSize`	`small`	`small` (0.5 vCPU / 1 GiB), `medium` (1 / 2 GiB), `large` (2 / 4 GiB).
`forwarderConcurrency`	`8`	Blobs drained at once. Raise this first if the backlog grows.
`forwardActivityLog`	`true`	Also stream the subscription Activity Log.
`deployRegionalForwarders`	`true`	Deploy a forwarder into every region that holds loggable resources. Azure refuses a Diagnostic Setting whose storage destination is in another region, so without this you collect logs from one region only.
`diagnosticSettingName`	`atatus-logs`	Shared with the quickstart, so both update one setting.

Leaving reconcilerClientSecret blank deploys the forward job without the reconciler, which is what a read-only onboarding wants. Diagnostic Settings then have to be created and maintained by you.The deployment outputs the storage account id. Note it, because Step 4 needs it.

Step 4: Connect your resource logs

The deployment in Step 3 already creates the subscription Activity Log setting (atatus-activity-log), covering the Administrative, Security, ServiceHealth, Alert, Recommendation, Policy, Autoscale and ResourceHealth categories. Pass forwardActivityLog=false if you do not want it.What remains is the per-resource settings. Log categories differ per resource type (an App Service has AppServiceHTTPLogs, a SQL database has SQLSecurityAuditEvents), so read them from the resource rather than hardcoding a list, which any resource lacking one of the names rejects outright:

RESOURCE=<resource-id>
STORAGE=<storage-account-id-from-step-3>

CATEGORIES=$(az monitor diagnostic-settings categories list --resource "$RESOURCE" \
  --query "value[?categoryType=='Logs'].name" -o tsv)

LOGS=$(printf '%s\n' "$CATEGORIES" | python3 -c \
  'import json,sys; print(json.dumps([{"category":n,"enabled":True} for n in sys.stdin.read().split()]))')

az monitor diagnostic-settings create \
  --name atatus-logs \
  --resource "$RESOURCE" \
  --storage-account "$STORAGE" \
  --logs "$LOGS"

Skip any resource inside the atatus-log-forwarder resource group. Wiring those would forward the forwarder’s own logs back to itself.

Azure limits a resource to five Diagnostic Settings. Always use the name atatus-logs so a re-run updates the setting instead of adding another one.A Diagnostic Setting cannot write to a storage account in a different region. Multi-region estates need one forwarder stack per region, which is what deployRegionalForwarders handles for you.

Doing this by hand covers only the resources that exist today. Anything created later emits nothing until you repeat it, which is the job the reconciler does for you when you supply reconcilerClientSecret in Step 3.

Step 5: Finish the setup in Atatus

Return to the Atatus tab.
Enter the Tenant ID, Application (client) ID, Client secret, and the subscription IDs.
Click Save.

Atatus authenticates against Azure Monitor immediately as a check. If it succeeds, the integration is created.

Where the log forwarder runs

Both setup paths above run the forwarder as Azure Container Apps jobs in the atatus-log-forwarder resource group, which is the default and the only option Atatus manages for you. If you already operate a Kubernetes cluster, you can move the log forwarder there after the quickstart. See Move the Azure log forwarder to Kubernetes. Running it on Kubernetes is a manual setup, and the cluster, the CronJobs and their upgrades are yours to manage. The move keeps every region you collect from today.

Verify the setup

In Atatus: Settings → Integrations → Azure shows the subscription as connected.
Metrics: open any Azure dashboard in Atatus. Data appears within about ten minutes.
Logs: go to Logs and filter by source:azure.
In Azure: the atatus-log-forwarder resource group exists, and the job execution history shows successful runs.

Each forward run logs a line like:

forwarded 812 record(s) from 40 blob(s), 1048576 bytes, 0 failure(s), 61 blob(s) seen, backlog 0 bytes

A backlog near zero means the schedule is keeping up. A figure that climbs run over run means the forwarder is falling behind, so raise forwarderConcurrency first, then forwarderSize.

Troubleshooting

The quickstart cannot assign a role

You have permission to create the App Registration but not to assign roles on the subscription. The script prints the exact az role assignment create commands to hand to a subscription owner. It keeps the App Registration it created, so once the roles are assigned you re-run the quickstart and it picks up where it left off rather than creating a second app.

No logs are arriving, but metrics work

Check in this order:

Diagnostic Settings exist. Open any resource → Diagnostic settings. There should be one named atatus-logs. If not, the reconciler is not running or lacks Monitoring Contributor.
The reconcile job is succeeding. Container Apps job execution history in atatus-log-forwarder.
The forward job is succeeding, and its backlog line is near zero.
The region matches. A Diagnostic Setting cannot write to a storage account in another region. Confirm deployRegionalForwarders was left on.

To find out why a specific resource is producing nothing, run the reconcile job with ATATUS_RECONCILE_DRY_RUN=1. It reports what it would connect without changing anything.

Logs from Application Insights or Automation Accounts are missing

Some log types only ever exist inside a Log Analytics workspace and can never be reached by a Diagnostic Setting: Automation Account JobLogs, Application Insights tables, and Entra sign-ins routed to a workspace. These need a workspace Data Export rule, which the quickstart creates as atatus-logs. Check the rule exists on the workspace, and that the workspace is in a region that supports data export.

The forwarder job is not starting

The container image must be pullable anonymously from inside your subscription. If your subscription restricts registries by policy, allow docker.io/atatus/azure-log-forwarder:latest.

The client secret expired

The quickstart requests a two year secret, and a tenant policy can force a shorter one. When it expires, metric collection stops and the reconciler can no longer maintain Diagnostic Settings. Re-run the quickstart, and it resets the credential on the existing app and reports the new secret to Atatus.

Pause the integration

To stop collection without removing anything, set the integration to Disabled in Atatus. Within ten minutes the reconciler asks Atatus what it should be doing and stops. The configuration is kept, so re-enabling restores it without re-onboarding.

Remove the integration

Removing Atatus from Azure is three separate operations:

DELETE INTEGRATION   stop sending data to Atatus            Atatus dashboard
UNINSTALL            remove the forwarding resource group   atatus_azure_uninstall.sh
REMOVE ACCESS        remove the Entra app and its roles     atatus_azure_uninstall.sh --remove-identity

Deleting the integration does not uninstall anything, and uninstalling does not revoke access. Pausing an evaluation, reclaiming the storage cost, and removing a vendor’s read access to your tenant are not the same request.

If you moved the forwarder to Kubernetes, steps 1 and 3 below still apply, but step 2 does not. The uninstall script only knows about the Container Apps deployment, so follow the removal steps in Move the Azure log forwarder to Kubernetes instead.

1. Delete the integration

In Atatus, go to Settings → Integrations → Azure and delete the subscription. Atatus cannot do this cleanup itself. Every Diagnostic Setting lives on your resources, and the only thing able to remove one is the job running in your subscription, with a credential Atatus does not hold. So the delete is a handshake:

Delete in Atatus  ──▶  integration marked DELETING
                              │
        reconciler's ten-minute tick asks Atatus what to do
                              │  told to tear down
                              ▼
              1. Remove every Diagnostic Setting it created
                 (your resources, plus the subscription Activity Log)
                              │
                     all of them gone?  ── no ──▶ retry next run
                              │ yes
                              ▼
              2. Delete the log containers those settings filled
                              │
                              ▼
              3. Report back to Atatus, which removes the integration

The order is forced. While one Diagnostic Setting still points at the storage account, Azure re-creates a deleted container on its next write. Purging first would delete containers that immediately come back and report a cleanup that did not happen. Your collected logs are deleted at this point, not left to expire. Removing the settings stops collection; it does not reclaim what was already collected, so the same run deletes the insights-logs-*, insights-metrics-* and am-* containers from the storage account. What remains afterwards is the infrastructure: the storage account itself, the jobs, and the managed environment. That is step 2. A large estate takes several ten-minute cycles. Watch progress in the job execution history:

az containerapp job execution list -g atatus-log-forwarder \
  -n $(az containerapp job list -g atatus-log-forwarder \
       --query "[?contains(name,'reconcile')].name" -o tsv) \
  --query "[0].properties.status" -o tsv

A metrics-only integration deletes immediately. Nothing was ever deployed into your subscription, so there is nothing to remove and nothing to wait for.If a deployment cannot report back for 24 hours (the resource group deleted by hand, the job stopped, the secret expired), Atatus marks the delete orphaned rather than complete, and tells you what may remain. It does not claim a subscription is clean when nobody can confirm it.There is no final drain. Forwarding stops as soon as the integration is marked for deletion, so log data written in the last minute or so is deleted with the containers rather than shipped.

2. Uninstall the forwarder

Download and run the uninstall script:

curl -O https://atatus-artifacts.s3.us-east-1.amazonaws.com/atatus-cloud-templates/azure/atatus_azure_uninstall.sh
chmod +x atatus_azure_uninstall.sh
./atatus_azure_uninstall.sh --subscription <subscription-id>

Run it in Azure Cloud Shell, or on any machine with the Azure CLI signed in. It needs the az CLI and jq, both of which are already present in Cloud Shell. The script reads the teardown record from the storage account, confirms the settings were removed, and then deletes the atatus-log-forwarder resource group.

Flag	Effect
`--subscription <id>`	Required. The subscription to clean up.
`--resource-group <name>`	If you renamed it. Default `atatus-log-forwarder`.
`--status`	Report the teardown state and delete nothing. Exits non-zero if teardown has not finished.
`--force`	Delete the group without a completed teardown record. See the warning below.
`--remove-identity`	Also delete the App Registration and its role assignments.
`--client-id <id>`	Supply the client id when the group is already gone and it cannot be read.

Do step 1 before step 2, and the script enforces it. Your Diagnostic Settings live on your resources, not in the atatus-log-forwarder group, and the only record of which resources carry one is a state blob inside that group’s storage account. Delete the group first and every setting survives it, attached to resources across the subscription, pointing at a storage account that no longer exists, and unfindable, because the list went with the group.The script refuses to delete anything until it has read a completed teardown record.

--force is for a deployment that can no longer run at all, such as an expired client secret, a revoked role assignment. It prints exactly what will be left behind and asks you to type the resource group name to confirm. You then have to remove the settings by hand: look for a Diagnostic Setting named atatus-logs on your resources, and atatus-activity-log on the subscription itself. If the resource group is already gone, the script says so and exits cleanly.

3. Remove access

./atatus_azure_uninstall.sh --subscription <subscription-id> --remove-identity

This deletes the role assignments the Atatus service principal holds, then the App Registration itself. After it runs, Atatus can no longer read your tenant. It is opt-in and never implicit: until it runs, a service principal with Reader on your subscriptions still exists. The app is identified by the client id recorded in the forwarder’s own job configuration, so nothing you created yourself can be matched by accident. If the resource group has already been deleted, the client id cannot be read from it, so pass --client-id, which the Atatus dashboard shows as Application (client) ID. Removing the role assignments needs User Access Administrator on their scope, and deleting the App Registration needs Application Administrator. If you lack either, the script says which assignment it could not remove, and you can finish in the portal under Entra ID → App registrations.

​How the connection works

​Before you start

​Set up the integration

​Step 1: Start in Atatus

​Step 2: Run the command in Cloud Shell

​Step 3: Confirm in Atatus

​What the quickstart creates

​Identity

​Roles

​Log forwarding infrastructure

​Step 1: Create the App Registration

​Step 2: Assign the roles

​Step 3: Deploy the log forwarder

​Step 4: Connect your resource logs

​Step 5: Finish the setup in Atatus

​Where the log forwarder runs

​Verify the setup

​Troubleshooting

​The quickstart cannot assign a role

​No logs are arriving, but metrics work

​Logs from Application Insights or Automation Accounts are missing

​The forwarder job is not starting

​The client secret expired

​Pause the integration

​Remove the integration

​1. Delete the integration

​2. Uninstall the forwarder

​3. Remove access

How the connection works

Before you start

Set up the integration

Step 1: Start in Atatus

Step 2: Run the command in Cloud Shell

Step 3: Confirm in Atatus

What the quickstart creates

Identity

Roles

Log forwarding infrastructure

Step 1: Create the App Registration

Step 2: Assign the roles

Step 3: Deploy the log forwarder

Step 4: Connect your resource logs

Step 5: Finish the setup in Atatus

Where the log forwarder runs

Verify the setup

Troubleshooting

The quickstart cannot assign a role

No logs are arriving, but metrics work

Logs from Application Insights or Automation Accounts are missing

The forwarder job is not starting

The client secret expired

Pause the integration

Remove the integration

1. Delete the integration

2. Uninstall the forwarder

3. Remove access