From 57bb3d12c2ce884d46068862d31fa6cf473383b6 Mon Sep 17 00:00:00 2001 From: Paolo Salvatori Date: Wed, 22 Apr 2026 10:21:58 +0200 Subject: [PATCH 1/2] docs: add Azure Monitor Workbook article (DOC-186) --- src/content/docs/azure/services/workbook.mdx | 196 +++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 src/content/docs/azure/services/workbook.mdx diff --git a/src/content/docs/azure/services/workbook.mdx b/src/content/docs/azure/services/workbook.mdx new file mode 100644 index 00000000..b2fb193a --- /dev/null +++ b/src/content/docs/azure/services/workbook.mdx @@ -0,0 +1,196 @@ +--- +title: "Workbook" +description: Get started with Azure Monitor Workbooks on LocalStack +template: doc +--- + +import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage"; + +## Introduction + +Azure Monitor Workbooks are interactive reports that combine text, KQL queries, metrics, and visualizations into a single shareable document. +Workbook Templates allow organizations to share reusable workbook definitions across workspaces and resource groups. +They are commonly used to create operational dashboards, cost reports, and compliance summaries that surface data from multiple Azure Monitor sources. For more information, see [Azure Workbooks overview](https://learn.microsoft.com/en-us/azure/azure-monitor/visualize/workbooks-overview). + +LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Monitor Workbooks. +The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Workbooks' integration with LocalStack. + +## Getting started + +This guide walks you through creating a workbook and a workbook template. + +Launch LocalStack using your preferred method. For more information, see [Introduction to LocalStack for Azure](/azure/getting-started/). Once the container is running, enable Azure CLI interception by running: + +```bash +azlocal start-interception +``` + +This command points the `az` CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API. +To revert this configuration, run: + +```bash +azlocal stop-interception +``` + +This reconfigures the `az` CLI to send commands to the official Azure management REST API. + +### Create a resource group + +Create a resource group to hold all resources created in this guide: + +```bash +az group create --name rg-workbook-demo --location westeurope +``` + +```bash title="Output" +{ + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-workbook-demo", + "location": "westeurope", + "name": "rg-workbook-demo", + "properties": { "provisioningState": "Succeeded" }, + "type": "Microsoft.Resources/resourceGroups" +} +``` + +### Create a workbook + +Generate a UUID for the workbook name, then create a shared workbook: + +```bash +WORKBOOK_ID=$(python3 -c "import uuid; print(uuid.uuid4())") + +az monitor app-insights workbook create \ + --name "$WORKBOOK_ID" \ + --resource-group rg-workbook-demo \ + --display-name "My Workbook" \ + --kind shared \ + --category workbook \ + --serialized-data '{"version":"Notebook/1.0","items":[{"type":1,"content":{"json":"## My Workbook\nHello, world!"},"name":"text-0"}],"isLocked":false}' \ + --location westeurope +``` + +```bash title="Output" +{ + "category": "workbook", + "displayName": "My Workbook", + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-workbook-demo/providers/microsoft.insights/workbooks/de747180-ecea-4b97-bef4-f8376fc72abe", + "kind": "shared", + "location": "westeurope", + "name": "de747180-ecea-4b97-bef4-f8376fc72abe", + "resourceGroup": "rg-workbook-demo", + "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":{\"json\":\"## My Workbook\\nHello, world!\"},\"name\":\"text-0\"}],\"isLocked\":false}" +} +``` + +### List workbooks + +List all workbooks in the resource group filtered by category: + +```bash +az monitor app-insights workbook list \ + --resource-group rg-workbook-demo \ + --category workbook +``` + +```bash title="Output" +[ + { + "category": "workbook", + "displayName": "My Workbook", + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-workbook-demo/providers/microsoft.insights/workbooks/de747180-ecea-4b97-bef4-f8376fc72abe", + "kind": "shared", + "location": "westeurope", + "name": "de747180-ecea-4b97-bef4-f8376fc72abe", + "resourceGroup": "rg-workbook-demo", + "serializedData": "..." + } +] +``` + +### Create a workbook template + +Workbook templates do not have a dedicated Azure CLI subcommand. Use `az rest` pointed at the LocalStack resource manager endpoint: + +```bash +RM=$(az cloud show --query "endpoints.resourceManager" -o tsv | sed 's|/$||') + +az rest --method PUT \ + --url "${RM}/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-workbook-demo/providers/microsoft.insights/workbookTemplates/my-template?api-version=2020-11-20" \ + --body '{ + "location": "westeurope", + "properties": { + "priority": 1, + "author": "My Team", + "templateData": {}, + "galleries": [ + { + "name": "My Template", + "category": "General", + "type": "workbook", + "order": 100, + "resourceType": "Azure Monitor" + } + ] + } + }' +``` + +```bash title="Output" +{ + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-workbook-demo/providers/microsoft.insights/workbooktemplates/my-template", + "location": "westeurope", + "name": "my-template", + "properties": { + "author": "My Team", + "galleries": [ + { + "category": "General", + "name": "My Template", + "order": 100, + "resourceType": "Azure Monitor", + "type": "workbook" + } + ], + "priority": 1, + "templateData": {} + }, + "type": "microsoft.insights/workbooktemplates" +} +``` + +### Delete resources + +Delete the workbook and workbook template, then delete the resource group: + +```bash +az monitor app-insights workbook delete \ + --name "$WORKBOOK_ID" \ + --resource-group rg-workbook-demo \ + --yes + +az rest --method DELETE \ + --url "${RM}/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-workbook-demo/providers/microsoft.insights/workbookTemplates/my-template?api-version=2020-11-20" +``` + +## Features + +- **Workbook lifecycle:** Create, read, list, update, and delete workbooks. +- **Workbook template lifecycle:** Create, read, list, update, and delete workbook templates. +- **Shared and private workbooks:** Accept both `shared` and `user` kind values. +- **Category filtering:** List workbooks by category such as `workbook`, `sentinel`, or `vm-insights`. +- **Serialized data storage:** Store the full workbook JSON definition in the `serializedData` field. +- **Gallery configuration:** Define workbook templates with gallery metadata for easy discovery. + +## Limitations + +- **No rendering or query execution:** The workbook content is stored as a JSON string but KQL queries within the workbook are not executed. +- **No Azure Portal integration:** Workbooks cannot be previewed or rendered via LocalStack. +- **No linked resource validation:** Source ID references to Application Insights components or subscriptions are accepted but not validated. + +## Samples + +Explore end-to-end examples in the [LocalStack for Azure Samples](https://github.com/localstack/localstack-azure-samples) repository. + +## API Coverage + + From 3e187390016663a52d764595d669ab974c71e6ca Mon Sep 17 00:00:00 2001 From: Brian Rinaldi Date: Mon, 11 May 2026 14:03:12 -0400 Subject: [PATCH 2/2] Minor accuracy updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. **Category filtering** — The former “`sentinel` / `vm-insights`” examples do **not** match the [List By Resource Group](https://learn.microsoft.com/en-us/rest/api/application-insights/workbooks/list-by-resource-group) `CategoryType` enum or the [CLI `workbook list --category`](https://learn.microsoft.com/en-us/cli/azure/monitor/app-insights/workbook#az-monitor-app-insights-workbook-list) set (`workbook`, `TSG`, `performance`, `retention`). The Features section now describes that explicitly and distinguishes **list `category`** from **`properties.category`** at create time. 2. **`kind`: shared vs user** — The REST **Definitions** section documents both `user` and `shared`; the CLI `workbook create` generator only allows `shared`. The page now states both, with pointers to those docs (avoiding the old blanket “CLI accepts both” implication). 3. **Sample JSON for `az workbook`** — The extension flattens `properties` into the top level (`client_flatten=True` in Azure’s [`_create.py`](https://github.com/Azure/azure-cli-extensions/blob/main/src/application-insights/azext_applicationinsights/aaz/latest/monitor/app_insights/workbook/_create.py)), but the **`resourceGroup` field is not part of that schema**, so it was removed from the samples. **`type`** and canonical **`Microsoft.Insights/workbooks`** casing were added; resource IDs keep **`resourcegroups`** in the path where [Microsoft’s own REST samples](https://learn.microsoft.com/en-us/rest/api/application-insights/workbooks/list-by-resource-group) do. 4. **`--version "Notebook/1.0"`** — Added on create so the command matches Azure’s guidance that `properties.version` align with the Notebook schema inside `serializedData` ([WorkbookProperties](https://learn.microsoft.com/en-us/azure/templates/microsoft.insights/workbooks)). 5. **Workbook template body** — Replaced `templateData: {}` with a minimal `Notebook/1.0` + `items` payload so the example matches how Microsoft documents template payloads (non-empty workbook JSON object). 6. **Template sample response** — Adjusted `type` to **`Microsoft.Insights/workbookTemplates`** and echoed `templateData` in the sample so the illustration matches the request. 7. **Cleanup steps** — The text said to delete the resource group but the block did not; **`az group delete --name rg-workbook-demo --yes`** was added, plus a note to reuse the same shell for **`WORKBOOK_ID`** and **`RM`**. 8. **Intro** — Rephrased workbook templates as **ARM resources** and gallery-oriented publishing, instead of “across workspaces and resource groups,” which is easy to misread as Log Analytics **workspace** scope. --- src/content/docs/azure/services/workbook.mdx | 41 +++++++++++++------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/src/content/docs/azure/services/workbook.mdx b/src/content/docs/azure/services/workbook.mdx index b2fb193a..6457c29b 100644 --- a/src/content/docs/azure/services/workbook.mdx +++ b/src/content/docs/azure/services/workbook.mdx @@ -9,7 +9,7 @@ import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureF ## Introduction Azure Monitor Workbooks are interactive reports that combine text, KQL queries, metrics, and visualizations into a single shareable document. -Workbook Templates allow organizations to share reusable workbook definitions across workspaces and resource groups. +Workbook templates are Azure Resource Manager resources that package reusable definitions and gallery metadata so teams can publish templates to experiences such as Azure Monitor workbooks galleries. They are commonly used to create operational dashboards, cost reports, and compliance summaries that surface data from multiple Azure Monitor sources. For more information, see [Azure Workbooks overview](https://learn.microsoft.com/en-us/azure/azure-monitor/visualize/workbooks-overview). LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Monitor Workbooks. @@ -65,6 +65,7 @@ az monitor app-insights workbook create \ --display-name "My Workbook" \ --kind shared \ --category workbook \ + --version "Notebook/1.0" \ --serialized-data '{"version":"Notebook/1.0","items":[{"type":1,"content":{"json":"## My Workbook\nHello, world!"},"name":"text-0"}],"isLocked":false}' \ --location westeurope ``` @@ -73,12 +74,13 @@ az monitor app-insights workbook create \ { "category": "workbook", "displayName": "My Workbook", - "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-workbook-demo/providers/microsoft.insights/workbooks/de747180-ecea-4b97-bef4-f8376fc72abe", + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-workbook-demo/providers/Microsoft.Insights/workbooks/de747180-ecea-4b97-bef4-f8376fc72abe", "kind": "shared", "location": "westeurope", "name": "de747180-ecea-4b97-bef4-f8376fc72abe", - "resourceGroup": "rg-workbook-demo", - "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":{\"json\":\"## My Workbook\\nHello, world!\"},\"name\":\"text-0\"}],\"isLocked\":false}" + "serializedData": "{\"version\":\"Notebook/1.0\",\"items\":[{\"type\":1,\"content\":{\"json\":\"## My Workbook\\nHello, world!\"},\"name\":\"text-0\"}],\"isLocked\":false}", + "type": "Microsoft.Insights/workbooks", + "version": "Notebook/1.0" } ``` @@ -97,19 +99,20 @@ az monitor app-insights workbook list \ { "category": "workbook", "displayName": "My Workbook", - "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-workbook-demo/providers/microsoft.insights/workbooks/de747180-ecea-4b97-bef4-f8376fc72abe", + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg-workbook-demo/providers/Microsoft.Insights/workbooks/de747180-ecea-4b97-bef4-f8376fc72abe", "kind": "shared", "location": "westeurope", "name": "de747180-ecea-4b97-bef4-f8376fc72abe", - "resourceGroup": "rg-workbook-demo", - "serializedData": "..." + "serializedData": "...", + "type": "Microsoft.Insights/workbooks", + "version": "Notebook/1.0" } ] ``` ### Create a workbook template -Workbook templates do not have a dedicated Azure CLI subcommand. Use `az rest` pointed at the LocalStack resource manager endpoint: +Workbook templates are not exposed as a first-party `az monitor app-insights` command group. Use `az rest` against the resource manager endpoint (via your active cloud, which LocalStack updates when interception is enabled): ```bash RM=$(az cloud show --query "endpoints.resourceManager" -o tsv | sed 's|/$||') @@ -121,7 +124,10 @@ az rest --method PUT \ "properties": { "priority": 1, "author": "My Team", - "templateData": {}, + "templateData": { + "version": "Notebook/1.0", + "items": [] + }, "galleries": [ { "name": "My Template", @@ -137,7 +143,7 @@ az rest --method PUT \ ```bash title="Output" { - "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-workbook-demo/providers/microsoft.insights/workbooktemplates/my-template", + "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-workbook-demo/providers/Microsoft.Insights/workbookTemplates/my-template", "location": "westeurope", "name": "my-template", "properties": { @@ -152,15 +158,18 @@ az rest --method PUT \ } ], "priority": 1, - "templateData": {} + "templateData": { + "version": "Notebook/1.0", + "items": [] + } }, - "type": "microsoft.insights/workbooktemplates" + "type": "Microsoft.Insights/workbookTemplates" } ``` ### Delete resources -Delete the workbook and workbook template, then delete the resource group: +Delete the workbook and workbook template, then delete the resource group. Use the same shell session as earlier steps so `WORKBOOK_ID` and `RM` are still set. ```bash az monitor app-insights workbook delete \ @@ -170,14 +179,16 @@ az monitor app-insights workbook delete \ az rest --method DELETE \ --url "${RM}/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-workbook-demo/providers/microsoft.insights/workbookTemplates/my-template?api-version=2020-11-20" + +az group delete --name rg-workbook-demo --yes ``` ## Features - **Workbook lifecycle:** Create, read, list, update, and delete workbooks. - **Workbook template lifecycle:** Create, read, list, update, and delete workbook templates. -- **Shared and private workbooks:** Accept both `shared` and `user` kind values. -- **Category filtering:** List workbooks by category such as `workbook`, `sentinel`, or `vm-insights`. +- **Shared and private workbooks:** The [Workbooks REST API](https://learn.microsoft.com/en-us/rest/api/application-insights/workbooks/create-or-update) defines `kind` values `shared` and `user`. The Azure CLI `workbook create` command currently exposes only `--kind shared` (see [az monitor app-insights workbook create](https://learn.microsoft.com/en-us/cli/azure/monitor/app-insights/workbook#az-monitor-app-insights-workbook-create)). +- **Category filtering:** For [list by resource group](https://learn.microsoft.com/en-us/rest/api/application-insights/workbooks/list-by-resource-group), the `category` query parameter is one of `workbook`, `TSG`, `performance`, or `retention` (the same set the CLI accepts on `workbook list --category`). The `properties.category` value stored on a workbook resource is a separate string that you set at creation time. - **Serialized data storage:** Store the full workbook JSON definition in the `serializedData` field. - **Gallery configuration:** Define workbook templates with gallery metadata for easy discovery.