From 1f4de207a84542be3836f720dac20b9936961545 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Thu, 9 Oct 2025 19:21:55 +0100 Subject: [PATCH 01/40] docs: Add Azure multi-resource graph sync guide --- .../azure/multi-resource-graph.md | 548 ++++++++++++++++++ 1 file changed, 548 insertions(+) create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md new file mode 100644 index 0000000000..7aa6251deb --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -0,0 +1,548 @@ +--- +sidebar_position: 4 +--- + +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +import CredentialsGuide from "/docs/build-your-software-catalog/custom-integration/api/\_template_docs/\_find_credentials.mdx"; +import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" + +# Azure resource graph + +Azure resource graph integration ingests Azure resources into Port using Resource Graph Queries, enabling high-volume resource ingestion over large subscription. #AI! make this more better and more comprehensible + +- **No infrastructure required** - runs directly via GitHub Actions or locally +- **Multi-subscription support** - sync resources across all your Azure subscriptions from a single deployment +- **Near real-time updates** - incremental syncs every 15 minutes by default +- **Full control** - customize which resource types to include and how they're mapped +- **Zero setup complexity** - ideal for large organizations wanting near real-time data without complex infrastructure + +## Overview + +This solution: +- Is written in Python using the Azure SDK for Python. +- Runs as a GitHub workflow at configurable periodic intervals. +- Provides two sync modes: + - **Incremental**: Syncs recent changes (default: every 15 minutes). + - **Full**: Complete sync of all resources (recommended for initial setup). +- Prioritizes Azure resources with detailed tracking. +- Supports flexible data mapping through Port webhooks. +- Can be deployed via: + - GitHub Actions for automated periodic sync. + - Local installation for development and testing. + + +:::tip Source code +The source code is available in the [port-labs/incremental-sync](https://github.com/port-labs/incremental-sync) repository. +::: + +### Azure setup + +This integration requires the standard [Azure app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate%2Cexpose-a-web-api) setup. + +Keep the following credentials handy after setup: +- `AZURE_CLIENT_ID`: The client ID of the Azure service principal +- `AZURE_CLIENT_SECRET`: The client secret of the Azure service principal +- `AZURE_TENANT_ID`: The tenant ID of the Azure service principal + + + +### Port setup + +The basic Port setup follows the [standard installation guide](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/installation.md#port-setup). However, this integration uses a different webhook configuration for incremental syncing: + +#### Port credentials + + + +#### Blueprint configuration + +:::tip Customizable Blueprints +While these configurations are provided as a starting point, you can customize them based on your specific requirements and the Azure resources you want to track. +::: + +Create the following blueprints in Port before syncing: + +
+azureSubscription blueprint + +```json +{ + "identifier": "azureSubscription", + "title": "Azure Subscription", + "icon": "Azure", + "schema": { + "properties": { + "subscriptionId": { + "title": "Subscription ID", + "type": "string" + }, + "tags": { + "title": "Tags", + "type": "object" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} +} +``` +
+ +
+azureResourceGroup blueprint + +```json +{ + "identifier": "azureResourceGroup", + "description": "This blueprint represents an Azure Resource Group in our software catalog", + "title": "Azure Resource Group", + "icon": "Azure", + "schema": { + "properties": { + "location": { + "title": "Location", + "type": "string" + }, + "tags": { + "title": "Tags", + "type": "object" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "subscription": { + "title": "Subscription", + "target": "azureSubscription", + "required": false, + "many": false + } + } +} +``` +
+ +
+azureCloudResources blueprint + +```json +{ + "identifier": "azureCloudResources", + "description": "This blueprint represents an AzureCloud Resource in our software catalog", + "title": "Azure Cloud Resources", + "icon": "Git", + "schema": { + "properties": { + "tags": { + "title": "Tags", + "type": "object" + }, + "type": { + "title": "Type", + "type": "string" + }, + "location": { + "title": "Location", + "type": "string" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "resourceGroup": { + "title": "Resource Group", + "target": "azureResourceGroup", + "required": false, + "many": false + } + } +} +``` +
+ +#### Webhook configuration + +![Azure Basic Blueprints](../../../../../static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/create-webhook.png) + +To set up the webhook in Port: + +1. Navigate to the [Data sources](https://app.getport.io/dev-portal/data-sources) page. +2. Click `+ Data Source` and select `Webhook`. +3. Fill in the required fields and create the webhook. +4. Copy the webhook URL (you'll need this for the integration setup). +5. Click Next to go the `Mapping` section. +6. Scroll down to find the `Map the data from the external system into Port` section. + +![Map Data in Webhook](/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/map-data.png) + +Add the following webhook mapping in the `Map the data from the external system into Port` field: + +
+Webhook Mapping Configuration + +```json +[ + { + "blueprint": "azureCloudResources", + "operation": "create", + "filter": ".body.type == 'resource' and .body.operation == 'upsert'", + "entity": { + "identifier": ".body.data.resourceId | gsub(\" \";\"_\")", + "title": ".body.data.name", + "properties": { + "tags": ".body.data.tags", + "type": ".body.data.type", + "location": ".body.data.location" + }, + "relations": { + "resourceGroup": "'/subscriptions/' + .body.data.subscriptionId + '/resourcegroups/' + .body.data.resourceGroup | gsub(\" \";\"_\")" + } + } + }, + { + "blueprint": "azureCloudResources", + "operation": "delete", + "filter": ".body.type == 'resource' and .body.operation == 'delete'", + "entity": { + "identifier": ".body.data.resourceId | gsub(\" \";\"_\")" + } + }, + { + "blueprint": "azureResourceGroup", + "operation": "create", + "filter": ".body.data.type == 'microsoft.resources/subscriptions/resourcegroups' and .body.operation == 'upsert'", + "entity": { + "identifier": ".body.data.resourceId | gsub(\" \";\"_\")", + "title": ".body.data.name", + "properties": { + "tags": ".body.data.tags", + "location": ".body.data.location" + }, + "relations": { + "subscription": "'/subscriptions/' + .body.data.subscriptionId | gsub(\" \";\"_\")" + } + } + }, + { + "blueprint": "azureResourceGroup", + "operation": "delete", + "filter": ".body.data.type == 'microsoft.resources/subscriptions/resourcegroups' and .body.operation == 'delete'", + "entity": { + "identifier": ".body.data.resourceId | gsub(\" \";\"_\")" + } + }, + { + "blueprint": "azureSubscription", + "operation": "create", + "filter": ".body.data.type == 'microsoft.resources/subscriptions' and .body.operation == 'upsert'", + "entity": { + "identifier": ".body.data.resourceId | gsub(\" \";\"_\")", + "title": ".body.data.name", + "properties": { + "subscriptionId": ".body.data.subscriptionId", + "tags": ".body.data.tags" + } + } + }, + { + "blueprint": "azureSubscription", + "operation": "delete", + "filter": ".body.data.type == 'microsoft.resources/subscriptions' and .body.operation == 'delete'", + "entity": { + "identifier": ".body.data.resourceId | gsub(\" \";\"_\")" + } + } +] +``` + +:::note Webhook Mapping Details +- The `body.operation` field is a discriminator for the webhook (not part of Azure resource payload) +- The `body.type` field indicates the Azure resource type: + - `resource` for Azure resources + - `resourceContainer` for resource containers (e.g., resource groups, subscriptions) +- The `body.data` field contains the Azure resource payload +- The `body.data.type` field contains specific Azure resource types: + - `microsoft.resources/subscriptions/resourcegroups` for resource groups + - `microsoft.resources/subscriptions` for subscriptions + - `microsoft.network/networksecuritygroups` for network security groups +::: + +
+ +### Resource group tag filtering + +Filtering Azure resources by their parent resource group tags allows for precise, consistent, and efficient control over what gets synced to Port. + +:::info Why use Resource Group Tag Filtering? +Resource groups typically have consistent, organization-wide tags, making them ideal for filtering. This approach: +- Avoids the need to tag every individual resource. +- Provides a consistent filtering mechanism. +- Reduces sync time and data volume by filtering at the query level. +::: + +#### Enhanced configuration format + +You can specify both `include` and `exclude` tag filters in a single configuration object: + +```json +{ + "include": {"Environment": "Production", "Team": "Platform"}, + "exclude": {"Temporary": "true", "Stage": "deprecated"} +} +``` + +
+Configuration Examples + +```bash +# Include only Production resources: +export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production"}}' + +# Include Production, exclude temporary: +export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production"}, "exclude": {"Temporary": "true"}}' + +# Include Platform team, exclude Development: +export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Team": "Platform"}, "exclude": {"Environment": "Development"}}' + +# Exclude only (no include): +export RESOURCE_GROUP_TAG_FILTERS='{"exclude": {"Environment": "Development", "Stage": "staging"}}' + +# Complex multi-condition: +export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production", "Team": "Platform"}, "exclude": {"Temporary": "true", "Purpose": "testing"}}' +``` +
+ +#### Filter logic + +- **Include filters**: All conditions must match (AND logic). + - Example: `{ "Environment": "Production", "Team": "Platform" }` requires BOTH tags. +- **Exclude filters**: Any condition matching will exclude (OR logic). + - Example: `{ "Temporary": "true", "Stage": "deprecated" }` excludes if EITHER tag matches. +- **Combined**: Resources must match all include criteria AND NOT match any exclude criteria. +- **Defaults**: + - Empty `include` = include all (unless excluded). + - Empty `exclude` = exclude none. + +#### Tag matching rules + +- **Case-insensitive**: Tag keys and values are matched case-insensitively. +- **Exact value match**: Tag values must match exactly (after case normalization). +- **Missing tags**: Resource groups missing required include tags are filtered out. +- **Null/empty values**: Treated as non-matches. +- **Special characters**: Properly escaped in tag values. + +#### How filtering works + +1. **Query-level filtering**: Applied in Azure Resource Graph for optimal performance. +2. **Resource group join**: Resources are joined with their parent RGs to access tags. +3. **Tag inheritance**: Resource data includes both resource and RG tags (`rgTags` field). +4. **Dual application**: Filtering applies to both resources and containers. +5. **Mode support**: Works with both incremental and full sync. + +:::info Performance benefits +- Filtering occurs in Azure, reducing data transfer. +- Fewer API calls and faster syncs. +- Only relevant resources are processed and sent to Port. +::: + + +## Installation methods + + + + +To run the integration using GitHub Actions, follow these steps: + +1. Set up the following secrets in your GitHub repository: + - `AZURE_CLIENT_ID`: The Azure service principal client ID + - `AZURE_CLIENT_SECRET`: The Azure service principal client secret + - `AZURE_TENANT_ID`: The Azure service principal tenant ID + - `PORT_WEBHOOK_INGEST_URL`: The webhook URL for ingesting Azure resources into Port + +2. (Optional) Configure the following environment variables: + - `SUBSCRIPTION_BATCH_SIZE`: Number of subscriptions to sync per batch (default: 1000, max: 1000) + - `CHANGE_WINDOW_MINUTES`: Time window for checking resource changes (default: 15 minutes) + - `RESOURCE_TYPES`: Specific Azure resource types to sync (default: All) + ```bash + # Example for specific resource types: + RESOURCE_TYPES='["microsoft.keyvault/vaults","Microsoft.Network/virtualNetworks", "Microsoft.network/networksecuritygroups"]' + - `RESOURCE_GROUP_TAG_FILTERS`: Filter Azure resources by their parent resource group tags, [see examples above](#enhanced-configuration-format) + +3. Create a GitHub workflow file based on your sync requirements: + + + +This workflow runs automatically every 15 minutes to sync recent changes. + +Create `.github/workflows/azure-incremental-sync.yml`: + +```yaml +name: "Incremental sync of Azure resources to Port" +on: + schedule: + - cron: "*/15 * * * *" + +jobs: + sync: + name: Incremental sync + runs-on: ubuntu-latest + steps: + - name: Setup Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Checkout Repository + uses: actions/checkout@v2 + with: + ref: main + repository: port-labs/incremental-sync + + - name: Install dependencies with Poetry + run: | + cd integrations/azure_incremental + python -m pip install --upgrade pip + pip install poetry + make install + + - name: Run incremental sync + run: | + cd integrations/azure_incremental + make run + env: + AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }} + AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }} + AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }} + PORT_WEBHOOK_INGEST_URL: ${{ secrets.PORT_WEBHOOK_INGEST_URL }} + CHANGE_WINDOW_MINUTES: 15 + # Optional: Enhanced resource group tag filtering + # RESOURCE_GROUP_TAG_FILTERS: ${{ secrets.RESOURCE_GROUP_TAG_FILTERS }} +``` + + + + + +This workflow can be triggered manually from the GitHub Actions UI. + +:::warning +It's recommended to run the full sync manually as it may take a long time to complete, depending on the number of Azure resources, subscriptions, and resource groups. +::: + +Create `.github/workflows/azure-full-sync.yml`: + +```yaml +name: "Full sync of Azure resources to Port" +on: + workflow_dispatch: + +jobs: + sync: + name: Full sync + runs-on: ubuntu-latest + steps: + - name: Checkout Repository + uses: actions/checkout@v2 + with: + ref: main + repository: port-labs/incremental-sync + + - name: Install dependencies with Poetry + run: | + cd integrations/azure_incremental + python -m pip install --upgrade pip + pip install poetry + make install + + - name: Run full sync + run: | + cd integrations/azure_incremental + make run + env: + AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }} + AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }} + AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }} + PORT_WEBHOOK_INGEST_URL: ${{ secrets.PORT_WEBHOOK_INGEST_URL }} + SYNC_MODE: full + # Optional: Enhanced resource group tag filtering + # RESOURCE_GROUP_TAG_FILTERS: ${{ secrets.RESOURCE_GROUP_TAG_FILTERS }} +``` + + + + + + + + +To run the integration locally, follow these steps: + +1. Clone the repository: +```bash +git clone https://github.com/port-labs/incremental-sync.git +cd integrations/azure_incremental +``` + +2. Install dependencies using Poetry: +```bash +pip install poetry +make install +``` + +3. Set the required environment variables: +```bash +# Required variables +export AZURE_CLIENT_ID="your-azure-client-id" +export AZURE_CLIENT_SECRET="your-azure-client-secret" +export AZURE_TENANT_ID="your-azure-tenant-id" +export PORT_WEBHOOK_INGEST_URL="your-port-webhook-url" + +# Optional variables +export SUBSCRIPTION_BATCH_SIZE=1000 # Default: 1000 (max) +export CHANGE_WINDOW_MINUTES=15 # Default: 15 minutes +export RESOURCE_TYPES='["microsoft.keyvault/vaults","Microsoft.Network/virtualNetworks"]' # Default: All +export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production"}}' # By default, all resource groups are included unless you set filters. +``` + +4. Run the integration: +```bash +# For incremental sync +make run + +# For full sync +export SYNC_MODE=full +make run +``` + +:::tip +For development and testing purposes, you can use a smaller `CHANGE_WINDOW_MINUTES` value to sync changes more frequently. +::: + + + + + + + +## How it works + +The integration follows these steps: + +1. Fetches Azure subscriptions accessible to the Azure app. +2. Queries changes in Azure resources within these subscriptions. +3. Constructs and ingests resource groups into Port. +4. Processes resource changes (create/update/delete) according to webhook configuration. + +## Next Steps + +- Refer to the [Resource Templates](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/resource_templates/resource_templates.md) page for templates on how to map Azure resources to Port. From aff75f7f6f04750159cf5c83e304c45768f8294e Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Thu, 9 Oct 2025 19:21:58 +0100 Subject: [PATCH 02/40] docs: Improve clarity of Azure Resource Graph description --- .../cloud-providers/azure/multi-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index 7aa6251deb..baaabdd8ec 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -9,7 +9,7 @@ import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" # Azure resource graph -Azure resource graph integration ingests Azure resources into Port using Resource Graph Queries, enabling high-volume resource ingestion over large subscription. #AI! make this more better and more comprehensible +The Azure Resource Graph integration uses Azure Resource Graph queries to efficiently ingest resources into Port. This method is ideal for syncing a high volume of resources across multiple subscriptions. - **No infrastructure required** - runs directly via GitHub Actions or locally - **Multi-subscription support** - sync resources across all your Azure subscriptions from a single deployment From fe6173641b50fd1ba579317c92e4c151cffac9d6 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Thu, 9 Oct 2025 19:25:30 +0100 Subject: [PATCH 03/40] docs: Refine Azure Resource Graph integration benefits --- .../cloud-providers/azure/multi-resource-graph.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index baaabdd8ec..f177a4ad90 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -9,13 +9,11 @@ import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" # Azure resource graph -The Azure Resource Graph integration uses Azure Resource Graph queries to efficiently ingest resources into Port. This method is ideal for syncing a high volume of resources across multiple subscriptions. +The Azure Resource Graph integration uses Azure Resource Graph queries to efficiently ingest resources into Port. This method is ideal for syncing a high volume of resources across multiple subscriptions. The integration has these key benefits: #AI! improve this and the following list -- **No infrastructure required** - runs directly via GitHub Actions or locally - **Multi-subscription support** - sync resources across all your Azure subscriptions from a single deployment -- **Near real-time updates** - incremental syncs every 15 minutes by default +- **High performance** - Azure Resource Graph queries can execute and ingest resources from up to 1000 subscriptions at once - **Full control** - customize which resource types to include and how they're mapped -- **Zero setup complexity** - ideal for large organizations wanting near real-time data without complex infrastructure ## Overview From f9bcc032b0aded8d3158c843744e5f6eab0d6e1d Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Thu, 9 Oct 2025 19:25:32 +0100 Subject: [PATCH 04/40] docs: Improve intro and benefits for Azure Resource Graph integration --- .../cloud-providers/azure/multi-resource-graph.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index f177a4ad90..a2cc6e73e5 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -9,11 +9,11 @@ import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" # Azure resource graph -The Azure Resource Graph integration uses Azure Resource Graph queries to efficiently ingest resources into Port. This method is ideal for syncing a high volume of resources across multiple subscriptions. The integration has these key benefits: #AI! improve this and the following list +Sync your Azure environment to Port at scale using Azure Resource Graph. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: -- **Multi-subscription support** - sync resources across all your Azure subscriptions from a single deployment -- **High performance** - Azure Resource Graph queries can execute and ingest resources from up to 1000 subscriptions at once -- **Full control** - customize which resource types to include and how they're mapped +- **Centralized Syncing**: Ingest resources from all your Azure subscriptions with a single deployment. +- **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 1000 subscriptions simultaneously for maximum performance. +- **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. ## Overview From e0590085e43967b1f97e9396565dd6fc66629ed2 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Thu, 9 Oct 2025 19:49:03 +0100 Subject: [PATCH 05/40] docs: Add supported resources section for Azure multi-resource graph --- .../cloud-providers/azure/multi-resource-graph.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index a2cc6e73e5..8e20b44d02 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -29,10 +29,11 @@ This solution: - GitHub Actions for automated periodic sync. - Local installation for development and testing. +## Supported resources -:::tip Source code -The source code is available in the [port-labs/incremental-sync](https://github.com/port-labs/incremental-sync) repository. -::: +The integration currently supports the following Azure resource types from the resource graph: +- `Resources`: Complete bucket information including properties, tags, and metadata. +- `Resource containers`: Cluster details, services, and task definitions. ### Azure setup From 5dbd7233c3320ecbd64c91f8f1dc36041abff0aa Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Thu, 9 Oct 2025 19:49:06 +0100 Subject: [PATCH 06/40] fix: Correct Azure ARG supported resources table descriptions --- .../cloud-providers/azure/multi-resource-graph.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index 8e20b44d02..ee09d98ad1 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -31,9 +31,10 @@ This solution: ## Supported resources -The integration currently supports the following Azure resource types from the resource graph: -- `Resources`: Complete bucket information including properties, tags, and metadata. -- `Resource containers`: Cluster details, services, and task definitions. +The integration syncs data from two main Azure Resource Graph tables: + +- `Resources`: This table includes a wide array of Azure resources, such as virtual machines, storage accounts, network interfaces, and more. The integration syncs their properties, tags, and metadata. +- `ResourceContainers`: This table contains management groups, subscriptions, and resource groups, providing the hierarchical context for your Azure resources. ### Azure setup From 96cb54291dc6b69ee2626274c3e977c894b66a15 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Thu, 9 Oct 2025 20:08:54 +0100 Subject: [PATCH 07/40] docs: Refactor Azure Resource Graph to use Ocean framework config --- .../azure/multi-resource-graph.md | 537 ++---------------- 1 file changed, 51 insertions(+), 486 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index ee09d98ad1..389f803dd6 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -9,14 +9,14 @@ import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" # Azure resource graph -Sync your Azure environment to Port at scale using Azure Resource Graph. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: +Sync your Azure environment to Port at scale using Azure Resource Graph and Ocean framework. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: - **Centralized Syncing**: Ingest resources from all your Azure subscriptions with a single deployment. - **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 1000 subscriptions simultaneously for maximum performance. - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. ## Overview - +#AI! replace this overview with a better one This solution: - Is written in Python using the Azure SDK for Python. - Runs as a GitHub workflow at configurable periodic intervals. @@ -55,494 +55,59 @@ The basic Port setup follows the [standard installation guide](/build-your-softw -#### Blueprint configuration - -:::tip Customizable Blueprints -While these configurations are provided as a starting point, you can customize them based on your specific requirements and the Azure resources you want to track. -::: - -Create the following blueprints in Port before syncing: - -
-azureSubscription blueprint - -```json -{ - "identifier": "azureSubscription", - "title": "Azure Subscription", - "icon": "Azure", - "schema": { - "properties": { - "subscriptionId": { - "title": "Subscription ID", - "type": "string" - }, - "tags": { - "title": "Tags", - "type": "object" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": {} -} -``` -
- -
-azureResourceGroup blueprint - -```json -{ - "identifier": "azureResourceGroup", - "description": "This blueprint represents an Azure Resource Group in our software catalog", - "title": "Azure Resource Group", - "icon": "Azure", - "schema": { - "properties": { - "location": { - "title": "Location", - "type": "string" - }, - "tags": { - "title": "Tags", - "type": "object" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "subscription": { - "title": "Subscription", - "target": "azureSubscription", - "required": false, - "many": false - } - } -} -``` -
- -
-azureCloudResources blueprint - -```json -{ - "identifier": "azureCloudResources", - "description": "This blueprint represents an AzureCloud Resource in our software catalog", - "title": "Azure Cloud Resources", - "icon": "Git", - "schema": { - "properties": { - "tags": { - "title": "Tags", - "type": "object" - }, - "type": { - "title": "Type", - "type": "string" - }, - "location": { - "title": "Location", - "type": "string" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "resourceGroup": { - "title": "Resource Group", - "target": "azureResourceGroup", - "required": false, - "many": false - } - } -} -``` -
- -#### Webhook configuration - -![Azure Basic Blueprints](../../../../../static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/create-webhook.png) - -To set up the webhook in Port: - -1. Navigate to the [Data sources](https://app.getport.io/dev-portal/data-sources) page. -2. Click `+ Data Source` and select `Webhook`. -3. Fill in the required fields and create the webhook. -4. Copy the webhook URL (you'll need this for the integration setup). -5. Click Next to go the `Mapping` section. -6. Scroll down to find the `Map the data from the external system into Port` section. - -![Map Data in Webhook](/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/map-data.png) - -Add the following webhook mapping in the `Map the data from the external system into Port` field: +## Configuration -
-Webhook Mapping Configuration - -```json -[ - { - "blueprint": "azureCloudResources", - "operation": "create", - "filter": ".body.type == 'resource' and .body.operation == 'upsert'", - "entity": { - "identifier": ".body.data.resourceId | gsub(\" \";\"_\")", - "title": ".body.data.name", - "properties": { - "tags": ".body.data.tags", - "type": ".body.data.type", - "location": ".body.data.location" - }, - "relations": { - "resourceGroup": "'/subscriptions/' + .body.data.subscriptionId + '/resourcegroups/' + .body.data.resourceGroup | gsub(\" \";\"_\")" - } - } - }, - { - "blueprint": "azureCloudResources", - "operation": "delete", - "filter": ".body.type == 'resource' and .body.operation == 'delete'", - "entity": { - "identifier": ".body.data.resourceId | gsub(\" \";\"_\")" - } - }, - { - "blueprint": "azureResourceGroup", - "operation": "create", - "filter": ".body.data.type == 'microsoft.resources/subscriptions/resourcegroups' and .body.operation == 'upsert'", - "entity": { - "identifier": ".body.data.resourceId | gsub(\" \";\"_\")", - "title": ".body.data.name", - "properties": { - "tags": ".body.data.tags", - "location": ".body.data.location" - }, - "relations": { - "subscription": "'/subscriptions/' + .body.data.subscriptionId | gsub(\" \";\"_\")" - } - } - }, - { - "blueprint": "azureResourceGroup", - "operation": "delete", - "filter": ".body.data.type == 'microsoft.resources/subscriptions/resourcegroups' and .body.operation == 'delete'", - "entity": { - "identifier": ".body.data.resourceId | gsub(\" \";\"_\")" - } - }, - { - "blueprint": "azureSubscription", - "operation": "create", - "filter": ".body.data.type == 'microsoft.resources/subscriptions' and .body.operation == 'upsert'", - "entity": { - "identifier": ".body.data.resourceId | gsub(\" \";\"_\")", - "title": ".body.data.name", - "properties": { - "subscriptionId": ".body.data.subscriptionId", - "tags": ".body.data.tags" - } - } - }, - { - "blueprint": "azureSubscription", - "operation": "delete", - "filter": ".body.data.type == 'microsoft.resources/subscriptions' and .body.operation == 'delete'", - "entity": { - "identifier": ".body.data.resourceId | gsub(\" \";\"_\")" - } - } -] -``` - -:::note Webhook Mapping Details -- The `body.operation` field is a discriminator for the webhook (not part of Azure resource payload) -- The `body.type` field indicates the Azure resource type: - - `resource` for Azure resources - - `resourceContainer` for resource containers (e.g., resource groups, subscriptions) -- The `body.data` field contains the Azure resource payload -- The `body.data.type` field contains specific Azure resource types: - - `microsoft.resources/subscriptions/resourcegroups` for resource groups - - `microsoft.resources/subscriptions` for subscriptions - - `microsoft.network/networksecuritygroups` for network security groups -::: - -
- -### Resource group tag filtering +Port integrations use a [YAML mapping block](/build-your-software-catalog/customize-integrations/configure-mapping#configuration-structure) to ingest data from the third-party api into Port. -Filtering Azure resources by their parent resource group tags allows for precise, consistent, and efficient control over what gets synced to Port. +The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API. -:::info Why use Resource Group Tag Filtering? -Resource groups typically have consistent, organization-wide tags, making them ideal for filtering. This approach: -- Avoids the need to tag every individual resource. -- Provides a consistent filtering mechanism. -- Reduces sync time and data volume by filtering at the query level. -::: +### Default mapping configuration -#### Enhanced configuration format - -You can specify both `include` and `exclude` tag filters in a single configuration object: - -```json -{ - "include": {"Environment": "Production", "Team": "Platform"}, - "exclude": {"Temporary": "true", "Stage": "deprecated"} -} -``` +This is the default mapping configuration you get after installing the Azure integration.
-Configuration Examples - -```bash -# Include only Production resources: -export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production"}}' - -# Include Production, exclude temporary: -export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production"}, "exclude": {"Temporary": "true"}}' - -# Include Platform team, exclude Development: -export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Team": "Platform"}, "exclude": {"Environment": "Development"}}' - -# Exclude only (no include): -export RESOURCE_GROUP_TAG_FILTERS='{"exclude": {"Environment": "Development", "Stage": "staging"}}' - -# Complex multi-condition: -export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production", "Team": "Platform"}, "exclude": {"Temporary": "true", "Purpose": "testing"}}' -``` +Default mapping configuration (Click to expand) + + ```yaml showLineNumbers +resources: + - kind: resource + selector: + query: 'true' + port: + entity: + mappings: + identifier: '.id | gsub(" ";"_")' + title: .name + blueprint: '"azureCloudResources"' + properties: + tags: .tags + type: .type + location: .location + - kind: resourceContainer + selector: + query: .type == "microsoft.resources/subscriptions" + port: + entity: + mappings: + identifier: '.id | gsub(" ";"_")' + title: .name + blueprint: '"azureSubscription"' + properties: + subscriptionId: .subscriptionId + location: .location + - kind: resourceContainer + selector: + query: .type == "microsoft.resources/subscriptions/resourcegroups" + port: + entity: + mappings: + identifier: '.id | gsub(" ";"_")' + title: .name + blueprint: '"azureResourceGroup"' + properties: + tags: .tags + location: .location + relations: + subscription: '("/subscriptions/" + .subscriptionId) | gsub(" ";"_")' + ```
- -#### Filter logic - -- **Include filters**: All conditions must match (AND logic). - - Example: `{ "Environment": "Production", "Team": "Platform" }` requires BOTH tags. -- **Exclude filters**: Any condition matching will exclude (OR logic). - - Example: `{ "Temporary": "true", "Stage": "deprecated" }` excludes if EITHER tag matches. -- **Combined**: Resources must match all include criteria AND NOT match any exclude criteria. -- **Defaults**: - - Empty `include` = include all (unless excluded). - - Empty `exclude` = exclude none. - -#### Tag matching rules - -- **Case-insensitive**: Tag keys and values are matched case-insensitively. -- **Exact value match**: Tag values must match exactly (after case normalization). -- **Missing tags**: Resource groups missing required include tags are filtered out. -- **Null/empty values**: Treated as non-matches. -- **Special characters**: Properly escaped in tag values. - -#### How filtering works - -1. **Query-level filtering**: Applied in Azure Resource Graph for optimal performance. -2. **Resource group join**: Resources are joined with their parent RGs to access tags. -3. **Tag inheritance**: Resource data includes both resource and RG tags (`rgTags` field). -4. **Dual application**: Filtering applies to both resources and containers. -5. **Mode support**: Works with both incremental and full sync. - -:::info Performance benefits -- Filtering occurs in Azure, reducing data transfer. -- Fewer API calls and faster syncs. -- Only relevant resources are processed and sent to Port. -::: - - -## Installation methods - - - - -To run the integration using GitHub Actions, follow these steps: - -1. Set up the following secrets in your GitHub repository: - - `AZURE_CLIENT_ID`: The Azure service principal client ID - - `AZURE_CLIENT_SECRET`: The Azure service principal client secret - - `AZURE_TENANT_ID`: The Azure service principal tenant ID - - `PORT_WEBHOOK_INGEST_URL`: The webhook URL for ingesting Azure resources into Port - -2. (Optional) Configure the following environment variables: - - `SUBSCRIPTION_BATCH_SIZE`: Number of subscriptions to sync per batch (default: 1000, max: 1000) - - `CHANGE_WINDOW_MINUTES`: Time window for checking resource changes (default: 15 minutes) - - `RESOURCE_TYPES`: Specific Azure resource types to sync (default: All) - ```bash - # Example for specific resource types: - RESOURCE_TYPES='["microsoft.keyvault/vaults","Microsoft.Network/virtualNetworks", "Microsoft.network/networksecuritygroups"]' - - `RESOURCE_GROUP_TAG_FILTERS`: Filter Azure resources by their parent resource group tags, [see examples above](#enhanced-configuration-format) - -3. Create a GitHub workflow file based on your sync requirements: - - - -This workflow runs automatically every 15 minutes to sync recent changes. - -Create `.github/workflows/azure-incremental-sync.yml`: - -```yaml -name: "Incremental sync of Azure resources to Port" -on: - schedule: - - cron: "*/15 * * * *" - -jobs: - sync: - name: Incremental sync - runs-on: ubuntu-latest - steps: - - name: Setup Python 3.12 - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - - name: Checkout Repository - uses: actions/checkout@v2 - with: - ref: main - repository: port-labs/incremental-sync - - - name: Install dependencies with Poetry - run: | - cd integrations/azure_incremental - python -m pip install --upgrade pip - pip install poetry - make install - - - name: Run incremental sync - run: | - cd integrations/azure_incremental - make run - env: - AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }} - AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }} - AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }} - PORT_WEBHOOK_INGEST_URL: ${{ secrets.PORT_WEBHOOK_INGEST_URL }} - CHANGE_WINDOW_MINUTES: 15 - # Optional: Enhanced resource group tag filtering - # RESOURCE_GROUP_TAG_FILTERS: ${{ secrets.RESOURCE_GROUP_TAG_FILTERS }} -``` - - - - - -This workflow can be triggered manually from the GitHub Actions UI. - -:::warning -It's recommended to run the full sync manually as it may take a long time to complete, depending on the number of Azure resources, subscriptions, and resource groups. -::: - -Create `.github/workflows/azure-full-sync.yml`: - -```yaml -name: "Full sync of Azure resources to Port" -on: - workflow_dispatch: - -jobs: - sync: - name: Full sync - runs-on: ubuntu-latest - steps: - - name: Checkout Repository - uses: actions/checkout@v2 - with: - ref: main - repository: port-labs/incremental-sync - - - name: Install dependencies with Poetry - run: | - cd integrations/azure_incremental - python -m pip install --upgrade pip - pip install poetry - make install - - - name: Run full sync - run: | - cd integrations/azure_incremental - make run - env: - AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }} - AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }} - AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }} - PORT_WEBHOOK_INGEST_URL: ${{ secrets.PORT_WEBHOOK_INGEST_URL }} - SYNC_MODE: full - # Optional: Enhanced resource group tag filtering - # RESOURCE_GROUP_TAG_FILTERS: ${{ secrets.RESOURCE_GROUP_TAG_FILTERS }} -``` - - - - - - - - -To run the integration locally, follow these steps: - -1. Clone the repository: -```bash -git clone https://github.com/port-labs/incremental-sync.git -cd integrations/azure_incremental -``` - -2. Install dependencies using Poetry: -```bash -pip install poetry -make install -``` - -3. Set the required environment variables: -```bash -# Required variables -export AZURE_CLIENT_ID="your-azure-client-id" -export AZURE_CLIENT_SECRET="your-azure-client-secret" -export AZURE_TENANT_ID="your-azure-tenant-id" -export PORT_WEBHOOK_INGEST_URL="your-port-webhook-url" - -# Optional variables -export SUBSCRIPTION_BATCH_SIZE=1000 # Default: 1000 (max) -export CHANGE_WINDOW_MINUTES=15 # Default: 15 minutes -export RESOURCE_TYPES='["microsoft.keyvault/vaults","Microsoft.Network/virtualNetworks"]' # Default: All -export RESOURCE_GROUP_TAG_FILTERS='{"include": {"Environment": "Production"}}' # By default, all resource groups are included unless you set filters. -``` - -4. Run the integration: -```bash -# For incremental sync -make run - -# For full sync -export SYNC_MODE=full -make run -``` - -:::tip -For development and testing purposes, you can use a smaller `CHANGE_WINDOW_MINUTES` value to sync changes more frequently. -::: - - - - - - - -## How it works - -The integration follows these steps: - -1. Fetches Azure subscriptions accessible to the Azure app. -2. Queries changes in Azure resources within these subscriptions. -3. Constructs and ingests resource groups into Port. -4. Processes resource changes (create/update/delete) according to webhook configuration. - -## Next Steps - -- Refer to the [Resource Templates](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/resource_templates/resource_templates.md) page for templates on how to map Azure resources to Port. From 02f963b03c12f42f271f568ed80ca0a1bfbf966d Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Thu, 9 Oct 2025 20:08:58 +0100 Subject: [PATCH 08/40] docs: Improve Azure multi-resource graph overview section --- .../azure/multi-resource-graph.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index 389f803dd6..a5c15e2d7e 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -16,18 +16,12 @@ Sync your Azure environment to Port at scale using Azure Resource Graph and Ocea - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. ## Overview -#AI! replace this overview with a better one -This solution: -- Is written in Python using the Azure SDK for Python. -- Runs as a GitHub workflow at configurable periodic intervals. -- Provides two sync modes: - - **Incremental**: Syncs recent changes (default: every 15 minutes). - - **Full**: Complete sync of all resources (recommended for initial setup). -- Prioritizes Azure resources with detailed tracking. -- Supports flexible data mapping through Port webhooks. -- Can be deployed via: - - GitHub Actions for automated periodic sync. - - Local installation for development and testing. + +This integration provides a robust solution for syncing your Azure resources to Port, built with Python and the Azure SDK. It is designed to run seamlessly as a GitHub workflow, executing at configurable intervals to keep your software catalog up-to-date. + +The integration offers two synchronization modes: an **incremental** sync that captures recent changes (running by default every 15 minutes) and a **full** sync for a complete ingestion of all resources, which is ideal for the initial setup. With detailed tracking of Azure resources and flexible data mapping powered by Port's webhook capabilities, you can customize the ingested data to fit your needs. + +You can deploy the integration using GitHub Actions for automated, periodic synchronization, or run it locally for development and testing purposes. ## Supported resources From ad51c4f322ad163da96d4ffdc34686650f6fa147 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Thu, 9 Oct 2025 20:11:56 +0100 Subject: [PATCH 09/40] docs: Update Azure multi-resource-graph overview content --- .../azure/multi-resource-graph.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index a5c15e2d7e..b93107e1d9 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -16,12 +16,18 @@ Sync your Azure environment to Port at scale using Azure Resource Graph and Ocea - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. ## Overview - -This integration provides a robust solution for syncing your Azure resources to Port, built with Python and the Azure SDK. It is designed to run seamlessly as a GitHub workflow, executing at configurable intervals to keep your software catalog up-to-date. - -The integration offers two synchronization modes: an **incremental** sync that captures recent changes (running by default every 15 minutes) and a **full** sync for a complete ingestion of all resources, which is ideal for the initial setup. With detailed tracking of Azure resources and flexible data mapping powered by Port's webhook capabilities, you can customize the ingested data to fit your needs. - -You can deploy the integration using GitHub Actions for automated, periodic synchronization, or run it locally for development and testing purposes. +#AI! replace this overview with a better one. The integration I'm building here is not incremental and it does not run as a Github action, instead it is built with Ocean framework - ocean.port.io. +This solution: +- Is written in Python using the Azure SDK for Python. +- Runs as a GitHub workflow at configurable periodic intervals. +- Provides two sync modes: + - **Incremental**: Syncs recent changes (default: every 15 minutes). + - **Full**: Complete sync of all resources (recommended for initial setup). +- Prioritizes Azure resources with detailed tracking. +- Supports flexible data mapping through Port webhooks. +- Can be deployed via: + - GitHub Actions for automated periodic sync. + - Local installation for development and testing. ## Supported resources From 633e1a4cbcae08270c3a4b426b81e2dbd09f69b1 Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Thu, 9 Oct 2025 20:12:00 +0100 Subject: [PATCH 10/40] docs: Update Azure Resource Graph overview for Ocean framework --- .../azure/multi-resource-graph.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md index b93107e1d9..5fae4ae72b 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md @@ -16,18 +16,12 @@ Sync your Azure environment to Port at scale using Azure Resource Graph and Ocea - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. ## Overview -#AI! replace this overview with a better one. The integration I'm building here is not incremental and it does not run as a Github action, instead it is built with Ocean framework - ocean.port.io. -This solution: -- Is written in Python using the Azure SDK for Python. -- Runs as a GitHub workflow at configurable periodic intervals. -- Provides two sync modes: - - **Incremental**: Syncs recent changes (default: every 15 minutes). - - **Full**: Complete sync of all resources (recommended for initial setup). -- Prioritizes Azure resources with detailed tracking. -- Supports flexible data mapping through Port webhooks. -- Can be deployed via: - - GitHub Actions for automated periodic sync. - - Local installation for development and testing. + +This integration is built on Port's open-source [Ocean framework](https://ocean.port.io), providing a robust solution for syncing your Azure resources to Port. It is written in Python and utilizes the Azure SDK to query the Azure Resource Graph API. + +The integration performs a full synchronization of your Azure resources on each run, ensuring that your software catalog accurately reflects the current state of your environment. With flexible data mapping capabilities, you can customize how the ingested data is structured and related within Port. + +You can deploy the integration in any environment that supports Python, including Kubernetes, Docker, or a local machine, giving you full control over its execution and scheduling. ## Supported resources From 34ac85bbd5a7ecc6bf69b7dbd6547583a8f6c6fe Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 13:15:59 +0100 Subject: [PATCH 11/40] docs: Add Azure Resource Graph sync documentation --- .../azure/azure-resource-graph.md | 706 ++++++++++++++++++ 1 file changed, 706 insertions(+) create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md new file mode 100644 index 0000000000..3fe0321b6f --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -0,0 +1,706 @@ +--- +sidebar_position: 5 +--- + +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +import CredentialsGuide from "/docs/build-your-software-catalog/custom-integration/api/\_template_docs/\_find_credentials.mdx"; +import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" +import DockerParameters from "./\_azure_docker_params.mdx" +import IntegrationVersion from "/src/components/IntegrationVersion/IntegrationVersion" +import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md" + +# Azure resource graph + +Sync your Azure environment to Port at scale using Azure Resource Graph and Ocean framework. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: + +- **Centralized Syncing**: Ingest resources from all your Azure subscriptions with a single deployment. +- **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 1000 subscriptions simultaneously for maximum performance. +- **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. + +## Overview + +This integration is built on Port's open-source [Ocean framework](https://ocean.port.io), providing a robust solution for syncing your Azure resources to Port. It is written in Python and utilizes the Azure SDK to query the Azure Resource Graph API. + +The integration performs a full synchronization of your Azure resources on each run, ensuring that your software catalog accurately reflects the current state of your environment. With flexible data mapping capabilities, you can customize how the ingested data is structured and related within Port. + +You can deploy the integration in any environment that supports Python, including Kubernetes, Docker, or a local machine, giving you full control over its execution and scheduling. + +## Supported resources + +The integration syncs data from two main Azure Resource Graph tables: + +- `Resources`: This table includes a wide array of Azure resources, such as virtual machines, storage accounts, network interfaces, and more. The integration syncs their properties, tags, and metadata. +- `ResourceContainers`: This table contains management groups, subscriptions, and resource groups, providing the hierarchical context for your Azure resources. + +## Configuration + +Port integrations use a [YAML mapping block](/build-your-software-catalog/customize-integrations/configure-mapping#configuration-structure) to ingest data from the third-party api into Port. + +The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API. + +### Default mapping configuration + +This is the default mapping configuration you get after installing the Azure integration. + +
+Default mapping configuration (Click to expand) + + ```yaml showLineNumbers +resources: + - kind: resource + selector: + query: 'true' + port: + entity: + mappings: + identifier: '.id | gsub(" ";"_")' + title: .name + blueprint: '"azureCloudResources"' + properties: + tags: .tags + type: .type + location: .location + - kind: resourceContainer + selector: + query: .type == "microsoft.resources/subscriptions" + port: + entity: + mappings: + identifier: '.id | gsub(" ";"_")' + title: .name + blueprint: '"azureSubscription"' + properties: + subscriptionId: .subscriptionId + location: .location + - kind: resourceContainer + selector: + query: .type == "microsoft.resources/subscriptions/resourcegroups" + port: + entity: + mappings: + identifier: '.id | gsub(" ";"_")' + title: .name + blueprint: '"azureResourceGroup"' + properties: + tags: .tags + location: .location + relations: + subscription: '("/subscriptions/" + .subscriptionId) | gsub(" ";"_")' + ``` +
+ +## installation + + + + + +The Azure resource graph exporter is deployed using helm on kubernetes. + +This way of deployment supports scheduled resyncs of resources from Azure to Port. + +

