Create an Azure connection via CLI

Latest Dynatrace
How-to guide
Preview

Prerequisites

1. Azure

Actions in this section must be performed by an Azure administrator with appropriate permissions.

Before running Azure CLI commands, ensure:

You have Azure CLI installed and authenticated (az login)
Your Azure account has one of the following:
- Application Administrator role in Microsoft Entra ID
- Cloud Application Administrator role in Microsoft Entra ID
- microsoft.directory/servicePrincipals/create permission.
  
  And one of the following:
- Owner role at the target scope (subscription or management group)
- User Access Administrator role at the target scope
- A custom role with Microsoft.Authorization/roleAssignments/write permission

For Management Group monitoring scope, you need role assignment permissions at the management group level, not just individual subscriptions.

Identify your Azure monitoring scope

Decide which monitoring scope you'll use and gather the required IDs:

Monitoring scope	Required information
`Management Group`	Management Group ID (found in Azure portal under Management groups)
`Subscription`	Subscription ID (found in Azure portal under Subscriptions)

2. Dynatrace

Create a new platform token for the Dynatrace environment with the following scopes:

extensions:configurations:read
extensions:configurations:write
extensions:definitions:read
settings:schemas:read
settings:objects:read
settings:objects:write
storage:logs:read
storage:metrics:read
storage:events:read

Download and install the Dynatrace CLI (dtctl):
- Linux / macOS:
```
tar -xzf dtctl_*.tar.gz
chmod +x dtctl
sudo mv dtctl /usr/local/bin/
dtctl version
```
MacOS users may see a security warning for unsigned binaries. To resolve it, run sudo xattr -r -d com.apple.quarantine dtctl before moving the binary to your PATH.
- Windows: Extract the zip file, then add dtctl.exe to a directory on your PATH and run dtctl version to verify.

Configure dtctl with your Dynatrace environment and platform token:

dtctl config set-context my-env --environment "https://<YOUR_ENVIRONMENT_ID>.apps.dynatrace.com" --token-ref my-token

dtctl config set-credentials my-token --token "<YOUR_PLATFORM_TOKEN>"

Verify your configuration:

dtctl config view

Dynatrace is designed to support large and complex Azure environments. By default, a Dynatrace environment can accommodate up to 3,000 Azure connections.

This is a soft limit. If you plan to exceed it (per Dynatrace environment), please open a support request to increase this limit.

Get started

A complete Azure monitoring setup requires two resources:

Azure connection
Monitoring configuration

