Usage Manual
This page describes how the connector can be used and configured.
Prerequisites
The server running CMDBuild must be able to reach the Azure public cloud, specifically the Azure Resource Manager endpoint and the Microsoft Entra ID endpoint used for authentication (the default endpoints of the Azure SDK for the AzureEnvironment.AZURE environment).
The connector authenticates with a Service Principal with client secret, so the following credentials are required:
- the Tenant ID of the Azure tenant;
- the Client ID (application ID) of the Service Principal;
- the Client secret of the Service Principal.
The Service Principal must be able to list and read the resources of the subscriptions that the connector has to import. The connector performs only read operations; the operations it uses are the following:
Microsoft.App/containerApps/read
Microsoft.App/managedEnvironments/read
Microsoft.Cache/redis/read
Microsoft.Compute/skus/read
Microsoft.Compute/virtualMachineScaleSets/read
Microsoft.Compute/virtualMachines/instanceView/read
Microsoft.Compute/virtualMachines/read
Microsoft.ContainerInstance/containerGroups/read
Microsoft.ContainerService/managedClusters/read
Microsoft.KeyVault/managedHSMs/read
Microsoft.Logic/workflows/read
Microsoft.Network/applicationGateways/read
Microsoft.Network/dnsZones/all/read
Microsoft.Network/dnsZones/read
Microsoft.Network/loadBalancers/read
Microsoft.Network/networkInterfaces/read
Microsoft.Network/privateDnsZones/all/read
Microsoft.Network/privateDnsZones/read
Microsoft.Network/privateDnsZones/virtualNetworkLinks/read
Microsoft.Network/publicIPAddresses/read
Microsoft.Network/virtualNetworks/read
Microsoft.Resources/subscriptions/read
Microsoft.Resources/subscriptions/resourceGroups/read
Microsoft.Sql/servers/automaticTuning/read
Microsoft.Sql/servers/databases/read
Microsoft.Sql/servers/databases/usages/read
Microsoft.Sql/servers/read
Microsoft.Sql/servers/usages/read
Microsoft.Storage/skus/read
Microsoft.Storage/storageAccounts/blobServices/containers/read
Microsoft.Storage/storageAccounts/fileServices/shares/read
Microsoft.Storage/storageAccounts/queueServices/queues/read
Microsoft.Storage/storageAccounts/read
Microsoft.Storage/storageAccounts/tableServices/tables/read
Microsoft.Web/sites/read
The list is derived from the calls performed by the connector and should be considered a suggestion: the permissions actually assigned depend on the services selected in the instance configuration (see the Services attribute below). Only the resources the Service Principal can read are imported.
Connector dependencies
The connector requires the installation of the Connector utils plugin version 2.0.4 or higher and CMDBuild version 4.2.0 or higher.
Configuration
Plugin configuration
The standard connector plugin configuration can be found here.
The connector has no additional plugin configurations.
Instance configuration
Each instance of the connector reads one Azure tenant. Attributes marked with * are mandatory.
| Config | Default | Description | Notes |
|---|---|---|---|
Code* | Unique code that identifies the instance | Used as the name of the instance in the connector runs. | |
Active* | Whether the instance is read during the synchronization | Only active instances are read. | |
Tenant ID* | The Tenant ID used for authentication | ||
Client ID* | The Client ID of the Service Principal used for authentication | ||
Client secret* | The Client secret of the Service Principal used for authentication | Stored as a password attribute. | |
Subscriptions | The subscriptions to read | Comma-separated list of subscription IDs. If empty, all the subscriptions visible to the Service Principal are read. | |
Excluded subscriptions | The subscriptions to exclude from the reading | Comma-separated list of subscription IDs. If empty, no subscription is excluded. An excluded subscription is skipped even if it is listed in Subscriptions. | |
Services | The Azure services to read | Comma-separated list of service names, case-insensitive. If empty, all services are read. Accepted values: ContainerInstance, Compute, Network, Storage, ContainerService, KeyVault, Sql, Redis, Dns, PrivateDns, AppContainers, AppService, LogicApps. Subscriptions and resource groups are always read. | |
Thread timeout | 15 | Maximum time, in minutes, to wait for the reading threads to complete | If not positive, the default value is used. The limit is applied to the reading threads of each subscription, resource group and service: threads still running after the timeout are terminated. |
Entities preview
Subscription and Resource Group are related to all the other records: their arrows point to the dashed container, which groups those records.
The diagram provides a high-level overview of the entities extracted by the connector and the relationships between them.
The diagram uses the following conventions:
-
Orange containers represent CMDBuild superclasses. The entities contained within them belong to the corresponding superclass.
-
Dashed orange containers group all the entities that are related to an entity outside the container. An arrow pointing to the container represents a relationship with each of the entities inside it.
-
Blue boxes represent record types extracted by the connector. Each box is labeled using the format
{Source Object Name} ({_type}), combining the object name used by the source service with the internal record type produced by the connector. -
Arrows represent one-to-many relationships between entities managed by the connector. The arrow points to the "many" side of the relationship, as indicated by its label (
1 : N). -
Lines without arrow tips represent many-to-many relationships between entities managed by the connector, as indicated by their label (
N : N).
Below is a list of all the entities retrieved by the connector.
Subscription
- Subscription (
subscription)
Resources
- Resource Group (
resourcegroup)
Container Instance
- Container Group (
containergroup) - Container (
container)
Compute
- Compute SKU (
computesku) - Virtual Machine Scale Set (
virtualmachinescaleset) - Virtual Machine (
virtualmachine)
Network
- Network (
network) - Subnet (
subnet) - Network Interface (
networkinterface) - Application Gateway (
applicationgateway) - Load Balancer (
loadbalancer) - Load Balancer - Network relation (
loadbalancernetworkrelation) - Load Balancer - Subnet relation (
loadbalancersubnetrelation)
Storage
- Storage SKU (
storagesku) - Generic Storage Account (
genericstorage) - Blob Storage Account (
blobstorage) - File Storage Account (
filestorage) - Blob Container (
blobcontainer) - File Share (
fileshare) - Queue (
queue) - Table (
table)
Container Service
- Kubernetes Cluster (
kubernetescluster)
Key Vault
- Managed HSM (
managedhsm)
Sql
- SQL Server (
sqlserver) - SQL Database (
sqldb)
Redis
- Redis Cache (
rediscache)
Dns
- DNS Zone (
dnszone) - DNS Record Set (
dnsrecordset)
Private Dns
- Private DNS Zone (
privatednszone) - Private DNS Record Set (
privatednsrecordset) - Private DNS Zone - Network relation (
privatednszonenetworkrelation)
App Containers
- Managed Environment (
managedenvironment) - Container App (
containerapp)
App Service
- Function App (
functionapp)
Logic Apps
- Workflow (
workflow)
Additional Information
Synchronization to Application Classes
The standard connector imports and maintains data within the CMDBuild standard classes and relationships, providing a consistent representation of the data.
As a separate and optional customization activity, organizations may define additional synchronization processes to populate application-specific classes from the imported infrastructure data. Through custom mappings and enrichment rules, connector resources can be associated with organization-specific business objects, services, assets, or other application entities.
This approach supports customer-specific business models, enrichment processes, and classification rules while preserving the standard infrastructure representation provided by the connector.
Known Limitations
- The connector operates in read-only mode.
- Large environments may require increased execution time.
- No real-time synchronization: data is updated only during scheduled runs.
- The plugin is distributed under a Premium license model. Its usage is tied to an active support and maintenance agreement, which is subject to expiration and must be renewed to remain valid.
Deployment Guidelines
Deployment of the connector includes the creation of standard CMDBuild classes and relationships corresponding to supported connector resource types. These structures provide the foundation for storing and organizing synchronized infrastructure information. The deployment process also includes configuration elements required for data visualization and the establishment of scheduled synchronization activities.
Following deployment, it is recommended to validate the configuration by executing an initial synchronization and reviewing the imported data.
Scheduling frequency should be selected according to the scale of the environment, expected rate of infrastructure change, and operational reporting requirements.