Prerequisites

+- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- [Helm](https://helm.sh/docs/intro/install/) >= 3.0.0 +- [Azure App Registration Credentials](See below) + + + +

Installation

+ + + +Now that you have the Azure App Registration details, you can install the Azure exporter using Helm. + +You should have the following information ready: + +- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). + - `PORT_CLIENT_ID` + - `PORT_CLIENT_SECRET` +- Azure Credentials: + - `AZURE_CLIENT_ID`: The Application (client) ID from the Azure App Registration. + - `AZURE_CLIENT_SECRET`: The Application (client) Secret from the Azure App Registration. + - `AZURE_TENANT_ID`: The Directory (tenant) ID from the Azure App Registration. + +```bash showLineNumbers +helm repo add --force-update port-labs https://port-labs.github.io/helm-charts +helm upgrade --install azure port-labs/port-ocean \ + --set port.clientId="PORT_CLIENT_ID" \ + --set port.clientSecret="PORT_CLIENT_SECRET" \ + --set port.baseUrl="https://api.getport.io" \ + --set initializePortResources=true \ + --set sendRawDataExamples=true \ + --set scheduledResyncInterval=1440 \ + --set integration.type="azure-rg" \ + --set integration.identifier="azure-resource-graph" \ + --set integration.eventListener.type="POLLING" \ + --set integration.config.azureClientId="" \ + --set integration.config.azureClientSecret="" \ + --set integration.config.azureTenantId="" +``` + + + + + + + + + + + +The Azure exporter is deployed using Azure DevOps pipline, which supports scheduled resyncs of resources from Azure to Port. + +

