Minor Fixes + New GET Reservations API

.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:

.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
+  }
 }

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,26 +9,28 @@ 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:
 
 - **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
 

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:
-````
+
+* 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    : [email protected]
 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.

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 [[email protected]](mailto:[email protected]) 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