# Connect Azure

# Connect Azure

Costfluent reads Azure cost through a service principal you create. One connection is one service
principal, and it imports every subscription you assign that principal to, so several subscriptions
do not need several connections.

Connecting imports the previous six months of cost for each subscription.

## What Costfluent is granted

Two built-in roles, and nothing else:

- **Cost Management Reader** — read the Cost Details report the import is built on.
- **Reader** — read the subscription metadata that labels the cost.

Neither role can change anything in your subscription. Do not grant `Contributor` or `Owner`.

Assign them per subscription, or once at a management group covering the subscriptions you want
imported. A management-group assignment also covers subscriptions added to it later.

## Create the service principal

Confirm which tenant and subscription you are working in:

```shell
az account show --query '{tenantId:tenantId,subscriptionId:id,subscriptionName:name}' --output table
```

Create the service principal. The output contains `appId`, `password` and `tenant`; the password
cannot be retrieved later, so store it in your password manager now.

```shell
az ad sp create-for-rbac --name "Costfluent" --output json
```

## Grant the two roles

Repeat this for each subscription you want imported:

```shell
SUBSCRIPTION_ID="$(az account show --query id --output tsv)"
APP_ID="<the appId from the previous step>"

az role assignment create --assignee "$APP_ID" \
  --role "Cost Management Reader" --scope "/subscriptions/$SUBSCRIPTION_ID"

az role assignment create --assignee "$APP_ID" \
  --role "Reader" --scope "/subscriptions/$SUBSCRIPTION_ID"
```

Or grant both once at a management group, which covers every subscription under it:

```shell
MANAGEMENT_GROUP_ID="<your management group id>"
SCOPE="/providers/Microsoft.Management/managementGroups/$MANAGEMENT_GROUP_ID"

az role assignment create --assignee "$APP_ID" --role "Cost Management Reader" --scope "$SCOPE"
az role assignment create --assignee "$APP_ID" --role "Reader" --scope "$SCOPE"
```

Role assignments take a moment to propagate. An authorization failure immediately after creating
them is not proof that the credentials are wrong.

## Add the connection

In Costfluent, open **Settings**, then **Integrations**, select **Azure**, and open the **Connect**
tab. Fill in the three fields:

| Field | Value |
|---|---|
| Azure AD Tenant ID | `tenant` from the service principal |
| Service Principal App ID | `appId` from the service principal |
| Service Principal Password | `password` from the service principal |

There is no subscription field: which subscriptions are imported is decided by the role assignments
you made above, and Costfluent reads that from Azure.

Costfluent validates the credentials against the Cost Details API before saving them, so a
connection that saves is a connection that can read your cost.

## After connecting

The **Manage** tab lists the connection by its tenant ID. Open the gear icon beside it to see
whether the credentials still work, which workspaces the connection feeds, which billing months have
been imported, and a **Subscriptions** card listing every subscription the principal reaches with
what the connection does with each.

A subscription the principal can see but cannot read cost for is listed as unavailable with the
reason, rather than appearing healthy and never producing data. Granting a role on another
subscription later needs no new connection: it appears after the next check, and is imported from
the same six months back.

**Run checks** on the connection page runs the checks again on request and reports each one
separately, so a failure names the step that failed: signing in, or reading cost data. The run
happens in the background, and the page updates itself when it finishes.

## Rotating or removing the credentials

Reset the service-principal credential in Azure, then use **Update credentials** on the connection
page. To retire the connection, remove it in Costfluent and delete both role assignments and the
service principal in Azure.