The shell commands on this page use \ for line continuation (bash/zsh). On Windows, replace \ with a backtick (`) in PowerShell, or ^ in Command Prompt.

Create a new Azure connection with CLI

The monitoring configuration requires an Azure connection to access your Azure environment. Dynatrace supports two authentication methods:

Federated identity: Uses federated identity credentials (more secure, passwordless authentication).
Client secret: Uses a service principal with client secret (password-based authentication).

Federated identity authentication method

Recommended

Federated identity credentials provide passwordless authentication and are more secure than client secrets.

This is the recommended approach for production environments.

1. Create an empty Azure connection

Create the Azure connection in Dynatrace.

dtctl automatically generates and displays the exact issuer, subject, and audience values you will need in step 2.

dtctl create azure connection --name "<CONNECTION_NAME>" --type federatedIdentityCredential

Save the connection object ID from the command output—you will need it when configuring the federated credential in Azure.

2. Configure federated credentials in Azure

Configure the federated identity credential in Microsoft Entra ID using the values displayed in step 1.

Register a new application in your Microsoft Entra ID tenant. Learn more: How to register an app in Microsoft Entra ID

Placeholder Description
<CONNECTION_NAME>
Descriptive name for the connection (used in Dynatrace)
```
az ad sp create-for-rbac \
--name "<CONNECTION_NAME>" \
--create-password false \
--query "{CLIENT_ID:appId, TENANT_ID:tenant}" \
--output table
```

Placeholder	Description
`<CONNECTION_NAME>`	Descriptive name for the connection (used in Dynatrace)

Create a federated credential for the Microsoft Entra ID app using the issuer, subject, and audience displayed in step 1. Dynatrace uses this for OIDC token exchange. Learn more: az ad app federated-credential.

Placeholder	Description
`<CLIENT_ID>`	Application (client) ID from the previous step
`<CONNECTION_NAME>`	Descriptive name for the federated credential
`<CONNECTION_ID_FROM_STEP_1>`	The connection object ID returned in step 1
`<DYNATRACE_TENANT_ID>`	Your Dynatrace tenant ID (for example, `abc12345`)

az ad app federated-credential create \
--id "<CLIENT_ID>" \
--parameters '{"name": "<CONNECTION_NAME>-Federated-Credential", \
"issuer": "https://token.dynatrace.com", \
"subject": "dt:connection-id/<CONNECTION_ID_FROM_STEP_1>", \
"audiences": ["<DYNATRACE_TENANT_ID>.apps.dynatrace.com/svc-id/com.dynatrace.da"]}'

Assign the Monitoring Reader Azure RBAC built-in role to the service principal at the appropriate monitoring scope.

For Management Group scope:

az role assignment create \
--assignee "<CLIENT_ID>" \
--role "Monitoring Reader" \
--scope "/providers/Microsoft.Management/managementGroups/<MANAGEMENT_GROUP_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"

For Subscription scope:

az role assignment create \
--assignee "<CLIENT_ID>" \
--role "Monitoring Reader" \
--scope "/subscriptions/<SUBSCRIPTION_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"

Verify the role assignment was successful. You should see the Monitoring Reader role listed at your specified scope.
```
az role assignment list \
--assignee "<CLIENT_ID>" \
--output table
```

3. Update the Azure connection with service principal details

Update the connection with the tenant ID and application ID returned in step 2.

Placeholder	Description
`<CONNECTION_NAME>`	The connection name used in step 1
`<TENANT_ID>`	Microsoft Entra ID tenant (directory) ID
`<CLIENT_ID>`	Application (client) ID of the service principal

dtctl update azure connection --name "<CONNECTION_NAME>" --directoryId "<TENANT_ID>" --applicationId "<CLIENT_ID>"

If the command returns an AADSTS70025 error, the federated credential is still propagating in Microsoft Entra ID. Wait a few seconds and retry.

Alternative: Apply via YAML

For GitOps or infrastructure-as-code workflows, you can apply the same update using a YAML file instead of CLI flags. Populate the placeholders and run dtctl apply:

Placeholder	Description
`<CONNECTION_OBJECT_ID>`	The connection object ID returned in step 1
`<CONNECTION_NAME>`	The connection name used in step 1
`<TENANT_ID>`	Microsoft Entra ID tenant (directory) ID
`<CLIENT_ID>`	Application (client) ID of the service principal

schemaId: builtin:hyperscaler-authentication.connections.azure
scope: environment
objectid: <CONNECTION_OBJECT_ID>
value:
  name: "<CONNECTION_NAME>"
  type: federatedIdentityCredential
  federatedIdentityCredential:
    directoryId: "<TENANT_ID>"
    applicationId: "<CLIENT_ID>"
    consumers:
      - SVC:com.dynatrace.da

dtctl apply -f azure-connection-federated.yaml

After successful completion, proceed to Create a new Azure monitoring configuration using the CLI.

Client secret authentication method

Client secret authentication uses a password-based credential. Consider using federated identity credentials for improved security in production environments.

When generating a client secret, Microsoft recommends using an expiration duration of less than 12 months for enhanced security.

Ensure client secrets are updated in Dynatrace before they expire.

Register a new application in your Microsoft Entra ID tenant. This creates a service principal with a client secret.

See How to register an app in Microsoft Entra ID to learn more.

Placeholder Description
<CONNECTION_NAME>
Descriptive name for the connection (used in Dynatrace)
```
az ad sp create-for-rbac \
--name "<CONNECTION_NAME>" \
--query "{CLIENT_ID:appId, TENANT_ID:tenant, CLIENT_SECRET:password}" \
--output table
```

Placeholder	Description
`<CONNECTION_NAME>`	Descriptive name for the connection (used in Dynatrace)

Assign the Monitoring Reader Azure RBAC built-in role to the service principal at the appropriate monitoring scope.

For Management Group scope:

az role assignment create \
--assignee "<CLIENT_ID>" \
--role "Monitoring Reader" \
--scope "/providers/Microsoft.Management/managementGroups/<MANAGEMENT_GROUP_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"

For Subscription scope:

az role assignment create \
--assignee "<CLIENT_ID>" \
--role "Monitoring Reader" \
--scope "/subscriptions/<SUBSCRIPTION_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"

Verify the role assignment was successful. You should see the Monitoring Reader role listed at your specified scope.
```
az role assignment list \
--assignee "<CLIENT_ID>" \
--output table
```

Create the Azure connection.

Populate the placeholders in the YAML file:

schemaId: builtin:hyperscaler-authentication.connections.azure
scope: environment
value:
  name: "<CONNECTION_NAME>"
  type: clientSecret
  clientSecret:
    directoryId: "<TENANT_ID>"
    applicationId: "<CLIENT_ID>"
    clientSecret: "<CLIENT_SECRET>"
    consumers:
      - SVC:com.dynatrace.da

Then apply it:

dtctl apply -f azure-connection-secret.yaml

The command confirms successful creation and displays the connection object ID. Save this ID—you will need it if creating the monitoring configuration via YAML.

Create a new Azure monitoring configuration with CLI

The monitoring configuration defines which Azure services to monitor, which regions to poll, and how to filter and enrich telemetry data.

Basic monitoring configuration

Create a monitoring configuration with defaults. By default, dtctl enables all *_essential feature sets and all Azure regions.

Placeholder	Description
`<CONFIGURATION_NAME>`	Name of the monitoring configuration (letters, numbers, hyphens only; must start with a letter)
`<CONNECTION_NAME>`	Name of the Azure connection created in the previous step

dtctl create azure monitoring --name "<CONFIGURATION_NAME>" --credentials "<CONNECTION_NAME>"

To restrict the monitored regions or feature sets, use the optional flags:

Flag	Description
`--locationFiltering`	Comma-separated Azure region names to monitor (for example, `eastus,westeurope,northeurope`)
`--featureSets`	Comma-separated feature set names to enable

Run these commands to discover valid values for each flag:

dtctl get azure monitoring-locations     # Lists all valid Azure region names
dtctl get azure monitoring-feature-sets  # Lists all valid feature set names

Required

To allow telemetry signals in context and inventory on all relevant regions, the topology service must poll for topology signals on all regions where any signal is ingested.

Advanced configuration via YAML

For more granular control—including subscription filtering, tag filtering, tag enrichment, and Dynatrace label mapping—create a YAML file and use dtctl apply.

The monitoring configuration supports additional filtering and enrichment options to customize what resources are monitored and how data is enriched in Dynatrace.

Subscription filtering

Control which Azure subscriptions to monitor using subscriptionfilteringmode and subscriptionFiltering.

Include mode: Monitor only specified subscriptions:

subscriptionfilteringmode: INCLUDE
subscriptionFiltering:
  - 00000000-0000-0000-0000-000000000001
  - 00000000-0000-0000-0000-000000000002

Exclude mode: Monitor all subscriptions except specified ones:

subscriptionfilteringmode: EXCLUDE
subscriptionFiltering:
  - 00000000-0000-0000-0000-000000000001

Tag filtering

Filter which Azure resources to monitor based on their tags using tagfiltering.

Include mode: Monitor only resources with matching tags:

tagfiltering:
  - key: environment
    value: production
    condition: INCLUDE
  - key: monitoring
    value: enabled
    condition: INCLUDE

Exclude mode: Monitor all resources except those with matching tags:

tagfiltering:
  - key: monitoring
    value: disabled
    condition: EXCLUDE

Tag enrichment

Enrich Dynatrace signals with Azure resource tags by specifying tag keys in tagenrichment. The specified Azure tag keys will be added as attributes to signals in Dynatrace.

tagenrichment:
  - environment
  - cost-center
  - application
  - team

Label mapping for cost allocation and security context

Map Azure tags or literal values to Dynatrace labels using dtlabelsenrichment. This is particularly useful for cost allocation (dt.cost.costcenter, dt.cost.product) and security context (dt.security_context).

Using literal values

dtlabelsenrichment:
  dt.security_context:
    literal: production
    tagkey: ""
  dt.cost.costcenter:
    literal: CC-12345
    tagkey: ""
  dt.cost.product:
    literal: MyProduct
    tagkey: ""

Using Azure tags

dtlabelsenrichment:
  dt.security_context:
    literal: ""
    tagkey: environment      # Azure tag key whose value is used
  dt.cost.costcenter:
    literal: ""
    tagkey: cost-center
  dt.cost.product:
    literal: ""
    tagkey: product-name

When using tagkey, the value of the specified Azure tag will be used as the label value in Dynatrace. Leave literal empty when using tagkey, and vice versa.

Complete example with advanced options

# objectid: <EXISTING_CONFIG_ID_IF_UPDATING>
scope: integration-azure
value:
  enabled: true
  description: <CONFIGURATION_NAME>
  azure:
    deploymentscope: SUBSCRIPTION
    configurationmode: ADVANCED
    deploymentmode: AUTOMATED
    subscriptionfilteringmode: INCLUDE
    subscriptionFiltering:
      - 00000000-0000-0000-0000-000000000001
      - 00000000-0000-0000-0000-000000000002
    credentials:
      - enabled: true
        description: <CONNECTION_NAME>
        connectionid: <AZURE_CONNECTION_OBJECT_ID>
        serviceprincipalid: <CLIENT_ID>
        type: FEDERATED    # Use SECRET for clientSecret connections
    locationfiltering:
      - eastus
      - westeurope
      - northeurope
      # Run 'dtctl get azure monitoring-locations' for the complete list
    tagfiltering:
      - key: environment
        value: production
        condition: INCLUDE
      - key: monitoring
        value: disabled
        condition: EXCLUDE
    tagenrichment:
      - environment
      - cost-center
    dtlabelsenrichment:
      dt.cost.costcenter:
        literal: ""
        tagkey: cost-center
      dt.cost.product:
        literal: MyProduct
        tagkey: ""
      dt.security_context:
        literal: ""
        tagkey: environment
  featuresets:
    - microsoft_compute.virtualmachines_essential
    - microsoft_storage.storageaccounts_essential
    - microsoft_web.sites_functionapp_essential
    # Run 'dtctl get azure monitoring-feature-sets' for the complete list

dtctl apply -f azure-monitoring-config.yaml

If you encounter errors, validate that:

The platform token has the required permissions
The connection object ID is correct, and all required fields are populated.

After successful completion, go to Settings > Cloud and virtualization > Azure (Preview). The newly created connection should be visible and in healthy state within a few minutes.

Additional CLI capabilities

Inspect and update existing connections and configurations

# List all Azure connections and monitoring configurations
dtctl get azure connections
dtctl get azure monitoring

# Show details of a specific connection or configuration
dtctl describe azure connection <CONNECTION_NAME>
dtctl describe azure monitoring <CONFIGURATION_NAME>

# Update service principal credentials for an existing connection
dtctl update azure connection --name "<CONNECTION_NAME>" --directoryId "<TENANT_ID>" --applicationId "<CLIENT_ID>"

# Update monitored regions for an existing configuration
dtctl update azure monitoring --name "<CONFIGURATION_NAME>" --locationFiltering "eastus,westeurope"

# Update monitored feature sets for an existing configuration
dtctl update azure monitoring \
  --name "<CONFIGURATION_NAME>" \
  --featureSets "microsoft_compute.virtualmachines_essential,microsoft_web.sites_functionapp_essential"

# Delete a connection or configuration
dtctl delete azure connection <CONNECTION_NAME>
dtctl delete azure monitoring <CONFIGURATION_NAME>

Get help

dtctl --help
dtctl create azure connection --help
dtctl create azure monitoring --help

Add --dry-run to any command to preview what would be executed without making any changes.

What's next?

Go to Clouds. Azure resources with telemetry should start to appear shortly.

Supported Azure services

For a full list of supported Azure services, including topology relationships and available metric collection sets, see Supported Azure services.

Troubleshooting

Error: "Authorization_RequestDenied" when creating the service principal

This error occurs when your Azure identity lacks permission to create applications in Microsoft Entra ID.

Solution: Ask your Azure administrator to grant you the Application Administrator role or create the service principal on your behalf.

Error: "AuthorizationFailed" when assigning the Monitoring Reader role

This error occurs when your Azure identity lacks permission to assign roles at the specified scope.

Solution:

Ensure you have Owner or User Access Administrator role at the target subscription or management group.
For Management Group scope, confirm you have permissions at the management group level, not just individual subscriptions.

Error: "AADSTS70025" when updating the Azure connection

This error indicates that Microsoft Entra ID has not yet propagated the federated credential configured in step 2.

Solution: Wait a few seconds for propagation to complete, then retry the dtctl update azure connection command.

dtctl fails with authentication errors

This error occurs when the Dynatrace platform token is invalid or lacks required permissions.

Solution:

Run dtctl config view to verify your environment URL and token reference are configured correctly.
Verify your platform token is valid and has not expired.
Ensure the token has the required scopes: settings:schemas:read, settings:objects:read, settings:objects:write.
Confirm you are using the correct Dynatrace environment URL.