Skip to content

Commit

Permalink
Merge pull request #237 from vantage-sh/azure-ea-instructions
Browse files Browse the repository at this point in the history 
Azure EA/MCA Docs
  • Loading branch information
@vansia43
vansia43 authored Feb 25, 2025
2 parents 52ac653 + 7f12037 commit a38412b
Show file tree
Hide file tree
Showing 10 changed files with 279 additions and 33 deletions.
50 changes: 18 additions & 32 deletions docs/connecting_azure.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,31 @@ toc_max_heading_level: 4
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Vantage integrates with your Azure account using an Active Directory [Service Principal](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/service-accounts-principal). This principal is then assigned access to either [management groups](https://learn.microsoft.com/en-us/azure/governance/management-groups/overview) or individual [subscriptions](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-subscriptions).
Vantage integrates with your Azure account using an Active Directory [service principal](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/service-accounts-principal).

## Before You Begin: Review Azure Billing Account Types

Microsoft offers different billing account types based on your organization’s setup. The way that you'll complete your Azure integration with Vantage depends on which account type you have.

:::tip
To determine your billing account type, follow the steps in the [Azure documentation](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/view-all-accounts#check-the-type-of-your-account).
:::

If your organization uses a Microsoft Customer Agreement (MCA) or Enterprise Agreement (EA), follow the specific integration steps linked below. If you are on another account type such as a Cloud Solution Provier (CSP) or Pay as You Go, use the instructions on this page to integrate your account with Vantage.

- [Microsoft Customer Agreement (MCA) Vantage integration steps](/connecting_azure_mca)
- [Enterprise Agreement (EA) Vantage integration steps](/connecting_azure_ea)

## Connect Your Azure Account (Non-MCA or EA Account)

This service principal is assigned access to either [management groups](https://learn.microsoft.com/en-us/azure/governance/management-groups/overview) or individual [subscriptions](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-subscriptions).

You can connect hundreds of Azure subscriptions to Vantage through the management group method. Any subscriptions that are part of a [resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) will be automatically imported.

:::note
The service principal is granted [Reader](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#reader) permissions. It does **not** have permissions—nor will it ever attempt—to make any changes to your infrastructure.
:::

## Connect Your Azure Account

:::tip
Instructions are provided below for you to connect via the [Azure CLI](/connecting_azure#azure-cli) or the [Azure portal](/connecting_azure#azure-portal).
:::
Expand Down Expand Up @@ -166,35 +181,6 @@ After you complete the steps for connecting via the Azure CLI or Azure portal, f
3. Add the **Azure AD Tenant ID**, **Service Principal App ID**, and **Service Principal Password** you previously obtained, then click **Connect Account**. Vantage will begin importing your Azure costs.
4. See the [Workspace Access](/connecting_azure#workspace-access) section below for some additional steps.

## Azure MCA Customers: Additional Integration Steps {#azure-mca}

If you currently have an [Microsoft Customer Agreement (MCA) account](https://learn.microsoft.com/en-us/azure/cost-management-billing/understand/mca-overview), after you complete the steps above, you need to follow the additional steps below to ensure Vantage pulls data from this top-level billing scope instead of pulling data subscription by subscription. With these additional steps, you will allow the service principal to have access at the billing scope level.

### Step 1: Obtain Your Billing Account ID

1. In Azure, navigate to **Cost Management + Billing**.
2. On the left menu, click **Billing scopes**.
3. Select your **MCA Billing Account** from the list.
4. On the left menu, click **Settings** > **Properties**.
5. Copy your **Billing account id** to later send to Vantage.

### Step 2: Assign the Billing Account Reader Role to the Service Principal

1. From the left menu, select **Access Control (IAM)**.
2. At the top, click **Add**.
3. On the right **Add role assignment** menu, select **Billing account reader**.
4. Under **Users, groups, or apps**, select the `vantage` service principal you previously created.
:::note
If you already have a Billing Reader group, add the `vantage` service principal as a new member.
:::
5. Click **Add**.

### Step 3: Send Your Billing Account ID to Vantage

Send the **Billing account id** you previously copied to [[email protected]](mailto:[email protected]).
- Indicate that you have set up an Azure integration and that you are a customer on an MCA agreement.
- In addition, indicate whether you want your Azure costs set to amortized or actual (unamortized). Note that with amortization, Reserved Instances and Savings Plans are visible.

## Next Steps: Manage Workspace Access {#workspace-access}

Once your costs are imported, select which workspaces this integration is associated with. See the [Workspaces](/workspaces#integration-workspace) documentation for information.
Expand Down
150 changes: 150 additions & 0 deletions docs/connecting_azure_ea.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
---
id: connecting_azure_ea
title: Azure EA Account
description: This page walks through how to connect your Azure EA account to Vantage.
keywords:
- Azure EA
- Connect Azure
---

# Azure EA Account

With the Azure EA integration, you allow the service principal to have access at the billing scope level.

:::note
When you configure this integration, the Vantage service principal is granted **enrollment reader** permissions. The service principal does _not_ have permissions—nor will it ever attempt—to make any changes to your infrastructure.
:::

To integrate your Azure EA account with Vantage, follow the below steps:

<table>
<tr><td><b>1</b></td><td><a href="/connecting_azure_ea#ea-step1">Create a new application registration</a></td></tr>
<tr><td><b>2</b></td><td><a href="/connecting_azure_ea#ea-step2">Generate a client secret</a></td></tr>
<tr><td><b>3</b></td><td><a href="/connecting_azure_ea#ea-step3">Obtain your billing account ID</a></td></tr>
<tr><td><b>4</b></td><td><a href="/connecting_azure_ea#ea-step4">Assign Enrollment Reader permission to the service principal</a></td></tr>
<tr><td><b>5</b></td><td><a href="/connecting_azure_ea#ea-step5">Add app registration credentials to Vantage</a></td></tr>
<tr><td><b>6</b></td><td><a href="/connecting_azure_ea#ea-step6">Send your billing account ID to Vantage</a></td></tr>
</table>

## Step 1: Create a New Application Registration {#ea-step1}

1. From the main page of the Azure portal, search for and navigate to **Microsoft Entra ID**.
2. In the left navigation, under **Manage**, select **App registrations**.
3. Click **+ New registration**.
<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure portal with App Registration menu option selected" width="100%" src="/img/connect-azure/azure-new-app-registration.png"/> </div>
</details>
4. The **Register an application** screen is displayed. For **Name**, enter _vantage_.
5. Leave all other settings as their defaults and click **Register**.
<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure portal the Register an application screen and vantage entered as app name" width="100%" src="/img/connect-azure/azure-register-app.png"/> </div>
</details>
6. The app details are displayed. Record the **Application (client) ID** and **Directory (tenant) ID** to use later.
<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure portal with the client ID and tenant ID displayed and highlighted" width="100%" src="/img/connect-azure/azure-app-ids.png"/> </div>
</details>

## Step 2: Generate a Client Secret {#ea-step2}

1. On the same page, next to the **Client credentials** field, click **Add a certificate or secret**. (You can also access the **Certificates and secrets** screen from the left navigation menu.)
2. Click **+ New client secret**.
3. The **Add a client secret** pane is displayed. For **Description**, enter a description, such as _vantage-secret_.
<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure portal with the Azure client secret window open and a new secreted created called vantage-secret" width="100%" src="/img/connect-azure/azure-client-secret.png"/> </div>
</details>
4. For **Expires**, select an expiration option for the secret.
:::caution
If this secret expires, you will need to supply Vantage with a new secret _before_ the expiration date.
:::
5. Click **Add**.
6. The newly created secret is displayed. Copy the secret's **Value** to add to the Vantage console later. This value will be displayed only one time.

## Step 3: Obtain Your Billing Account ID {#ea-step3}

1. Navigate to **Cost Management + Billing**.
2. On the left menu, click **Billing scopes** and select your **EA Billing Account** from the list.
3. On the left menu, click **Settings** > **Properties**.
4. Copy your **Billing account id** to [later send to Vantage](/connecting_azure_ea#ea-step6).

## Step 4: Assign Enrollment Reader Permission to the Service Principal {#ea-step4}

:::note
You need to have the **billing account owner** role permissions to assign enrollment reader permissions to the service principal. The below steps are based on the [Azure documentation](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/assign-roles-azure-service-principals).
:::

1. Navigate to **Microsoft Entra ID**, then select **Enterprise applications**.
2. From the **All applications** list, select the _vantage_ application you previously created.
<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure portal with all apps listed in Enterprise Applications" width="100%" src="/img/connect-azure/azure-ea-all-apps.png"/> </div>
<i>Source: Microsoft</i>
</details>
3. Under **Properties**, copy the **Application ID** and **Object ID**.
<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure portal with App and Object ID listed" width="100%" src="/img/connect-azure/azure-ea-app-id.png"/> </div>
<i>Source: Microsoft</i>
</details>
4. Open the [_Role Assignments - Put_ article](https://learn.microsoft.com/en-us/rest/api/billing/role-assignments/put?view=rest-billing-2019-10-01-preview&tabs=HTTP) from the Microsoft documentation in a new tab.
5. Next to the _Create or update a billing role assignment_ step, click **Try It**.
<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure API role assignment sample call" width="100%" src="/img/connect-azure/azure-ea-role-assignment.png"/> </div>
<i>Source: Microsoft</i>
</details>
6. A login in screen is displayed on the right. Using your account credentials, log in to the tenant that you want to assign enrollment reader access.
7. An API request form is displayed. In the **Parameters** section add the following values:
- `billingAccountName`: Add the **billing account ID** you obtained in [step 3](/connecting_azure_ea#ea-step3).
- `billingRoleAssignmentName`: Generate a unique GUID using the [a GUID generator](https://guidgenerator.com/), as suggested by Microsoft.
- `api-version`: Use `2019-10-01-preview`.
8. In the **Body** section, copy and paste the request body below.
```json
{
"properties": {
"principalId": "<YOUR_OBJECT_ID>",
"principalTenantId": "<YOUR_TENANT_ID>",
"roleDefinitionId": "/providers/Microsoft.Billing/billingAccounts/<YOUR_BILLING_ACCOUNT_ID>/billingRoleDefinitions/24f8edb6-1668-4659-b5e2-40bb5f3a7d7e"
}
}
```

9. Update placeholders in the **Body** as follows:
- `principalId`: The **Object ID** you copied at the beginning of this section.
- `principalTenantId`: Your **Directory (tenant) ID** that you copied in [step 1](/connecting_azure_ea#ea-step1).
- `roleDefinitionId`: Replace `<YOUR_BILLING_ACCOUNT_ID>` with the **Billing account id** you copied in [step 3](/connecting_azure_ea#ea-step3).
- Note that `24f8edb6-1668-4659-b5e2-40bb5f3a7d7e` is the billing role definition ID for an [EnrollmentReader](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/assign-roles-azure-service-principals#permissions-that-can-be-assigned-to-the-service-principal).

<details><summary>Expand to view example image</summary>
<div>
<img alt="Azure API role assignment parameters filled in" width="100%" src="/img/connect-azure/azure-ea-run.png"/> </div>
<i>Source: Microsoft</i>
</details>

10. Click **Run**. You should see a `200 OK` response, indicating that the request was successful.
:::tip
If you receive an error, see the [Troubleshoot section](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/assign-roles-azure-service-principals#troubleshoot) of the Microsoft article these instructions were based on.
:::

## Step 5: Add App Registration Credentials to Vantage {#ea-step5}

1. Navigate to the [Integrations page](https://console.vantage.sh/settings/integrations) in the Vantage console, and add an Azure integration.
2. On the Azure integration page, click **Add Credentials**.
3. Add the following credentials:
- For **Azure AD Tenant ID**, add the **Directory (tenant) ID** you obtained in [step 1](/connecting_azure_ea#ea-step1).
- For **Service Principal App ID**, add the **Application (client) ID** you obtained in [step 1](/connecting_azure_ea#ea-step1).
- For **Service Principal Password**, add the client secret you obtained in [step 2](/connecting_azure_ea#ea-step2).
4. Click **Connect Account**.

Vantage will begin importing your Azure costs.

## Step 6: Send Your Billing Account ID to Vantage {#ea-step6}

Send the **Billing account id** you obtained in [step 3](/connecting_azure_ea#ea-step3) to [[email protected]](mailto:[email protected]) to complete the configuration. Indicate that you have set up an Azure integration and that you are a customer on an EA agreement.

## Next Steps: Workspace Access

See the [Workspace Access](/connecting_azure#workspace-access) section on the main _Connecting Azure_ page for information on how to assign this integration to one or more workspaces.
Loading

0 comments on commit a38412b

Please sign in to comment.