Manage your Azure connections via CLI

Latest Dynatrace
How-to guide
Published Sep 09, 2026

The Dynatrace CLI (dtctl) enables you to inspect, update, and delete both Azure connections and their associated monitoring configurations from your terminal or automation scripts.

An Azure connection is the foundational link between Dynatrace and your Azure environment, using a dedicated Microsoft Entra ID service principal for authentication and authorization. Each connection is paired one-to-one with a monitoring configuration—the blueprint that governs all monitoring behavior for that connection, such as which Azure services to poll for metrics and which regions to target.

To learn how to create an Azure connection with the CLI, see Create an Azure connection via CLI.

Prerequisites

The commands on this page require dtctl to be installed and authenticated, as described in the prerequisites for creating an Azure connection.

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

Inspect connections and configurations

List all Azure connections and monitoring configurations in your environment:

dtctl get azure connections
dtctl get azure monitoring

Show the details of a specific connection or configuration:

dtctl describe azure connection <AZURE_CONNECTION_ID>
dtctl describe azure monitoring <CONFIGURATION_NAME>

Use dtctl get azure connections to retrieve the <AZURE_CONNECTION_ID> of an existing connection.

You can also find these values in Settings as the connection's HAS Connection ID and Monitoring Configuration ID properties on the Overview tab.

Update connections and configurations

Update the service principal credentials for an existing connection:

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

Update the monitored regions for an existing configuration:

dtctl update azure monitoring --name "<CONFIGURATION_NAME>" --locationFiltering "eastus,westeurope"

Update the monitored feature sets for an existing configuration:

dtctl update azure monitoring \
  --name "<CONFIGURATION_NAME>" \
  --featureSets "microsoft_compute.virtualmachines_essential,microsoft_web.sites_functionapp_essential"

dtctl update azure connection only updates --directoryId and --applicationId. To update the client secret value itself, you must use dtctl apply -f, as described in Roll over a client secret.

For the full set of filtering and enrichment options you can apply through a YAML manifest, see Advanced configuration via YAML.

Delete a connection or configuration

This action is immediate and irreversible. Deleting a monitoring configuration causes telemetry polling downtime and automatically removes its mapped Azure connection.

We recommend thorough testing of any automation scripts before running them in production—particularly scripts that iterate over and delete multiple monitoring configurations and their associated Azure connections.

dtctl delete azure connection <CONNECTION_NAME>
dtctl delete azure monitoring <CONFIGURATION_NAME>

A deleted monitoring configuration does not delete any supporting Azure resources deployed in your environment (for example, logs infrastructure).

You must delete these manually to avoid lingering resources which will incur Azure and Dynatrace costs.

Roll over a client secret

This procedure applies to connections that use client secret authentication. If you want to eliminate ongoing secret rotation, consider migrating to federated identity credentials instead.

Update the connection in Dynatrace before the existing secret expires to avoid a monitoring gap.

Replace the following placeholders with your values:
- <APPLICATION_ID>: Application (client) ID of the Azure service principal
- <CONNECTION_NAME>: Name of the existing Dynatrace Azure connection
- <TENANT_ID>: Microsoft Entra ID tenant (directory) ID
- <NEW_CLIENT_SECRET>: New client secret generated in step 3: save it immediately as it can't be retrieved later
- <OLD_KEY_ID>: The keyId of the old credential captured in step 2
- <AZURE_CONNECTION_ID>: The objectId of the existing Azure connection: Run dtctl get azure connections to retrieve it
List the current credentials for your service principal to capture the keyId of the existing secret.
```
az ad app credential list --id "<APPLICATION_ID>" --output table
```
Note the keyId value. You'll need it in step 6 to remove the old secret.
Generate a new client secret. The --append flag adds the new credential without invalidating the existing one, so Dynatrace monitoring continues uninterrupted during the rollover.
```
az ad app credential reset \
--id "<APPLICATION_ID>" \
--append \
--display-name "Dynatrace rollover $(date +%Y-%m-%d)" \
--query password \
--output tsv
```
The command outputs the new secret. Save this value as <NEW_CLIENT_SECRET>—it can't be retrieved again after this point.

Update your connection YAML with the new secret value and apply it.

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

dtctl apply -f azure-connection-secret.yaml

Verify that the connection is healthy.

dtctl describe azure connection "<AZURE_CONNECTION_ID>"

Once the connection is Healthy in Dynatrace, remove the old secret from Azure.

az ad app credential delete \
--id "<APPLICATION_ID>" \
--key-id "<OLD_KEY_ID>"

Get help

dtctl --help
dtctl update azure connection --help
dtctl update azure monitoring --help

Troubleshooting

dtctl fails with authentication errors

This error occurs when the CLI cannot authenticate against your Dynatrace environment.

Solution:

Verify that your platform token is valid and assigned to the correct Dynatrace environment.
Confirm the token has the required Settings and Extensions scopes, as listed in the prerequisites.
Re-run the command with --dry-run to confirm the target environment before applying changes.