Deploy OneAgent on Azure App Service

DESK provides an Azure Site-Extension to install OneAgent on Azure App Services. Site Extensions are the native extension mechanism provided via Kudu, which is the deployment management engine behind Azure App Services.

How the Site Extension for OneAgent works

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

Agent updates aren't automatically provided through OneAgent. For more information about how updates are applied, see How to update OneAgent on App Services

Prerequisites

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

How to retrieve your Environment ID and API Token

Environment ID

1. Login with your DESK account.

2. Select Deploy DESK 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 DESK > 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're using DESK Managed or your cluster traffic should be routed through an ActiveGate, you need to configure the API endpoint used by the extension for downloading OneAgent.

<YourDESKServerURL> and <YourEnvironmentID> need to be replaced. The URL pattern for the API endpoint is as follows: https://<YourDESKServerURL>/e/<YourEnvironmentID>/api

Installation

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

  {
      "apiVersion": "2016-08-01",
      "name": "[parameters('resourceName')]",
      "type": "Microsoft.Web/sites",
      "properties": {
          "name": "[parameters('resourceName')]",
          "siteConfig": {
              "alwaysOn": true,
              "appSettings": [
                { "Name": "DT_TENANT", "Value": "<Environment-ID>" },
                { "Name": "DT_API_TOKEN", "Value": "<API-Token>" },
                { "Name": "DT_API_URL", "Value": "<Server-Url>" }
              ]
          },
          "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('resourceName'))]"
      },
      "dependsOn": [
          "[concat('Microsoft.Web/serverfarms/', parameters('resourceName'))]"
      ],
      "location": "[parameters('location')]",
      "resources": [
          {
              "apiVersion": "2016-08-01",
              "name": "DESK",
              "type": "siteextensions",
              "dependsOn": [
                  "[resourceId('Microsoft.Web/sites', parameters('resourceName'))]"
              ],
              "properties": { }
          }
      ]
  }

Overriding OneAgent configuration

The following parameters can be used to set/override default configurations

Using multiple deployment slots

As Azure App Service deployment slots are treated like full-fledged application service instances, you need to enable the Site-Extension for OneAgent on each deployment slot you want monitored by DESK.

For details on configuring deployment slots, see Microsoft Documentation - Staged Publishing.

If you're using application settings to additionally configure certain OneAgent options, make sure the additional settings are also applied to the deployment slots as well.

Troubleshooting

"No route registered for '/desk/'" when accessing the Site Extension

This error message appears if Kudu hasn't been restarted after the Site Extension was installed.

Solution

To restart, follow step #5 as described in Install the Site Extension for OneAgent.

Alternatively you can restart Kudu directly in the Kudu console or kill the scm worker process in the Kudu process explorer.

Keep in mind, if you've enabled the extension on multiple deployment slots, you have to do this for each deployment slot

"503 Service Unavailable" for Web App and Kudu

The Site Extension for OneAgent registers IIS modules. If registration is complete but the actual IIS module files aren't in place (or corrupt), the App Service may return a 503 Service Unavailable message. Also, the Kudu AppPool will no longer be available, which effectively means that you can no longer fix your installation via Kudu.

Solution

By adding the following setting in Application Settings

WEBSITE_PRIVATE_EXTENSIONS=0

Deactivate all site extensions.

This setting gives you access to Kudu once again. Re-install the site extension and set WEBSITE_PRIVATE_EXTENSIONS=1 (or remove the setting entirely). Following application restart, everything should work again, including DESK monitoring.

Where can I find log-files to troubleshoot

The extension's log-files are located in the extensions-folder: D:\home\SiteExtensions\DESK\

The OneAgent log-files are located in D:\home\SiteExtensions\DESK.Agent\x.xxx.xxx.xxxxxxxx-xxxxxx\log. You may have multiple sub-directories D:\home\SiteExtensions\DESK.Agent\ caused by agent updates.