Prerequisites

+ +- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- Access to an Azure DevOps project with permission to configure pipelines and secrets. +- Azure App Registration Credentials (See below) + + + +

Installation

+ +Now that you have the Azure App Registration details, you can set up the Azure exporter using an Azure DevOps pipeline. + +Make sure to configure the following [seceret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables?view=azure-devops&tabs=yaml%2Cbash) in a variable group: + +- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). + - `PORT_CLIENT_ID` + - `PORT_CLIENT_SECRET` +- Azure Credentials: + - `OCEAN__SECRET__AZURE_CLIENT_ID`: The Application (client) ID from the Azure App Registration. + - `OCEAN__SECRET__AZURE_CLIENT_SECRET`: The Application (client) Secret from the Azure App Registration. + - `OCEAN__SECRET__AZURE_TENANT_ID`: The Directory (tenant) ID from the Azure App Registration. + +Here is an example for `azure-pipeline-integration.yml` workflow file: +Make sure to change the highlighted line to your variable group's name. + +
+Azure pipline integration (Click to expand) + +```yaml showLineNumbers +name: Azure Resource Graph Exporter Pipeline + +trigger: none + +schedules: + - cron: "0 */4 * * *" + displayName: Every 4 Hours + branches: + include: + - main + always: true + +variables: + # highlight-start + - group: port-azure-exporter-secrets # Contains the secrets used below + # highlight-end + +pool: + vmImage: 'ubuntu-latest' + +steps: + - task: Bash@3 + displayName: 'Run Ocean Sail (Azure-RG)' + inputs: + targetType: 'inline' + script: | + set -euo pipefail + + echo "Building .env file for Ocean Sail..." + + echo "OCEAN__PORT__CLIENT_ID=$(PORT_CLIENT_ID)" > .sail-env + echo "OCEAN__PORT__CLIENT_SECRET=$(PORT_CLIENT_SECRET)" >> .sail-env + echo "OCEAN__PORT__BASE_URL=https://api.getport.io" >> .sail-env + + echo "OCEAN__EVENT_LISTENER={\"type\":\"ONCE\"}" >> .sail-env + echo "OCEAN__INITIALIZE_PORT_RESOURCES=true" >> .sail-env + + echo "OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_ID=$(OCEAN__SECRET__AZURE_CLIENT_ID)" >> .sail-env + echo "OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_SECRET=$(OCEAN__SECRET__AZURE_CLIENT_SECRET)" >> .sail-env + echo "OCEAN__INTEGRATION__CONFIG__AZURE_TENANT_ID=$(OCEAN__SECRET__AZURE_TENANT_ID)" >> .sail-env + + echo "Running Ocean Sail container..." + docker run -i --rm \ + --platform=linux/amd64 \ + --env-file .sail-env \ + ghcr.io/port-labs/port-ocean-azure-rg:latest + + - task: Bash@3 + displayName: 'Clean up .env file' + condition: always() + inputs: + targetType: 'inline' + script: | + rm -f .sail-env + +``` + +
+ + + + + +The Azure exporter is deployed using Github Actions, which supports scheduled resyncs of resources from Azure to Port. + +- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- Azure App Registration Credentials (See below) + + + + +

