Deploy OneAgent on Azure VM Scale Set

Dynatrace provides a VM Extension to install OneAgent on Azure VM Scale Set. This allows to leverage the native deployment automation features using Azure Resource Manager (ARM).

How the VM-Extension for OneAgent works

The extension doesn't include the OneAgent installer. Instead it uses the Dynatrace REST API to download the latest version from the cluster, unless a OneAgent default version is configured.

Agent updates are provided automatically through the capabilities of OneAgent.


To use the extension, you need the Dynatrace Environment ID and API Token.

How to retrieve Environment ID and API Token

Environment ID

  1. Login with your Dynatrace account.

  2. Select Deploy Dynatrace from the navigation menu.

  3. Click the Set up PaaS integration button. Your environment ID appears in the Environment ID text box.

  4. Click Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.

API Token

The API token is used in combination with your environment ID to download OneAgent. Go to Deploy Dynatrace > Set up PaaS integration to access the InstallerDownload token. For security reasons, it's recommended that you create a discrete token for each environment.

To generate a new token

  1. Click the Generate new token button.

  2. Type in a meaningful name for your token. A meaningful token name might be the name of the platform you want to monitor (for example, azure, cloud-foundry, or openshift). To view and manage your existing tokens, go to Settings -> Integration -> Platform as a Service.

  3. Click Generate to create the token. The newly created token will appear in the list below.

  4. Click Copy to copy the generated token to the clipboard. You can do this at any time by revisiting this page and clicking Show token next to the relevant PaaS token.

Additional configuration parameters

Server Url
If you are using Dynatrace Managed or your cluster traffic should be routed through an Active Gate you need to configure the API endpoint used by the extension for downloading the OneAgent.

If you're using Dynatrace Managed or your communication should be routed through a specific ActiveGate, you need to configure your custom communication endpoint.

The URL pattern for the API endpoint is as follows:



Azure Resource Manager provides a consistent management layer to perform tasks through Azure PowerShell, Azure CLI, Azure portal, REST API, and client SDKs.

Replace all values marked with <...> with your actual values.

az vmss extension set
  --publisher dynatrace.ruxit
  -n "<Extension-Type>"
  -g "<Resource-Group>"
  --vmss-name "<VMSS-Name>"
  --settings "{\"tenantId\":\"<Environment-ID>\",\"token\":\"<API-Token>\", \"server\":\"<Server-Url>\", \"enableLogAnalytics\":\"yes\", \"hostGroup\":\"<Host-Group>\"}"

Note: When using the Azure CLI within PowerShell, the settings have to be formatted as a here-string.

--settings @'"{\"tenantId\":\"<Environment-ID>\",\"token\":\"<API-Token>\"}"'@
Parameter Required Description
Resource-Group yes Name of the resource group the Virtual Machine is deployed to
VMSS-Name yes Name of the VMSS the extension should be installed to.
Extension-Type yes For Windows-based Virtual Machines use oneAgentWindows. For Linux-based ones use oneAgentLinux.
tenantId yes Set environment ID as described in the Prerequisites
token yes Set API token as described in the Prerequisites
server No Optionally provide this property to configure an alternative communication endpoint. See Additional configuration parameters for more information.
enableLogAnalytics No If not set, Log Analytics isn't enabled. Set value to yes to enable Log Analytics
hostGroup No Optionally provide this property to set the hostgroup this VM belongs to. See Host Groups for more information.

After OneAgent is installed, OneAgent immediately starts monitoring your virtual machine. You can check the deployment status within Dynatrace.

OneAgent deployment status

VM-Extension Availability

  • The Dynatrace VM-Extension is available for Windows and Linux in all public Azure regions.
  • Coming soon: Azure Sovereign Clouds such as Azure Government, Azure China as well as Azure Stack