Azure
/
ipam
зеркало из https://github.com/Azure/ipam.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Updated docs and added skip ci message to workflow commit

This commit is contained in:
Matthew Garrett 2024-03-05 10:53:30 -08:00
Родитель 3cb86553ac
Коммит 63fed57dae
8 изменённых файлов: 105 добавлений и 86 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

2
.github/workflows/azure-ipam-build.yml поставляемый
Просмотреть файл

@ -101,7 +101,7 @@ jobs:
env:
prNumber: ${{ fromJson(steps.getPullRequestData.outputs.result).number }}
run: |
git commit -a -m "Updated Azure IPAM Version to v${{ steps.updateVersion.outputs.ipamVersion }}"
git commit -a -m "Updated Azure IPAM Version to v${{ steps.updateVersion.outputs.ipamVersion }} [skip ci]"
git push
release:

7
.vscode/settings.json поставляемый
Просмотреть файл

@ -7,5 +7,10 @@
"[javascript]": {
"editor.tabSize": 2
},
"editor.wordWrap": "off"
"editor.wordWrap": "off",
"markdownlint.config": {
"default": true,
"MD024": { "siblings_only": true },
"MD033": false
}
}

16
docs/README.md
Просмотреть файл

@ -1,4 +1,4 @@
# Welcome to Azure IPAM!
# Welcome to Azure IPAM
<!--
Guidelines on README format: https://review.docs.microsoft.com/help/onboard/admin/samples/concepts/readme-template?branch=master
@ -9,13 +9,15 @@ Taxonomies for products and languages: https://review.docs.microsoft.com/new-hop
-->
## Overview and Architecture
Azure IPAM was developed to give customers a simple, straightforward way to manage their IP address space in Azure. It enables end-to-end planning, deploying, managing and monitoring of your IP address space, with an intuitive user experience. Additionally, it can automatically discover IP address utilization within your Azure tenant and enables you to manage it all from a centralized UI. You can also interface with the Azure IPAM service programmatically via a RESTful API to facilitate IP address management at scale via Infrastructure as Code (IaC) and CI/CD pipelines. Azure IPAM is designed and architected based on the 5 pillars of the [Microsoft Azure Well Architected Framework](https://docs.microsoft.com/en-us/azure/architecture/framework/).
Azure IPAM was developed to give customers a simple, straightforward way to manage their IP address space in Azure. It enables end-to-end planning, deploying, managing and monitoring of your IP address space, with an intuitive user experience. Additionally, it can automatically discover IP address utilization within your Azure tenant and enables you to manage it all from a centralized UI. You can also interface with the Azure IPAM service programmatically via a RESTful API to facilitate IP address management at scale via Infrastructure as Code (IaC) and CI/CD pipelines. Azure IPAM is designed and architected based on the 5 pillars of the [Microsoft Azure Well Architected Framework](https://docs.microsoft.com/azure/architecture/framework/).
| App Service | Function |
:-----------------------------------------------------------------:|:---------------------------------------------------------------------------:
|-----------------------------------------------------------------:|:---------------------------------------------------------------------------|
| ![IPAM Architecture](./images/ipam_architecture_full.png ':size=70%') | ![IPAM Architecture](./images/ipam_architecture_function.png ':size=70%') |
## Azure IPAM Infrastructure
The Azure IPAM solution is delivered via a container running in Azure App Services or as an Azure Function. It can also be deployed in an API-only fashion if no UI is required (e.g. pure IaC model). The container is built and published to a public Azure Container Registry (ACR), but you may also choose to build your own container and host it in a Private Container Registry. More details on this can be found in the [Deployment](./deployment/README.md) section. All of the supporting infrastructure is deployed and runs within your Azure Tenant and none of the resources are shared with other IPAM users (outside of the publicly hosted ACR).
Here is a more specific breakdown of the components used:
@ -23,12 +25,12 @@ Here is a more specific breakdown of the components used:
- **App Registrations**
- 2x App Registrations
- *Engine* App Registration
- Granted **reader** permission to the [Root Management Group](https://learn.microsoft.com/en-us/azure/governance/management-groups/overview#root-management-group-for-each-directory) to facilitate IPAM Admin operations (global visibility)
- Authentication point for IPAM API operations ([on-behalf-of](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) flow)
- Granted **reader** permission to the [Root Management Group](https://learn.microsoft.com/azure/governance/management-groups/overview#root-management-group-for-each-directory) to facilitate IPAM Admin operations (global visibility)
- Authentication point for IPAM API operations ([on-behalf-of](https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) flow)
- *UI* App Registration *(Optional if no UI is desired)*
- Granted **read** permissions for Microsoft Graph API's
- Added as a *known client application* for the *Engine* App Registration
- Authentication point for the IPAM UI ([auth code](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow) flow)
- Authentication point for the IPAM UI ([auth code](https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow) flow)
- **Resource Group**
- Contains all Azure IPAM deployed resources
- **App Service Plan with App Service** *(AppContainer Deployment only)*
@ -68,7 +70,7 @@ Azure IPAM has been designed as such to radically simplify the often daunting ta
## User Interface
The front end is written in [React](https://reactjs.org/) and leverages the [Material UI](https://mui.com/) for the UI components. The UI handles AuthN/AuthZ with AzureAD via [MSAL](https://learn.microsoft.com/en-us/azure/active-directory/develop/msal-overview), and manages token acquisition & refresh for communication to the backend Engine API (on your behalf).
The front end is written in [React](https://reactjs.org/) and leverages the [Material UI](https://mui.com/) for the UI components. The UI handles AuthN/AuthZ with AzureAD via [MSAL](https://learn.microsoft.com/azure/active-directory/develop/msal-overview), and manages token acquisition & refresh for communication to the backend Engine API (on your behalf).
## Backend Engine

59
docs/api/README.md
Просмотреть файл

@ -1,61 +1,68 @@
## Azure IPAM REST API Overview
# Azure IPAM REST API Overview
You can interface with the full set of capabilities of Azure IPAM via a REST API. We use Swagger to define API documentation in OpenAPI v3 Specification format.
API docs can be found at the `/api/docs` path of your Azure IPAM website. Here you will find information on methods, parameters, and request body details for all available APIs.
![IPAM openapi specification](./images/openapispec.png)
![IPAM OpenAPI specification](./images/openapispec.png)
## How to Call the API
You can interface with the API like you would any other REST API. We'll be using [Postman](https://www.postman.com) and [Azure PowerShell](https://docs.microsoft.com/en-us/powershell/azure/what-is-azure-powershell) for our examples.
You can interface with the API like you would any other REST API. We'll be using [Postman](https://www.postman.com) and [Azure PowerShell](https://docs.microsoft.com/powershell/azure/what-is-azure-powershell) for our examples.
## Obtaining an Azure AD Token
First things first, you'll need to obtain an Azure AD token for authentication purposes. You can retrieve one via the Azure IPAM UI at anytime by selecting **Token** from the menu presented when clicking on your user avatar in the upper righthand corner.
![IPAM azure ad token](./images/token.png)
![IPAM Azure AD Token](./images/token.png)
You'll then be presented with a message notifying you that your token has been saved to your clipboard.
![IPAM azure ad token clipboard](./images/token_clipboard.png)
![IPAM Azure AD Token Clipboard](./images/token_clipboard.png)
You can also retrieve an Azure AD token from Azure IPAM via Azure PowerShell by using the [Get-AzAccessToken](https://docs.microsoft.com/en-us/powershell/module/az.accounts/get-azaccesstoken) commandlet. The token is retrieved from the API exposed via the backend engine application registration. This is the **ResourceUrl** you will be making the access token call against via Azure PowerShell.
You can also retrieve an Azure AD token from Azure IPAM via Azure PowerShell by using the [Get-AzAccessToken](https://docs.microsoft.com/powershell/module/az.accounts/get-azaccesstoken) commandlet. The token is retrieved from the API exposed via the backend engine application registration. This is the **ResourceUrl** you will be making the access token call against via Azure PowerShell.
![IPAM api resource url](./images/ipam_api_resource_url.png)
![IPAM API Resource URL](./images/ipam_api_resource_url.png)
```ps1
$accessToken = ConvertTo-SecureString (Get-AzAccessToken -ResourceUrl api://e3ff2k34-2271-58b5-9g2g-5004145608b3).Token -AsPlainText
````
```
## Sample API Calls
You'll need to provide the following for each API call:
* a bearer token
* the method
* the request URL
* any headers you'd like to pass
* the body of the request
Here is an example of how to create an IP address CIDR reservation in order to create a new VNET. We'll be performing a POST to the following request URL:
````
You'll need to provide the following for each API call:
* Bearer Token
* HTTP Method
* API Request URL
* HTTP Headers
* Request Body (PUT/PATCH/POST)
Here is an example of how to create an IP address CIDR reservation in order to create a new vNET. We'll be performing a POST to the following request URL:
```text
https://ipmadev.azurewebsites.net/api/spaces/TestSpace/blocks/TestBlock/reservations
````
```
The body contains a bit mask size of **/24**. Based on this, IPAM will provide the next available **/24** CIDR block available in the **TestBlock** found within our **TestSpace** (as denoted in our request URL).
![Postman CIDR reservation](./images/postman_body.png)
![Postman CIDR Reservation](./images/postman_body.png)
Be sure to provide the appropriate headers under the **Headers** tab.
![Postman CIDR reservation headers](./images/postman_headers.png)
![Postman CIDR Reservation Headers](./images/postman_headers.png)
Lastly, don't forget to provide your token information under the **Authorization** tab.
![Postman CIDR reservation authorization](./images/postman_authorization.png)
![Postman CIDR Reservation Authorization](./images/postman_authorization.png)
Click **Send** and you will recieve a response of type **201 Created** with key information regarding your CIDR block reservation request. Make note of the tag that is returned in the response. Tagging your newly created VNET with this key:value will automatically associate it with the **Block** the reservation was created from.
Click **Send** and you will receive a response of type **201 Created** with key information regarding your CIDR block reservation request. Make note of the tag that is returned in the response. Tagging your newly created vNET with this key:value will automatically associate it with the **Block** the reservation was created from.
![Postman CIDR reservation response](./images/postman_response.png)
![Postman CIDR Reservation Response](./images/postman_response.png)
Here is the same example performed via Azure PowerShell.
````ps1
```ps1
$engineClientId = '<Engine App Registration Client ID>'
$appName = 'ipamdev'
$space = 'TestSpace'
@ -81,11 +88,11 @@ $response = Invoke-RestMethod `
-Token $accessToken `
-Headers $headers `
-Body $body
````
```
The call will return key information regarding your CIDR block reservation. Again, make note of the *tag* information in the response.
````ps1
```ps1
$response
id : ABNsJjXXyTRDTRCdJEJThu
@ -94,6 +101,6 @@ userId : user@ipam.onmicrosoft.com
createdOn : 1662514052.26623
status : wait
tag : @{X-IPAM-RES-ID=ABNsJjXXyTRDTRCdJEJThu}
````
```
Take a look at our **Azure Landing Zone integration** example found under the `deploy` directory in the repository for a real work example of how to automate vNET creation by means of Bicep and leveraging the Azure IPAM API.

7
docs/contributing/README.md
Просмотреть файл

@ -2,7 +2,7 @@
This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
the rights to use your contribution. For details, visit [https://cla.opensource.microsoft.com](https://cla.opensource.microsoft.com).
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
@ -13,7 +13,8 @@ For more information see the [Code of Conduct FAQ](https://opensource.microsoft.
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
## Running an Azure IPAM Development Environment with Docker Compose
We have included a Docker Compose file in the root directory of the project (`docker-compose.yml`), to quickly build a fully functional Azure IPAM development environment. The Docker Compose file is also dependant on an `env` file to correctly pass all of the required environment variables into the containers. You can use the `env.example` file, also found at the root directory of the project, as a template to create your own `env` file.
We have included a Docker Compose file in the root directory of the project (`docker-compose.yml`), to quickly build a fully functional Azure IPAM development environment. The Docker Compose file is also dependant on an `env` file to correctly pass all of the required environment variables into the containers. You can use the `env.example` file, also found at the root directory of the project, as a template to create your own `env` file.
To start a development environment of the Azure IPAM solution via Docker Compose, run the following commands from the root directory of the project:
@ -29,6 +30,7 @@ docker compose rm -s -v -f
```
## Building Production Containers Images and Pushing them to DockerHub
We use Dockerfiles to build the containers for the Azure IPAM solution and have two located in the root directory of the project. One is designed for use when running inside a solution such as Azure App Services (as well as other containerized environments) and another specifically designed for running inside Azure Functions. If you choose, you can build these containers yourself and host them in DockerHub.
To do so, run the following Docker commands from the root directory of the project:
@ -44,6 +46,7 @@ docker push <Repository Name>/ipamfunc:latest
```
## Building & Updating Production Containers Images Using a Private ACR
In addition to the DockerHub option (above), alternatively you may choose to leverage an Azure Container Registry to host your Azure IPAM containers. Also, you may have selected the `-PrivateACR` flag during the deployment of your Azure IPAM environment, and from time to time you will need to update your containers as new code is released.
Before running the update commands, you'll need to authenticate to the Azure CLI

40
docs/deployment/README.md
Просмотреть файл

@ -6,20 +6,20 @@ To successfully deploy the solution, the following prerequisites must be met:
- An Azure Subscription (to deploy the solution into)
- The following Azure RBAC Roles:
- [Owner](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#owner) at the above mentioned Subscription scope
- One of the following roles at the [Root Management Group](https://learn.microsoft.com/en-us/azure/governance/management-groups/overview#root-management-group-for-each-directory) scope (needed to grant App Registrations and Managed Identity RBAC permissions):
- [Owner](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#owner)
- [User Access Administrator](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#user-access-administrator)
- [Custom Role](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles) with *allow* permissions of `Microsoft.Authorization/roleAssignments/write`
- [Global Administrator](https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#global-administrator) (needed to grant admin consent for the App Registration API permissions)
- [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner) at the above mentioned Subscription scope
- One of the following roles at the [Root Management Group](https://learn.microsoft.com/azure/governance/management-groups/overview#root-management-group-for-each-directory) scope (needed to grant App Registrations and Managed Identity RBAC permissions):
- [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner)
- [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator)
- [Custom Role](https://learn.microsoft.com/azure/role-based-access-control/custom-roles) with *allow* permissions of `Microsoft.Authorization/roleAssignments/write`
- [Global Administrator](https://learn.microsoft.com/azure/active-directory/roles/permissions-reference#global-administrator) (needed to grant admin consent for the App Registration API permissions)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed
- Required to clone the Azure IPAM GitHub repository
- [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) version 7.2.0 or later installed
- [Azure PowerShell](https://learn.microsoft.com/en-us/powershell/azure/install-az-ps) version 8.0.0 or later installed
- [Microsoft Graph PowerShell SDK](https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation) version 2.0.0 or later installed
- Required for *Full* or *Apps Only* deployments to grant [Admin Consent](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent) to the App Registrations
- [Bicep CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) version 0.21.1 or later installed
- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) version 2.35.0 or later installed (optional)
- [PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) version 7.2.0 or later installed
- [Azure PowerShell](https://learn.microsoft.com/powershell/azure/install-az-ps) version 8.0.0 or later installed
- [Microsoft Graph PowerShell SDK](https://learn.microsoft.com/powershell/microsoftgraph/installation) version 2.0.0 or later installed
- Required for *Full* or *Apps Only* deployments to grant [Admin Consent](https://learn.microsoft.com/azure/active-directory/manage-apps/grant-admin-consent) to the App Registrations
- [Bicep CLI](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install) version 0.21.1 or later installed
- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) version 2.35.0 or later installed (optional)
- Required only if you are building your own container image and pushing it to a private Azure Container Registry (Private ACR)
- [Docker (Linux)](https://docs.docker.com/engine/install/) / [Docker Desktop (Windows)](https://docs.docker.com/desktop/install/windows-install/) installed (optional)
- Required only if you are building your own container image and running it locally for development/testing purposes
@ -47,7 +47,7 @@ The two-part deployment option is provided in the event that a single team withi
## Authenticate to Azure PowerShell
Before executing the Azure IPAM deployment script, you'll need to authenticate to [Azure PowerShell](https://learn.microsoft.com/en-us/powershell/azure/install-az-ps) and set the context to the target subscription in which you'd like to deploy the solution.
Before executing the Azure IPAM deployment script, you'll need to authenticate to [Azure PowerShell](https://learn.microsoft.com/powershell/azure/install-az-ps) and set the context to the target subscription in which you'd like to deploy the solution.
### Connect to Azure PowerShell
@ -59,7 +59,7 @@ Connect-AzAccount
Connect-AzAccount -UseDeviceAuthentication
```
> **NOTE:** If you're connecting to an Azure Cloud besides Azure Public (such as Gov, China, etc.), you may need to specify the `-Environment` flag as described [here](https://learn.microsoft.com/en-us/powershell/azure/authenticate-azureps#sign-in-to-another-cloud) when using `Connect-AzAccount`
> **NOTE:** If you're connecting to an Azure Cloud besides Azure Public (such as Gov, China, etc.), you may need to specify the `-Environment` flag as described [here](https://learn.microsoft.com/powershell/azure/authenticate-azureps#sign-in-to-another-cloud) when using `Connect-AzAccount`
### Set the Active Subscription for Azure PowerShell
@ -74,11 +74,11 @@ Set-AzContext -Subscription "28b502e2-323f-4e57-98db-743459176557"
Set-AzContext -Subscription "Contoso IPAM Subscription"
```
For additional information on authenticating with Azure PowerShell, refer to the documentation [here](https://learn.microsoft.com/en-us/powershell/azure/authenticate-azureps)
For additional information on authenticating with Azure PowerShell, refer to the documentation [here](https://learn.microsoft.com/powershell/azure/authenticate-azureps)
## Authenticate to Azure CLI (Optional)
If you are using the `-PrivateACR` switch, you will need to be authenticated to the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) *in addition to* Azure PowerShell. This is because the deployment script will use the `az acr build` feature to build the application containers and push them into the private Azure Container Registry and the equivalent commands are current not available via Azure PowerShell.
If you are using the `-PrivateACR` switch, you will need to be authenticated to the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) *in addition to* Azure PowerShell. This is because the deployment script will use the `az acr build` feature to build the application containers and push them into the private Azure Container Registry and the equivalent commands are current not available via Azure PowerShell.
### Connect to Azure CLI
@ -103,7 +103,7 @@ az account set --subscription "28b502e2-323f-4e57-98db-743459176557"
az account set --subscription "Contoso IPAM Subscription"
```
For additional information on authenticating with Azure CLI, refer to the documentation [here](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli)
For additional information on authenticating with Azure CLI, refer to the documentation [here](https://learn.microsoft.com/cli/azure/authenticate-azure-cli)
## Clone the Github Repo
@ -142,7 +142,7 @@ You have the ability to pass optional flags to the deployment script:
> **NOTE 1:** The required values will vary based on the deployment type.
> **NOTE 2:** This must include ALL required resource names as shown below. Please review the [Naming Rules And Restrictions For Azure Resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) documentation to ensure your custom names are compliant and unique.
> **NOTE 2:** This must include ALL required resource names as shown below. Please review the [Naming Rules And Restrictions For Azure Resources](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-name-rules) documentation to ensure your custom names are compliant and unique.
> **NOTE 3:** Maximum of seven (7) characters. This is because the prefix is used to generate names for several different Azure resource types with varying maximum lengths.
@ -288,7 +288,7 @@ As part of the app registration deployment, a `main.parameters.json` file is gen
## Infrastructure Stack (Only) Deployment
To deploy infrastructure only, ensure you have the auto-generated `main.parameters.json` file created by the [App Registration Only](#app-registration-only-deployment) deployment in your `deploy` directory. Alternatively, you can generate your own using `main.parameters.example.json` as an example template.
To deploy infrastructure only, ensure you have the auto-generated `main.parameters.json` file created by the [App Registration Only](#azure-identities-only-deployment) deployment in your `deploy` directory. Alternatively, you can generate your own using `main.parameters.example.json` as an example template.
Once your parameters file is ready, run the following from within the `deploy` directory:
@ -310,7 +310,7 @@ You have the ability to pass optional flags to the deployment script:
> **NOTE 1:** The required values will vary based on the deployment type.
> **NOTE 2:** This must include ALL required resource names as shown below. Please review the [Naming Rules And Restrictions For Azure Resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) documentation to ensure your custom names are compliant and unique.
> **NOTE 2:** This must include ALL required resource names as shown below. Please review the [Naming Rules And Restrictions For Azure Resources](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-name-rules) documentation to ensure your custom names are compliant and unique.
> **NOTE 3:** Maximum of seven (7) characters. This is because the prefix is used to generate names for several different Azure resource types with varying maximum lengths.

4
docs/how-to/README.md
Просмотреть файл

@ -4,9 +4,9 @@
![IPAM Homepage](./images/home_page.png)
IPAM leverages the [Microsoft Authentication Library (MSAL)](https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-overview) in order to authenticate users. It uses your existing Azure AD credentials to authenticate you and leverages your existing Azure RBAC permissions to authorize what information is visible from within the IPAM tool.
IPAM leverages the [Microsoft Authentication Library (MSAL)](https://docs.microsoft.com/azure/active-directory/develop/msal-overview) in order to authenticate users. It uses your existing Azure AD credentials to authenticate you and leverages your existing Azure RBAC permissions to authorize what information is visible from within the IPAM tool.
IPAM has the concept of an **IPAM Administrator**. While using the IPAM tool as an administrator, you are viewing Azure resources through the permissions of the Engine Service Principal, which has [Reader](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#reader) at the [Tenant Root Management Group](https://learn.microsoft.com/en-us/azure/governance/management-groups/overview#root-management-group-for-each-directory) level. Upon initial deployment, no IPAM administrators are set which has the effect of **all** users having administrative rights. You can define who within your Azure AD Tenant should be designated as an IPAM administrator via the **Admin** section of the menu blade.
IPAM has the concept of an **IPAM Administrator**. While using the IPAM tool as an administrator, you are viewing Azure resources through the permissions of the Engine Service Principal, which has [Reader](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#reader) at the [Tenant Root Management Group](https://learn.microsoft.com/azure/governance/management-groups/overview#root-management-group-for-each-directory) level. Upon initial deployment, no IPAM administrators are set which has the effect of **all** users having administrative rights. You can define who within your Azure AD Tenant should be designated as an IPAM administrator via the **Admin** section of the menu blade.
![IPAM Admins](./images/ipam_admin_admins.png)

56
docs/troubleshooting/README.md
Просмотреть файл

@ -2,7 +2,7 @@
## New-AzRoleAssignment (Failed)
#### <u>Symptoms</u>
### <u>Symptoms</u>
During the deployment of Azure IPAM, you see an error similar to the following:
@ -16,9 +16,9 @@ HTTP 502 responses are visible for the "spaces/vnet/multi" calls in the Develope
![Access Denied Errors](./images/access_denied_not_enough_permission.png)
#### <u>Verify</u>
### <u>Verify</u>
You can check to see if you have the necessary permissions on the Tenant Root Group in the Azure Portal by navigating to [Management Groups](https://learn.microsoft.com/en-us/azure/governance/management-groups/overview)
You can check to see if you have the necessary permissions on the Tenant Root Group in the Azure Portal by navigating to [Management Groups](https://learn.microsoft.com/azure/governance/management-groups/overview)
If you cannot click on the *Tenant Root Group*, then you likely don't have access to the *Tenant Root Group* at all.
@ -30,23 +30,23 @@ Once you select the Tenant Root Group, under *Access Control (IAM)* you can clic
You can see from the above image, this user only has the `Reader` role, which isn't sufficient to deploy the Azure IPAM solution.
#### <u>Resolve</u>
### <u>Resolve</u>
Contact your Azure Administrator (or equivalent) to request a role which has `Microsoft.Authorization/roleAssignments/write` at the *Tenant Root Group* level.
This role could be one of the following:
- [Owner](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#owner)
- [User Access Administrator](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#user-access-administrator)
- [Custom Role](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles) with *allow* permissions of `Microsoft.Authorization/roleAssignments/write`
- [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner)
- [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator)
- [Custom Role](https://learn.microsoft.com/azure/role-based-access-control/custom-roles) with *allow* permissions of `Microsoft.Authorization/roleAssignments/write`
#### <u>Notes</u>
### <u>Notes</u>
You can read more about the requirements for deploying Azure IPAM in the [Prerequisites](/deployment/README?id=prerequisites) section of the deployment guide.
## New-MgOauth2PermissionGrant (Failed)
#### <u>Symptoms</u>
### <u>Symptoms</u>
During the deployment of Azure IPAM, you see an error similar to the following:
@ -56,34 +56,34 @@ When authenticating to Azure IPAM for the first time, you are presented with a *
![Permissions Requested](./images/permissions_requested.png)
#### <u>Verify</u>
### <u>Verify</u>
The role of [Global Administrator](https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#global-administrator) is required to deploy the Azure IPAM solution. This role is needed to [grant admin consent](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal) for the API permissions used by the Azure IPAM [App Registrations](https://learn.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals#application-registration).
The role of [Global Administrator](https://learn.microsoft.com/azure/active-directory/roles/permissions-reference#global-administrator) is required to deploy the Azure IPAM solution. This role is needed to [grant admin consent](https://learn.microsoft.com/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal) for the API permissions used by the Azure IPAM [App Registrations](https://learn.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals#application-registration).
Navigate to your user in Azure Active Directory and check your current [Role Assignments](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-users-assign-role-azure-portal).
Navigate to your user in Azure Active Directory and check your current [Role Assignments](https://learn.microsoft.com/azure/active-directory/fundamentals/active-directory-users-assign-role-azure-portal).
![Global Admin Missing](./images/global_admin_role_missing.png)
You can see from the image above that the [Global Administrator](https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#global-administrator) role is not present.
You can see from the image above that the [Global Administrator](https://learn.microsoft.com/azure/active-directory/roles/permissions-reference#global-administrator) role is not present.
#### <u>Resolve</u>
### <u>Resolve</u>
Contact your Azure Active Directory Administrator (or equivalent) to request the [Global Administrator](https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#global-administrator) role.
Contact your Azure Active Directory Administrator (or equivalent) to request the [Global Administrator](https://learn.microsoft.com/azure/active-directory/roles/permissions-reference#global-administrator) role.
Alternatively, if your organization (like many) has separate groups whom manage Azure Active Directory permissions and Azure infrastructure, you can leverage the two-step deployment method for Azure IPAM where a member of the [Global Administrators](https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#global-administrator) can deploy the required [App Registrations](https://learn.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals#application-registration), then pass the generated [Parameters](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/parameter-files) file to the Azure Infrastructure team to complete the deployment.
Alternatively, if your organization (like many) has separate groups whom manage Azure Active Directory permissions and Azure infrastructure, you can leverage the two-step deployment method for Azure IPAM where a member of the [Global Administrators](https://learn.microsoft.com/azure/active-directory/roles/permissions-reference#global-administrator) can deploy the required [App Registrations](https://learn.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals#application-registration), then pass the generated [Parameters](https://learn.microsoft.com/azure/azure-resource-manager/templates/parameter-files) file to the Azure Infrastructure team to complete the deployment.
Here are the steps from the [Deployment](/deployment/README) section:
1. [App Registration Only Deployment](/deployment/README?id=app-registration-only-deployment)
2. [Infrastructure Stack (Only) Deployment](/deployment/README?id=infrastructure-stack-only-deployment)
#### <u>Notes</u>
### <u>Notes</u>
You can read more about the requirements for deploying Azure IPAM in the [Prerequisites](/deployment/README?id=prerequisites) section of the deployment guide.
## DisableKeyBasedMetadataWriteAccess (Cosmos DB)
#### <u>Symptoms</u>
### <u>Symptoms</u>
- Spaces, Blocks, Virtual Networks, Subnets, and Endpoints fail to load
- HTTP 502 responses are visible for the "me" call in the Developer Tools networking view
@ -94,11 +94,11 @@ You can read more about the requirements for deploying Azure IPAM in the [Prereq
![Cosmos DB Not Allowed Though Endpoint](./images/cosmos_db_not_allowed.png)
#### <u>Verify</u>
### <u>Verify</u>
You can check to see if the flag `DisableKeyBasedMetadataWriteAccess` is set on your Cosmos DB resource by running one of the following commands:
**Azure PowerShell**
#### Azure PowerShell
```powershell
Get-AzCosmosDBAccount -ResourceGroupName <ResourceGroupName> -Name <CosmosDBAccountName>
@ -106,30 +106,32 @@ Get-AzCosmosDBAccount -ResourceGroupName <ResourceGroupName> -Name <CosmosDBAcco
![disableKeyBasedMetadataWriteAccess Azure PowerShell](./images/disableKeyBasedMetadataWriteAccess_powershell.png)
**Azure CLI**
#### Azure CLI
```bash
az cosmosdb show --resource-group <ResourceGroupName> --name <CosmosDBAccountName>
```
![disableKeyBasedMetadataWriteAccess Azure CLI](./images/disableKeyBasedMetadataWriteAccess_cli.png)
#### <u>Resolve</u>
### <u>Resolve</u>
Set the `DisableKeyBasedMetadataWriteAccess` flag to `false` using one of the following commands:
**Azure PowerShell**
#### Azure PowerShell
```powershell
Update-AzCosmosDBAccount -ResourceGroupName <ResourceGroupName> -Name <CosmosDBAccountName> -DisableKeyBasedMetadataWriteAccess $false
```
**Azure CLI**
#### Azure CLI
```bash
az cosmosdb update --resource-group <ResourceGroupName> --name <CosmosDBAccountName> --disable-key-based-metadata-write-access false
```
#### <u>Notes</u>
### <u>Notes</u>
This flag may have been set by [Azure Policy](https://learn.microsoft.com/en-us/azure/governance/policy/overview). You can find more details about this policy [here](https://learn.microsoft.com/en-us/azure/cosmos-db/policy-reference#azure-cosmos-db) under *Azure Cosmos DB key based metadata write access should be disabled*. You may need to contact your policy administrator to request an exception for Azure IPAM.
This flag may have been set by [Azure Policy](https://learn.microsoft.com/azure/governance/policy/overview). You can find more details about this policy [here](https://learn.microsoft.com/azure/cosmos-db/policy-reference#azure-cosmos-db) under *Azure Cosmos DB key based metadata write access should be disabled*. You may need to contact your policy administrator to request an exception for Azure IPAM.
Additionally this issue only applies to legacy deployments of Azure IPAM (prior to v3.0.0) as the latest versions use SQL [role-based access control](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-setup-rbac) to read/write data from Cosmos DB.
Additionally this issue only applies to legacy deployments of Azure IPAM (prior to v3.0.0) as the latest versions use SQL [role-based access control](https://learn.microsoft.com/azure/cosmos-db/how-to-setup-rbac) to read/write data from Cosmos DB.