Installation

+ +Now that you have the Azure App Registration details, you can set up the Azure exporter using Github Actions. + +Make sure to configure the following [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions): + +- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). + - `PORT_CLIENT_ID` + - `PORT_CLIENT_SECRET` +- Azure Credentials: + - `OCEAN__SECRET__AZURE_CLIENT_ID`: The Application (client) ID from the Azure App Registration. + - `OCEAN__SECRET__AZURE_CLIENT_SECRET`: The Application (client) Secret from the Azure App Registration. + - `OCEAN__SECRET__AZURE_TENANT_ID`: The Directory (tenant) ID from the Azure App Registration. + + + +
+ +Here is an example for `azure-rg-integration.yml` workflow file: + +
+GitHub Action integration (Click to expand) + + ```yaml showLineNumbers + name: Azure Resource Graph Exporter Workflow + + on: + workflow_dispatch: + schedule: + - cron: '0 */4 * * *' + + jobs: + run-integration: + runs-on: ubuntu-latest + steps: + - name: Run azure-rg Integration + uses: port-labs/ocean-sail@v1 + with: + type: azure-rg + port_client_id: ${{ secrets.PORT_CLIENT_ID }} + port_client_secret: ${{ secrets.PORT_CLIENT_SECRET }} + port_base_url: "https://api.getport.io" + config: | + azure_client_id: ${{ secrets.OCEAN__SECRET__AZURE_CLIENT_ID }} + azure_client_secret: ${{ secrets.OCEAN__SECRET__AZURE_CLIENT_SECRET }} + azure_tenant_id: ${{ secrets.OCEAN__SECRET__AZURE_TENANT_ID }} + ``` +
+ + + + + +

Prerequisites

+ +- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- [ArgoCD](https://argoproj.github.io/argo-cd/getting_started/) >= 2.0.0 +- Azure App Registration Credentials (See below) + + + +

Installation

+ +1. Create a `values.yaml` file in `argocd/azure-integration` in your git repository with the content: + +```yaml showLineNumbers +initializePortResources: true +scheduledResyncInterval: 120 +integration: + identifier: azure-rg-integration + type: azure-rg + eventListener: + type: POLLING + config: + azureClientId: + azureClientSecret: + azureTenantId: +``` + +2. Install the `azure-rg-integration` ArgoCD Application by creating the following `azure-rg-integration.yaml` manifest: + +:::note Replace placeholders +Remember to replace the placeholders for `YOUR_PORT_CLIENT_ID` `YOUR_PORT_CLIENT_SECRET` and `YOUR_GIT_REPO_URL`. +Multiple sources ArgoCD documentation can be found [here](https://argo-cd.readthedocs.io/en/stable/user-guide/multiple_sources/#helm-value-files-from-external-git-repository). +::: + +
+ArgoCD Application (Click to expand) + + ```yaml showLineNumbers + apiVersion: argoproj.io/v1alpha1 + kind: Application + metadata: + name: my-ocean-azure-rg-integration + namespace: argocd + spec: + destination: + namespace: mmy-ocean-azure-rg-integration + server: https://kubernetes.default.svc + project: default + sources: + - repoURL: 'https://port-labs.github.io/helm-charts/' + chart: port-ocean + targetRevision: 0.9.5 + helm: + valueFiles: + - $values/argocd/my-ocean-azure-rg-integration/values.yaml + // highlight-start + parameters: + - name: port.clientId + value: YOUR_PORT_CLIENT_ID + - name: port.clientSecret + value: YOUR_PORT_CLIENT_SECRET + - name: port.baseUrl + value: https://api.getport.io + // highlight-end + - repoURL: YOUR_GIT_REPO_URL + // highlight-end + targetRevision: main + ref: values + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true +``` +
+ + + +3. Apply the `azure-rg-integration.yaml` manifest to your Kubernetes cluster. +```bash +kubectl apply -f azure-rg-integration.yaml +``` + + + + + +Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project): + +| Parameter | Description | Required | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `OCEAN__PORT__CLIENT_ID` | Your port client id. | ✅ | +| `OCEAN__PORT__CLIENT_SECRET` | Your port client secret. | ✅ | +| `OCEAN__PORT__BASE_URL` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US. | ✅ | +| `OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_ID` | The client ID of the Azure App Registration. | ✅ | +| `OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_SECRET` | The client secret of the Azure App Registration. | ✅ | +| `OCEAN__INTEGRATION__CONFIG__AZURE_TENANT_ID` | The tenant ID of the Azure App Registration. | ✅ | +| `OCEAN__INITIALIZE_PORT_RESOURCES` | Default true, when set to false the integration will not create default blueprints and the port App config mapping. | ❌ | +| `OCEAN__SEND_RAW_DATA_EXAMPLES` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true. | ❌ | +| `OCEAN__EVENT_LISTENER` | [The event listener object](https://ocean.getport.io/framework/features/event-listener/). | ❌ | + +
+ +Here is an example for `.gitlab-ci.yml` pipeline file: + +```yaml showLineNumbers +default: + image: docker:24.0.5 + services: + - docker:24.0.5-dind + before_script: + - docker info + +variables: + INTEGRATION_TYPE: azure-rg + VERSION: latest + +stages: + - ingest + +ingest_data: + stage: ingest + variables: + IMAGE_NAME: ghcr.io/port-labs/port-ocean-$INTEGRATION_TYPE:$VERSION + script: + - | + docker run -i --rm --platform=linux/amd64 \ + -e OCEAN__PORT__CLIENT_ID=$PORT_CLIENT_ID \ + -e OCEAN__PORT__CLIENT_SECRET=$PORT_CLIENT_SECRET \ + -e OCEAN__PORT__BASE_URL="https://api.port.io" \ + -e OCEAN__INITIALIZE_PORT_RESOURCES=true \ + -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ + -e OCEAN__EVENT_LISTENER='{"type": "ONCE"}' \ + -e OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_ID="Enter value here" \ + -e OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_SECRET="Enter value here" \ + -e OCEAN__INTEGRATION__CONFIG__AZURE_TENANT_ID="Enter value here" \ + $IMAGE_NAME + + rules: # Run only when changes are made to the main branch + - if: '$CI_COMMIT_BRANCH == "main"' +``` + + + + + + + + + +

Prerequisites

+- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- [Docker](https://docs.docker.com/get-docker/) +- [Azure App Registration Credentials](?installation-methods=on-premise#azure-app-registration) + + + +

Installation

+ +Now that you have the Azure App Registration details, you can install the Azure exporter using Docker. + +You should have the following information ready: + +- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). + - `PORT_CLIENT_ID` + - `PORT_CLIENT_SECRET` +- Azure Credentials: + - `AZURE_CLIENT_ID`: The Application (client) ID from the Azure App Registration. + - `AZURE_CLIENT_SECRET`: The Application (client) Secret from the Azure App Registration. + - `AZURE_TENANT_ID`: The Directory (tenant) ID from the Azure App Registration. + +
+Environment Variables + +| Variable | Description | +|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| `OCEAN__PORT__CLIENT_ID` | Your Port client ID. | +| `OCEAN__PORT__CLIENT_SECRET` | Your Port client secret. | +| `OCEAN__PORT__BASE_URL` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | +| `OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_ID` | The client ID of the Azure App Registration. | +| `OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_SECRET` | The client secret of the Azure App Registration. | +| `OCEAN__INTEGRATION__CONFIG__AZURE_TENANT_ID` | The tenant ID of the Azure App Registration. | +| `OCEAN__EVENT_LISTENER` | [The event listener object](https://ocean.getport.io/framework/features/event-listener/). | +| `OCEAN__INTEGRATION__IDENTIFIER` | The identifier of the integration. | +| `OCEAN__INTEGRATION__TYPE` | should be set to `azure-rg`. | +| `OCEAN__INITIALIZE_PORT_RESOURCES` | Default true, When set to true the integration will create default blueprints and the port App config Mapping. Read more about [initializePortResources](https://ocean.getport.io/develop-an-integration/integration-configuration/#initializeportresources---initialize-port-resources) | +| `OCEAN__SEND_RAW_DATA_EXAMPLES` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true | + +
+ +For example: + +```bash +docker run -i --rm --platform=linux/amd64 \ + -e OCEAN__PORT__CLIENT_ID="$PORT_CLIENT_ID" \ + -e OCEAN__PORT__CLIENT_SECRET="$PORT_CLIENT_SECRET" \ + -e OCEAN__PORT__BASE_URL="https://api.getport.io" \ + -e OCEAN__INITIALIZE_PORT_RESOURCES=true \ + -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ + -e OCEAN__EVENT_LISTENER='{"type": "ONCE"}' \ + -e OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_ID=AZURE_CLIENT_ID \ + -e OCEAN__INTEGRATION__CONFIG__AZURE_CLIENT_SECRET=$AZURE_CLIENT_SECRET \ + -e OCEAN__INTEGRATION__CONFIG__AZURE_TENANT_ID=$AZURE_TENANT_ID \ +ghcr.io/port-labs/port-ocean-azure-rg:latest +``` + + + + + +## Examples + +### Resource type filtering + +You can alter the resources fetched from Azure resource graph by configuring the resource types selector. + +
+ Blueprint (click to expand) + + ```json showLineNumbers +{ + "identifier": "azureCloudResources", + "description": "This blueprint represents an Azure Cloud Resource in our software catalog", + "title": "Azure Cloud Resources", + "icon": "Azure", + "schema": { + "properties": { + "tags": { + "title": "Tags", + "type": "object" + }, + "type": { + "title": "Type", + "type": "string" + }, + "location": { + "title": "Location", + "type": "string" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} + } + ``` +
+ +
+ Mapping configuration (click to expand) + + ```yaml showLineNumbers + resources: + - kind: resource + selector: + query: 'true' + resource_types: + - microsoft.insights/datacollectionendpoints + port: + entity: + mappings: + identifier: .id | gsub(" ";"_") + title: .name + blueprint: '"azureCloudResources"' + properties: + tags: .tags + type: .type + location: .location + ``` +
+ +### Resource group tag filtering +The integration supports powerful filtering of Azure resources based on tags applied to their parent resource groups. The format allows you to specify both include and exclude conditions in a single configuration. #AI! improve this + +
+ Blueprints (click to expand) + + ```json showLineNumbers + +[ + { + "identifier": "azureResourceGroup", + "description": "This blueprint represents an Azure Resource Group in our software catalog", + "title": "Azure Resource Group", + "icon": "Azure", + "schema": { + "properties": { + "location": { + "title": "Location", + "type": "string" + }, + "tags": { + "title": "Tags", + "type": "object" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} + }, + { + "identifier": "azureCloudResources", + "description": "This blueprint represents an AzureCloud Resource in our software catalog", + "title": "Azure Cloud Resources", + "icon": "Git", + "schema": { + "properties": { + "tags": { + "title": "Tags", + "type": "object" + }, + "type": { + "title": "Type", + "type": "string" + }, + "location": { + "title": "Location", + "type": "string" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "resource_group": { + "title": "Resource Group", + "target": "azureResourceGroup", + "required": false, + "many": false + } + } + } +] + ``` +
+ +
+ Mapping configuration (click to expand) + + ```yaml showLineNumbers +resources: + - kind: resourceContainer + selector: + query: .type == "microsoft.resources/subscriptions/resourcegroups" + tags: + included: + environment: staging + exluded: + environment: production + port: + entity: + mappings: + identifier: .id | gsub(" ";"_") + title: .name + blueprint: '"azureResourceGroup"' + properties: + tags: .tags + location: .location + + - kind: resource + selector: + query: 'true' + tags: + included: + environment: staging + exluded: + environment: production + port: + entity: + mappings: + identifier: .id | gsub(" ";"_") + title: .name + blueprint: '"azureCloudResources"' + properties: + tags: .tags + type: .type + location: .location + relations: + resource_group: >- + ("/subscriptions/" + .subscriptionId + "/resourceGroups/" + .resourceGroup) | gsub(" ";"_") + ``` +
+ +## Frequently asked questions + +### Why use resource group filtering? + +- Individual resources often lack the relevant tags +- Resource groups typically have consistent tagging for classification +- Avoids the need to tag every individual resource +- Provides a consistent filtering mechanism across all resources in a resource group +- Reduces sync time and data volume by filtering at the query level From ff5dc3d5cb05b1766592258407cb142880e5d033 Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Mon, 13 Oct 2025 13:16:03 +0100 Subject: [PATCH 12/40] docs: Improve Azure resource group tag filtering description --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 3fe0321b6f..1a8f009d89 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -579,7 +579,7 @@ You can alter the resources fetched from Azure resource graph by configuring the ### Resource group tag filtering -The integration supports powerful filtering of Azure resources based on tags applied to their parent resource groups. The format allows you to specify both include and exclude conditions in a single configuration. #AI! improve this +The integration provides advanced filtering capabilities for Azure resources by leveraging tags from their parent resource groups. This allows you to define both inclusion and exclusion rules within a single configuration, offering precise control over which resources are synchronized.
Blueprints (click to expand) From f65cfd895818d3ea9581fe52323abfcc11609cb4 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 13:16:48 +0100 Subject: [PATCH 13/40] docs: Add note for improving resource type filtering explanation --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 1a8f009d89..d7c020b6ec 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -519,7 +519,7 @@ ghcr.io/port-labs/port-ocean-azure-rg:latest ### Resource type filtering -You can alter the resources fetched from Azure resource graph by configuring the resource types selector. +You can alter the resources fetched from Azure resource graph by configuring the resource types selector. #AI! improve this
Blueprint (click to expand) From 4476b6dc816d24b4ce5249eff5245fc99b7edd09 Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Mon, 13 Oct 2025 13:16:52 +0100 Subject: [PATCH 14/40] docs: Improve explanation of Azure Resource Graph resource type filtering --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index d7c020b6ec..b5cf17c351 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -519,7 +519,7 @@ ghcr.io/port-labs/port-ocean-azure-rg:latest ### Resource type filtering -You can alter the resources fetched from Azure resource graph by configuring the resource types selector. #AI! improve this +You can filter the resources fetched from Azure Resource Graph by using the `resource_types` selector in your mapping. This allows you to specify exactly which resource types to sync, giving you granular control over the data ingested into your software catalog.
Blueprint (click to expand) From 1b8dfd8fbf8f3b1c574aaf3d717216f752e04487 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 13:17:58 +0100 Subject: [PATCH 15/40] docs: Clarify resource type filtering for Azure Resource Graph --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index b5cf17c351..83f3d3b625 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -519,7 +519,7 @@ ghcr.io/port-labs/port-ocean-azure-rg:latest ### Resource type filtering -You can filter the resources fetched from Azure Resource Graph by using the `resource_types` selector in your mapping. This allows you to specify exactly which resource types to sync, giving you granular control over the data ingested into your software catalog. +You can filter the resources fetched from Azure Resource Graph by using the `resource_types` selector in your mapping. This allows you to specify exactly which resource types to sync, giving you granular control over the query used to ingest data into your software catalog. #AI! improve this
Blueprint (click to expand) From 08a46a8b106efb738e2a617c7fd948e03658b4e4 Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Mon, 13 Oct 2025 13:18:02 +0100 Subject: [PATCH 16/40] docs: Improve clarity of Azure Resource Graph resource type filtering --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 83f3d3b625..dc0af4d44a 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -519,7 +519,7 @@ ghcr.io/port-labs/port-ocean-azure-rg:latest ### Resource type filtering -You can filter the resources fetched from Azure Resource Graph by using the `resource_types` selector in your mapping. This allows you to specify exactly which resource types to sync, giving you granular control over the query used to ingest data into your software catalog. #AI! improve this +The integration allows you to filter which resources are ingested from Azure Resource Graph by specifying the `resource_types` in the mapping configuration. By providing a list of resource types, you can control precisely which data is synced, helping to streamline the ingestion process and keep your software catalog focused on the resources that matter most.
Blueprint (click to expand) From a03344e4cf6ea5926dae197266aa5faf4f0c0197 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 13:22:58 +0100 Subject: [PATCH 17/40] chore: Add AI improvement placeholder to Azure Resource Graph FAQ --- .../cloud-providers/azure/azure-resource-graph.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index dc0af4d44a..18d415c67f 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -697,6 +697,7 @@ resources: ## Frequently asked questions +#AI! improve this faq section ### Why use resource group filtering? - Individual resources often lack the relevant tags From 341071faf470a73e84498d9e9b0ca67ed7e1e6ab Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Mon, 13 Oct 2025 13:23:02 +0100 Subject: [PATCH 18/40] docs: Improve Azure resource graph FAQ on resource group filtering --- .../cloud-providers/azure/azure-resource-graph.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 18d415c67f..fcfda7d306 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -697,11 +697,10 @@ resources: ## Frequently asked questions -#AI! improve this faq section -### Why use resource group filtering? - -- Individual resources often lack the relevant tags -- Resource groups typically have consistent tagging for classification -- Avoids the need to tag every individual resource -- Provides a consistent filtering mechanism across all resources in a resource group -- Reduces sync time and data volume by filtering at the query level +### Why should I filter resources by their resource group tags? + +Filtering resources based on their parent resource group's tags is a powerful feature that simplifies resource management and synchronization. Here's why it's beneficial: + +- **Simplified Tagging Strategy**: Instead of tagging every individual resource, you can apply tags at the resource group level. This is often more manageable and ensures that all resources within a group share a common context (e.g., environment, application, or owner). +- **Consistent Classification**: Resource groups usually have a more consistent tagging strategy compared to individual resources. By filtering at this level, you can reliably include or exclude entire sets of related resources. +- **Improved Efficiency**: By filtering at the query level, you reduce the amount of data synced from Azure. This not only speeds up the ingestion process but also minimizes the volume of data processed, leading to a more efficient and focused software catalog. From adcf2f92dddb62097984c9aae954c80e9846d13c Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 13:26:40 +0100 Subject: [PATCH 19/40] docs: Add internal question regarding Azure RG subscription limit --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index fcfda7d306..f34526063c 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -15,7 +15,7 @@ import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_expl Sync your Azure environment to Port at scale using Azure Resource Graph and Ocean framework. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: - **Centralized Syncing**: Ingest resources from all your Azure subscriptions with a single deployment. -- **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 1000 subscriptions simultaneously for maximum performance. +- **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 1000 subscriptions simultaneously for maximum performance. #AI? is 1000 the maximum subscriptions than can be synced using Azure resource graph? - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. ## Overview From ba336f4df05ffc110dd52897624ddb40add7e736 Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Mon, 13 Oct 2025 13:26:44 +0100 Subject: [PATCH 20/40] docs: Update Azure Resource Graph subscription sync limit to 5000 --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index f34526063c..f2d661ea9d 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -15,7 +15,7 @@ import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_expl Sync your Azure environment to Port at scale using Azure Resource Graph and Ocean framework. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: - **Centralized Syncing**: Ingest resources from all your Azure subscriptions with a single deployment. -- **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 1000 subscriptions simultaneously for maximum performance. #AI? is 1000 the maximum subscriptions than can be synced using Azure resource graph? +- **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 5000 subscriptions simultaneously for maximum performance. - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. ## Overview From 6aee654d78a84fd6b1613f72fa683554e0d84dba Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 13:30:36 +0100 Subject: [PATCH 21/40] The user wants a one-line Git commit message. I need to analyze the diff and determine the type and a concise description. The diff shows a single line added: `#AI? can this overview section be improved?` This line is a comment, likely for internal use or a placeholder for future changes/AI suggestions. It's not a functional change to the code or documentation for the end-user. Therefore, the type should be `chore` as it's a minor internal change/note. The description should reflect that it's an internal note or a prompt for improvement. Let's consider the options: - `chore: Add AI prompt for doc improvement` (too long) - `chore: Add internal note for doc improvement` (good) - `chore: Add comment for AI review` (good) - `chore: Add AI prompt to docs` (concise) - `docs: Add AI improvement note` (Could be `docs` if it was actual documentation content, but this is a meta-comment *about* the docs. `chore` feels more appropriate for an internal note.) Given the line is a direct question to an AI, `chore: Add AI prompt to docs` seems very accurate and concise. `chore: Add internal note for doc improvement` is also good. Let's go with `chore: Add AI prompt to docs`. It's under 72 chars and describes the change.chore: Add AI prompt to docs --- .../cloud-providers/azure/azure-resource-graph.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index f2d661ea9d..6ac8e64e81 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -18,6 +18,7 @@ Sync your Azure environment to Port at scale using Azure Resource Graph and Ocea - **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 5000 subscriptions simultaneously for maximum performance. - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. +#AI? can this overview section be improved? ## Overview This integration is built on Port's open-source [Ocean framework](https://ocean.port.io), providing a robust solution for syncing your Azure resources to Port. It is written in Python and utilizes the Azure SDK to query the Azure Resource Graph API. From a8c36778f93ffa342850b8d304220c9c25796d60 Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Mon, 13 Oct 2025 13:30:39 +0100 Subject: [PATCH 22/40] docs: Improve Azure Resource Graph integration overview section --- .../cloud-providers/azure/azure-resource-graph.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 6ac8e64e81..b47a3fbb8d 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -18,14 +18,13 @@ Sync your Azure environment to Port at scale using Azure Resource Graph and Ocea - **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 5000 subscriptions simultaneously for maximum performance. - **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. -#AI? can this overview section be improved? ## Overview -This integration is built on Port's open-source [Ocean framework](https://ocean.port.io), providing a robust solution for syncing your Azure resources to Port. It is written in Python and utilizes the Azure SDK to query the Azure Resource Graph API. +This integration provides a robust solution for syncing your Azure resources to Port by leveraging our open-source [Ocean framework](https://ocean.port.io). It uses the Azure SDK to efficiently query the Azure Resource Graph API, ensuring high-performance data ingestion even in large-scale environments. -The integration performs a full synchronization of your Azure resources on each run, ensuring that your software catalog accurately reflects the current state of your environment. With flexible data mapping capabilities, you can customize how the ingested data is structured and related within Port. +On each run, the integration performs a full synchronization, so your software catalog always reflects the current state of your Azure resources. You can use declarative YAML mapping to transform raw data and model it according to your software catalog's structure. -You can deploy the integration in any environment that supports Python, including Kubernetes, Docker, or a local machine, giving you full control over its execution and scheduling. +The integration is packaged as a Docker container and can be deployed in any environment that supports it, such as Kubernetes or your CI/CD pipeline. This gives you full control over its execution schedule and operational management. ## Supported resources From 0c7ed9705e95ca5375735199eb9acf07fddac978 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 13:38:33 +0100 Subject: [PATCH 23/40] Delete old docs file --- .../azure/multi-resource-graph.md | 107 ------------------ 1 file changed, 107 deletions(-) delete mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md deleted file mode 100644 index 5fae4ae72b..0000000000 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-resource-graph.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -sidebar_position: 4 ---- - -import Tabs from "@theme/Tabs" -import TabItem from "@theme/TabItem" -import CredentialsGuide from "/docs/build-your-software-catalog/custom-integration/api/\_template_docs/\_find_credentials.mdx"; -import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" - -# Azure resource graph - -Sync your Azure environment to Port at scale using Azure Resource Graph and Ocean framework. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: - -- **Centralized Syncing**: Ingest resources from all your Azure subscriptions with a single deployment. -- **High-Speed Ingestion**: Leverage Azure Resource Graph to query and sync up to 1000 subscriptions simultaneously for maximum performance. -- **Customizable Mapping**: Take full control over which resource types are ingested and how they are mapped to your software catalog. - -## Overview - -This integration is built on Port's open-source [Ocean framework](https://ocean.port.io), providing a robust solution for syncing your Azure resources to Port. It is written in Python and utilizes the Azure SDK to query the Azure Resource Graph API. - -The integration performs a full synchronization of your Azure resources on each run, ensuring that your software catalog accurately reflects the current state of your environment. With flexible data mapping capabilities, you can customize how the ingested data is structured and related within Port. - -You can deploy the integration in any environment that supports Python, including Kubernetes, Docker, or a local machine, giving you full control over its execution and scheduling. - -## Supported resources - -The integration syncs data from two main Azure Resource Graph tables: - -- `Resources`: This table includes a wide array of Azure resources, such as virtual machines, storage accounts, network interfaces, and more. The integration syncs their properties, tags, and metadata. -- `ResourceContainers`: This table contains management groups, subscriptions, and resource groups, providing the hierarchical context for your Azure resources. - -### Azure setup - -This integration requires the standard [Azure app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate%2Cexpose-a-web-api) setup. - -Keep the following credentials handy after setup: -- `AZURE_CLIENT_ID`: The client ID of the Azure service principal -- `AZURE_CLIENT_SECRET`: The client secret of the Azure service principal -- `AZURE_TENANT_ID`: The tenant ID of the Azure service principal - - - -### Port setup - -The basic Port setup follows the [standard installation guide](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/installation.md#port-setup). However, this integration uses a different webhook configuration for incremental syncing: - -#### Port credentials - - - -## Configuration - -Port integrations use a [YAML mapping block](/build-your-software-catalog/customize-integrations/configure-mapping#configuration-structure) to ingest data from the third-party api into Port. - -The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API. - -### Default mapping configuration - -This is the default mapping configuration you get after installing the Azure integration. - -
-Default mapping configuration (Click to expand) - - ```yaml showLineNumbers -resources: - - kind: resource - selector: - query: 'true' - port: - entity: - mappings: - identifier: '.id | gsub(" ";"_")' - title: .name - blueprint: '"azureCloudResources"' - properties: - tags: .tags - type: .type - location: .location - - kind: resourceContainer - selector: - query: .type == "microsoft.resources/subscriptions" - port: - entity: - mappings: - identifier: '.id | gsub(" ";"_")' - title: .name - blueprint: '"azureSubscription"' - properties: - subscriptionId: .subscriptionId - location: .location - - kind: resourceContainer - selector: - query: .type == "microsoft.resources/subscriptions/resourcegroups" - port: - entity: - mappings: - identifier: '.id | gsub(" ";"_")' - title: .name - blueprint: '"azureResourceGroup"' - properties: - tags: .tags - location: .location - relations: - subscription: '("/subscriptions/" + .subscriptionId) | gsub(" ";"_")' - ``` -
From 2d672c99f4f68671c7c769497f162fa2a8707b94 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Mon, 13 Oct 2025 16:12:01 +0100 Subject: [PATCH 24/40] Chore: Remove reference to deleted incremental sync page --- .../sync-data-to-catalog/cloud-providers/azure/azure.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure.md index bd3f2af2e3..8f0c38c556 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure.md @@ -62,7 +62,6 @@ Use the Azure exporter when you need comprehensive resource scanning and can set - Refer to the [Resource Templates](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/resource_templates/resource_templates.md) page for templates on how to map Azure resources to Port. - Check out the [Azure Multi Subscriptions](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md) guide for setting up synchronization of Azure resources. -- Learn about [Azure Incremental Sync](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/incremental-sync.md) for lightweight, efficient change-based synchronization. ## Configuration From eda2da446ec5702eff7ca6a821463dd597a16eac Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 10:52:44 +0100 Subject: [PATCH 25/40] Fix integration version --- .../cloud-providers/azure/azure-resource-graph.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index b47a3fbb8d..d7b02b2a68 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -109,7 +109,7 @@ This way of deployment supports scheduled resyncs of resources from Azure to Por

Installation

- + Now that you have the Azure App Registration details, you can install the Azure exporter using Helm. @@ -164,7 +164,7 @@ The Azure exporter is deployed using Azure DevOps pipline, which supports schedu Now that you have the Azure App Registration details, you can set up the Azure exporter using an Azure DevOps pipeline. -Make sure to configure the following [seceret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables?view=azure-devops&tabs=yaml%2Cbash) in a variable group: +Make sure to configure the following [secret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables?view=azure-devops&tabs=yaml%2Cbash) in a variable group: - Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). - `PORT_CLIENT_ID` From 4fd7f6652ea3394df74f1b6a4f6ac680068a1c51 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 11:01:21 +0100 Subject: [PATCH 26/40] Deprecate multi-subscriptions page --- .../cloud-providers/azure/multi-subscriptions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md index 079efa3d95..d487330ee5 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md @@ -7,7 +7,7 @@ import TabItem from "@theme/TabItem" import CredentialsGuide from "/docs/build-your-software-catalog/custom-integration/api/\_template_docs/\_find_credentials.mdx"; import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" -# Azure multi subscriptions +# Azure multi subscriptions (Deprecated) The Azure multi-subscription sync solution provides a way to periodically sync resources from multiple Azure subscriptions into Port with these key advantages: From a67308a05707624d7d2150e6ae7f7644cfdd6e04 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Tue, 14 Oct 2025 10:24:33 +0000 Subject: [PATCH 27/40] docs: Update formatting and indentation in Azure App Registration guide --- .../azure/_azure_app_registration_guide.mdx | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/_azure_app_registration_guide.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/_azure_app_registration_guide.mdx index 637755ecdf..069b7cc380 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/_azure_app_registration_guide.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/_azure_app_registration_guide.mdx @@ -4,40 +4,40 @@ To ingest resources from Azure, you will need to create an Azure App Registratio 1. Create an Azure App Registration in the Azure portal. -

+

-

+

2. Copy the `Application (client) ID` and `Directory (tenant) ID` from the App Registration. -

+

3. Create a client secret for the App Registration. -

+

4. Copy the `Application (client) Secret` from the App Registration. -

+

5. Create a new role assignment for the App Registration. Go to the `Access control (IAM)` section of the subscription you want to ingest resources from.

Click on `Add role assignment`. -:::info Multi Account Support -It is supported to ingest resources from multiple subscriptions, for that you will have to repeat the role assignment -for each subscription you want to ingest resources from. -::: + :::info Multi Account Support + It is supported to ingest resources from multiple subscriptions, for that you will have to repeat the role assignment + for each subscription you want to ingest resources from. + ::: -

+

6. Assign the `Reader` role to the App Registration. -:::tip Permissions -The Reader role is recommended for querying all resources in your Azure subscription. You can restrict permissions to specific resource groups or types by assigning a different role. If you do this, remember to adjust permissions when adding more resources to the catalog. -Basic permissions required for ingesting resources from Azure include: -- `Microsoft.Resources/subscriptions/read` (to list the accessible subscriptions) -- `Microsoft.Resources/subscriptions/resourceGroups/read` (to list the accessible resource groups) -- `read`/`list` permissions to the resources you want to ingest -::: + :::tip Permissions + The Reader role is recommended for querying all resources in your Azure subscription. You can restrict permissions to specific resource groups or types by assigning a different role. If you do this, remember to adjust permissions when adding more resources to the catalog. + Basic permissions required for ingesting resources from Azure include: + - `Microsoft.Resources/subscriptions/read` (to list the accessible subscriptions) + - `Microsoft.Resources/subscriptions/resourceGroups/read` (to list the accessible resource groups) + - `read`/`list` permissions to the resources you want to ingest + ::: -

+

From 11246f1c4ecc6aee0e9a94456644cf46af64138b Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 14:31:20 +0100 Subject: [PATCH 28/40] docs: Improve Azure Resource Graph documentation structure and examples --- .../azure/azure-resource-graph.md | 110 +++++++++++------- 1 file changed, 65 insertions(+), 45 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index d7b02b2a68..95bdd23070 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -10,7 +10,7 @@ import DockerParameters from "./\_azure_docker_params.mdx" import IntegrationVersion from "/src/components/IntegrationVersion/IntegrationVersion" import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md" -# Azure resource graph +# Azure Resource Graph Sync your Azure environment to Port at scale using Azure Resource Graph and Ocean framework. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: @@ -90,7 +90,26 @@ resources: ```
-## installation +## Setup + +### Port setup + +#### Port credentials + + + +### Azure setup + +This integration requires the standard [Azure app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate%2Cexpose-a-web-api) setup. + +Keep the following credentials handy after setup: +- `AZURE_CLIENT_ID`: The client ID of the Azure service principal +- `AZURE_CLIENT_SECRET`: The client secret of the Azure service principal +- `AZURE_TENANT_ID`: The tenant ID of the Azure service principal + + + +## Installation @@ -101,11 +120,9 @@ The Azure resource graph exporter is deployed using helm on kubernetes. This way of deployment supports scheduled resyncs of resources from Azure to Port.

Prerequisites

-- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- [Port API credentials](#port-credentials) - [Helm](https://helm.sh/docs/intro/install/) >= 3.0.0 -- [Azure App Registration Credentials](See below) - - +- Azure App Registration Credentials

Installation

@@ -115,7 +132,7 @@ Now that you have the Azure App Registration details, you can install the Azure You should have the following information ready: -- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). +- Port API credentials, you can check out the [Port API documentation](#port-credentials). - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -154,11 +171,9 @@ The Azure exporter is deployed using Azure DevOps pipline, which supports schedu

Prerequisites

-- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- [Port API credentials](#port-credentials) - Access to an Azure DevOps project with permission to configure pipelines and secrets. -- Azure App Registration Credentials (See below) - - +- Azure App Registration Credentials

Installation

@@ -166,7 +181,7 @@ Now that you have the Azure App Registration details, you can set up the Azure e Make sure to configure the following [secret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables?view=azure-devops&tabs=yaml%2Cbash) in a variable group: -- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). +- Port API credentials, you can check out the [Port API documentation](#port-credentials). - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -235,7 +250,6 @@ steps: targetType: 'inline' script: | rm -f .sail-env - ```
@@ -246,11 +260,8 @@ steps: The Azure exporter is deployed using Github Actions, which supports scheduled resyncs of resources from Azure to Port. -- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) -- Azure App Registration Credentials (See below) - - - +- [Port API credentials](#port-credentials) +- Azure App Registration Credentials

Installation

@@ -258,7 +269,7 @@ Now that you have the Azure App Registration details, you can set up the Azure e Make sure to configure the following [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions): -- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). +- Port API credentials, you can check out the [Port API documentation](#port-credentials). - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -307,28 +318,26 @@ Here is an example for `azure-rg-integration.yml` workflow file:

Prerequisites

-- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- [Port API credentials](#port-credentials) - [ArgoCD](https://argoproj.github.io/argo-cd/getting_started/) >= 2.0.0 -- Azure App Registration Credentials (See below) - - +- Azure App Registration Credentials

Installation

-1. Create a `values.yaml` file in `argocd/azure-integration` in your git repository with the content: +1. Create a `values.yaml` file in `argocd/azure-rg-integration` in your git repository with the content: ```yaml showLineNumbers -initializePortResources: true -scheduledResyncInterval: 120 -integration: - identifier: azure-rg-integration - type: azure-rg - eventListener: - type: POLLING - config: - azureClientId: - azureClientSecret: - azureTenantId: + initializePortResources: true + scheduledResyncInterval: 120 + integration: + identifier: azure-rg-integration + type: azure-rg + eventListener: + type: POLLING + config: + azureClientId: + azureClientSecret: + azureTenantId: ``` 2. Install the `azure-rg-integration` ArgoCD Application by creating the following `azure-rg-integration.yaml` manifest: @@ -384,6 +393,7 @@ Multiple sources ArgoCD documentation can be found [here](https://argo-cd.readth 3. Apply the `azure-rg-integration.yaml` manifest to your Kubernetes cluster. + ```bash kubectl apply -f azure-rg-integration.yaml ``` @@ -404,7 +414,6 @@ Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ | `OCEAN__INTEGRATION__CONFIG__AZURE_TENANT_ID` | The tenant ID of the Azure App Registration. | ✅ | | `OCEAN__INITIALIZE_PORT_RESOURCES` | Default true, when set to false the integration will not create default blueprints and the port App config mapping. | ❌ | | `OCEAN__SEND_RAW_DATA_EXAMPLES` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true. | ❌ | -| `OCEAN__EVENT_LISTENER` | [The event listener object](https://ocean.getport.io/framework/features/event-listener/). | ❌ |
@@ -456,11 +465,9 @@ ingest_data:

Prerequisites

-- [Port API credentials](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) +- [Port API credentials](#port-credentials) - [Docker](https://docs.docker.com/get-docker/) -- [Azure App Registration Credentials](?installation-methods=on-premise#azure-app-registration) - - +- Azure App Registration Credentials

Installation

@@ -468,7 +475,7 @@ Now that you have the Azure App Registration details, you can install the Azure You should have the following information ready: -- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/custom-integration/api/#find-your-port-credentials). +- Port API credentials, you can check out the [Port API documentation](#port-credentials). - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -517,9 +524,11 @@ ghcr.io/port-labs/port-ocean-azure-rg:latest ## Examples -### Resource type filtering +### Mapping Azure Cloud resources + +The following example demonstrates how to ingest your Azure Subscriptions to Port. +You can use the following Port blueprint definitions and integration configuration: -The integration allows you to filter which resources are ingested from Azure Resource Graph by specifying the `resource_types` in the mapping configuration. By providing a list of resource types, you can control precisely which data is synced, helping to streamline the ingestion process and keep your software catalog focused on the resources that matter most.
Blueprint (click to expand) @@ -578,8 +587,15 @@ The integration allows you to filter which resources are ingested from Azure Res ```
-### Resource group tag filtering -The integration provides advanced filtering capabilities for Azure resources by leveraging tags from their parent resource groups. This allows you to define both inclusion and exclusion rules within a single configuration, offering precise control over which resources are synchronized. +#### Configuration options + +The integration allows you to filter which resources are ingested from Azure Resource Graph by specifying the `resource_types` in the mapping configuration. By providing a list of resource types, you can control precisely which data is synced, helping to streamline the ingestion process and keep your software catalog focused on the resources that matter most. #Ai! make this more succint + +### Mapping cloud resources and resource groups + +The following example demonstrates how to ingest your Azure Subscriptions to Port. +You can use the following Port blueprint definitions and integration configuration: +
Blueprints (click to expand) @@ -695,6 +711,10 @@ resources: ```
+#### Configuration options + +The integration provides advanced filtering capabilities for Azure resources by leveraging tags from their parent resource groups. This allows you to define both inclusion and exclusion rules within a single configuration, offering precise control over which resources are synchronized. + ## Frequently asked questions ### Why should I filter resources by their resource group tags? From 7fbd30d42a66b2630431a0e72eb05f5d7049a84b Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Tue, 14 Oct 2025 14:31:26 +0100 Subject: [PATCH 29/40] docs: Make Azure Resource Graph config options succinct --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 95bdd23070..42c94e5cb2 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -589,7 +589,7 @@ You can use the following Port blueprint definitions and integration configurati #### Configuration options -The integration allows you to filter which resources are ingested from Azure Resource Graph by specifying the `resource_types` in the mapping configuration. By providing a list of resource types, you can control precisely which data is synced, helping to streamline the ingestion process and keep your software catalog focused on the resources that matter most. #Ai! make this more succint +You can filter resources from Azure Resource Graph by specifying `resource_types` in the mapping configuration. This provides precise control over synced data, streamlining ingestion and keeping your catalog focused on relevant resources. ### Mapping cloud resources and resource groups From dbe02ec37e6bc24cd995e12421cff6e8cee8d4d2 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 14:37:29 +0100 Subject: [PATCH 30/40] docs: Add AI prompt to shorten Azure ARG filtering description --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 42c94e5cb2..fe8655daa8 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -713,7 +713,7 @@ resources: #### Configuration options -The integration provides advanced filtering capabilities for Azure resources by leveraging tags from their parent resource groups. This allows you to define both inclusion and exclusion rules within a single configuration, offering precise control over which resources are synchronized. +The integration provides advanced filtering capabilities for Azure resources by leveraging tags from their parent resource groups. This allows you to define both inclusion and exclusion rules within a single configuration, offering precise control over which resources are synchronized. #AI! make this more succint ## Frequently asked questions From 95ef22ec9e1d08c4de51fad95c892d7afa15fc4a Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Tue, 14 Oct 2025 14:37:39 +0100 Subject: [PATCH 31/40] docs: Refine Azure Resource Graph filtering description --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index fe8655daa8..7414913215 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -713,7 +713,7 @@ resources: #### Configuration options -The integration provides advanced filtering capabilities for Azure resources by leveraging tags from their parent resource groups. This allows you to define both inclusion and exclusion rules within a single configuration, offering precise control over which resources are synchronized. #AI! make this more succint +You can filter Azure resources using tags from their parent resource groups. This allows you to define both inclusion and exclusion rules in a single configuration, giving you precise control over which resources are synchronized. ## Frequently asked questions From 36d0b70fc8abca398969c6e9239dfacaeef5f285 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 14:40:44 +0100 Subject: [PATCH 32/40] docs: Add comment to improve FAQ section --- .../cloud-providers/azure/azure-resource-graph.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 7414913215..4d227e2163 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -717,6 +717,7 @@ You can filter Azure resources using tags from their parent resource groups. Thi ## Frequently asked questions +#Ai! make this section more succint ### Why should I filter resources by their resource group tags? Filtering resources based on their parent resource group's tags is a powerful feature that simplifies resource management and synchronization. Here's why it's beneficial: From ac1b7289252f944ababda34632aa993d7cfe03cf Mon Sep 17 00:00:00 2001 From: "Melody Daniel (aider)" Date: Tue, 14 Oct 2025 14:40:48 +0100 Subject: [PATCH 33/40] docs: Make Azure Resource Graph FAQ more succinct --- .../cloud-providers/azure/azure-resource-graph.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 4d227e2163..1dd8ea81ba 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -717,11 +717,10 @@ You can filter Azure resources using tags from their parent resource groups. Thi ## Frequently asked questions -#Ai! make this section more succint ### Why should I filter resources by their resource group tags? -Filtering resources based on their parent resource group's tags is a powerful feature that simplifies resource management and synchronization. Here's why it's beneficial: +Filtering resources by their parent resource group's tags simplifies management and synchronization for several reasons: -- **Simplified Tagging Strategy**: Instead of tagging every individual resource, you can apply tags at the resource group level. This is often more manageable and ensures that all resources within a group share a common context (e.g., environment, application, or owner). -- **Consistent Classification**: Resource groups usually have a more consistent tagging strategy compared to individual resources. By filtering at this level, you can reliably include or exclude entire sets of related resources. -- **Improved Efficiency**: By filtering at the query level, you reduce the amount of data synced from Azure. This not only speeds up the ingestion process but also minimizes the volume of data processed, leading to a more efficient and focused software catalog. +- **Simplified Tagging**: Apply tags at the resource group level instead of to individual resources. This is more manageable and ensures resources share a common context. +- **Consistent Classification**: Resource group tags are often more consistent than individual resource tags, allowing for reliable filtering of related resources. +- **Improved Efficiency**: Filtering reduces the amount of data synced from Azure, speeding up ingestion and creating a more focused software catalog. From a4e432d2116a5a506d86b10b8ef3d73d7d72833f Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 14:47:34 +0100 Subject: [PATCH 34/40] Add prerequisite to gitlab ci section --- .../cloud-providers/azure/azure-resource-graph.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 1dd8ea81ba..674ad0f44e 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -402,6 +402,11 @@ kubectl apply -f azure-rg-integration.yaml +

Prerequisites

+ +- [Port API credentials](#port-credentials) +- Azure App Registration Credentials + Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project): | Parameter | Description | Required | From b96cc43b758d8fc36a4a73fc2c1be780bbc50c63 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 15:08:10 +0100 Subject: [PATCH 35/40] Chore: Reduce repetition in link --- .../azure/azure-resource-graph.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 674ad0f44e..f0af89aa41 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -132,7 +132,7 @@ Now that you have the Azure App Registration details, you can install the Azure You should have the following information ready: -- Port API credentials, you can check out the [Port API documentation](#port-credentials). +- Port API credentials: - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -171,7 +171,7 @@ The Azure exporter is deployed using Azure DevOps pipline, which supports schedu

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](./#port-credentials) - Access to an Azure DevOps project with permission to configure pipelines and secrets. - Azure App Registration Credentials @@ -181,7 +181,7 @@ Now that you have the Azure App Registration details, you can set up the Azure e Make sure to configure the following [secret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables?view=azure-devops&tabs=yaml%2Cbash) in a variable group: -- Port API credentials, you can check out the [Port API documentation](#port-credentials). +- Port API credentials: - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -260,7 +260,7 @@ steps: The Azure exporter is deployed using Github Actions, which supports scheduled resyncs of resources from Azure to Port. -- [Port API credentials](#port-credentials) +- [Port API credentials](./#port-credentials) - Azure App Registration Credentials

Installation

@@ -269,7 +269,7 @@ Now that you have the Azure App Registration details, you can set up the Azure e Make sure to configure the following [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions): -- Port API credentials, you can check out the [Port API documentation](#port-credentials). +- Port API credentials: - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -318,7 +318,7 @@ Here is an example for `azure-rg-integration.yml` workflow file:

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](./#port-credentials) - [ArgoCD](https://argoproj.github.io/argo-cd/getting_started/) >= 2.0.0 - Azure App Registration Credentials @@ -404,7 +404,7 @@ kubectl apply -f azure-rg-integration.yaml

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](./#port-credentials) - Azure App Registration Credentials Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project): @@ -470,7 +470,7 @@ ingest_data:

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](./#port-credentials) - [Docker](https://docs.docker.com/get-docker/) - Azure App Registration Credentials @@ -480,7 +480,7 @@ Now that you have the Azure App Registration details, you can install the Azure You should have the following information ready: -- Port API credentials, you can check out the [Port API documentation](#port-credentials). +- Port API credentials: - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: From 03e186d2c79248857053f28a49d30bbf90fd2bf5 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Tue, 14 Oct 2025 14:18:36 +0000 Subject: [PATCH 36/40] docs: Update Azure Resource Graph documentation for clarity and structure --- .../azure/azure-resource-graph.md | 37 +++++++++---------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 674ad0f44e..90b1265dc3 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -92,13 +92,12 @@ resources: ## Setup -### Port setup - -#### Port credentials +To set up the Azure Resource Graph exporter, you'll need to configure both Port credentials and Azure app registration. +

Port credentials

-### Azure setup +

Azure setup

This integration requires the standard [Azure app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate%2Cexpose-a-web-api) setup. @@ -120,9 +119,9 @@ The Azure resource graph exporter is deployed using helm on kubernetes. This way of deployment supports scheduled resyncs of resources from Azure to Port.

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) - [Helm](https://helm.sh/docs/intro/install/) >= 3.0.0 -- Azure App Registration Credentials +- [Azure App Registration Credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup)

Installation

@@ -132,7 +131,7 @@ Now that you have the Azure App Registration details, you can install the Azure You should have the following information ready: -- Port API credentials, you can check out the [Port API documentation](#port-credentials). +- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup). - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -171,9 +170,9 @@ The Azure exporter is deployed using Azure DevOps pipline, which supports schedu

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) - Access to an Azure DevOps project with permission to configure pipelines and secrets. -- Azure App Registration Credentials +- [Azure App Registration Credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup)

Installation

@@ -260,8 +259,8 @@ steps: The Azure exporter is deployed using Github Actions, which supports scheduled resyncs of resources from Azure to Port. -- [Port API credentials](#port-credentials) -- Azure App Registration Credentials +- [Port API credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) +- [Azure App Registration Credentials](/build-your-software-catalog/sync-to-catalog/cloud-providers/azure/azure-resource-graph#setup)

Installation

@@ -269,7 +268,7 @@ Now that you have the Azure App Registration details, you can set up the Azure e Make sure to configure the following [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions): -- Port API credentials, you can check out the [Port API documentation](#port-credentials). +- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup). - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: @@ -318,9 +317,9 @@ Here is an example for `azure-rg-integration.yml` workflow file:

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) - [ArgoCD](https://argoproj.github.io/argo-cd/getting_started/) >= 2.0.0 -- Azure App Registration Credentials +- [Azure App Registration Credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup)

Installation

@@ -404,8 +403,8 @@ kubectl apply -f azure-rg-integration.yaml

Prerequisites

-- [Port API credentials](#port-credentials) -- Azure App Registration Credentials +- [Port API credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) +- [Azure App Registration Credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project): @@ -470,9 +469,9 @@ ingest_data:

Prerequisites

-- [Port API credentials](#port-credentials) +- [Port API credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) - [Docker](https://docs.docker.com/get-docker/) -- Azure App Registration Credentials +- [Azure App Registration Credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup)

Installation

@@ -480,7 +479,7 @@ Now that you have the Azure App Registration details, you can install the Azure You should have the following information ready: -- Port API credentials, you can check out the [Port API documentation](#port-credentials). +- Port API credentials, you can check out the [Port API documentation](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup). - `PORT_CLIENT_ID` - `PORT_CLIENT_SECRET` - Azure Credentials: From b9a968d845141a7a29719b2de71b06cf210d19b9 Mon Sep 17 00:00:00 2001 From: kodjomiles Date: Tue, 14 Oct 2025 14:35:18 +0000 Subject: [PATCH 37/40] fix: Correct link to Azure App Registration Credentials in Azure Resource Graph documentation --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index b7b0e18ee8..ad5952defd 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -260,7 +260,7 @@ steps: The Azure exporter is deployed using Github Actions, which supports scheduled resyncs of resources from Azure to Port. - [Port API credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup) -- [Azure App Registration Credentials](/build-your-software-catalog/sync-to-catalog/cloud-providers/azure/azure-resource-graph#setup) +- [Azure App Registration Credentials](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph#setup)

Installation

From 8e94fa76672a29d767ddb38d19c9839f2e6a40c0 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 15:45:39 +0100 Subject: [PATCH 38/40] Use admonition in the mapping comment --- .../cloud-providers/azure/azure-resource-graph.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index ad5952defd..0783763b6b 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -591,9 +591,9 @@ You can use the following Port blueprint definitions and integration configurati ```
-#### Configuration options - +:::info resource type filter You can filter resources from Azure Resource Graph by specifying `resource_types` in the mapping configuration. This provides precise control over synced data, streamlining ingestion and keeping your catalog focused on relevant resources. +::: ### Mapping cloud resources and resource groups @@ -715,9 +715,9 @@ resources: ```
-#### Configuration options - +:::info resource group tags You can filter Azure resources using tags from their parent resource groups. This allows you to define both inclusion and exclusion rules in a single configuration, giving you precise control over which resources are synchronized. +::: ## Frequently asked questions From 5e517583d17d300992f888828898f0dd43641887 Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 16:05:12 +0100 Subject: [PATCH 39/40] Chore: use note rather than info for call out --- .../cloud-providers/azure/azure-resource-graph.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index 0783763b6b..ebd615be67 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -591,7 +591,7 @@ You can use the following Port blueprint definitions and integration configurati ```
-:::info resource type filter +:::note resource type filter You can filter resources from Azure Resource Graph by specifying `resource_types` in the mapping configuration. This provides precise control over synced data, streamlining ingestion and keeping your catalog focused on relevant resources. ::: @@ -715,7 +715,7 @@ resources: ``` -:::info resource group tags +:::note resource group tags You can filter Azure resources using tags from their parent resource groups. This allows you to define both inclusion and exclusion rules in a single configuration, giving you precise control over which resources are synchronized. ::: From 59e877f53a137dbd356f0d010aa8e5b39d755c2f Mon Sep 17 00:00:00 2001 From: Melody Daniel Date: Tue, 14 Oct 2025 16:29:28 +0100 Subject: [PATCH 40/40] Add beta tag and deprecation notice --- .../cloud-providers/azure/azure-resource-graph.md | 2 +- .../cloud-providers/azure/multi-subscriptions.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md index ebd615be67..35e7c9c43e 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/azure-resource-graph.md @@ -10,7 +10,7 @@ import DockerParameters from "./\_azure_docker_params.mdx" import IntegrationVersion from "/src/components/IntegrationVersion/IntegrationVersion" import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md" -# Azure Resource Graph +# Azure Resource Graph (Beta) Sync your Azure environment to Port at scale using Azure Resource Graph and Ocean framework. This integration is designed for high-volume data ingestion across multiple subscriptions, offering several key advantages: diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md index d487330ee5..4ee660d811 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/multi-subscriptions.md @@ -9,6 +9,10 @@ import AzureAppRegistration from "./\_azure_app_registration_guide.mdx" # Azure multi subscriptions (Deprecated) +:::warning Deprecation Notice +This integration is deprecated and will be discontinued soon, please use [Azure Resource Graph](./azure-resource-graph.md) integration instead. +::: + The Azure multi-subscription sync solution provides a way to periodically sync resources from multiple Azure subscriptions into Port with these key advantages: - **No infrastructure required** - runs directly via GitHub Actions or locally