• Home
  • Deploy Dynatrace
  • Remote configuration management of OneAgents and ActiveGates

Remote configuration management of OneAgents and ActiveGates

To change the organization of your OneAgents and ActiveGates into host groups or network zones, instead of performing the same actions one by one on each host—whether during installation, by editing configuration files, or by using the oneagentctl command-line tool—you can manage the configuration of multiple OneAgents and ActiveGates at once.

When using remote configuration management, the action is still performed on respective hosts, but you trigger it and control it centrally from the Dynatrace Deployment status page or by using the Dynatrace API.

Prerequisites

  • Dynatrace version 1.252+
  • OneAgent version 1.237+
  • ActiveGate version 1.237+

Remote configuration management works for OneAgents in Full-Stack and Infrastructure Monitoring mode and for host-based ActiveGates. OneAgent and ActiveGate must be communicating with your environment.

Limitations

Remote configuration management does NOT work with:

  • OneAgent deployed with Dynatrace Operator
  • Application-only OneAgents
  • OneAgents on Solaris
  • Containerized ActiveGates

Permissions

We recommend that you limit the number of users permitted to use remote configuration management. Multiple users performing configuration at the same time may not be aware of one another's actions. This applies to both the web UI and the API. The IAM permissions give you very granular control, so you can avoid having your users run into conflicts.

Configuration scope

You can change the following configuration properties:

OneAgent configuration

  • Host group assignment
  • Network zone assignment

ActiveGate configuration

  • ActiveGate group assignment
  • Network zone assignment

Required permissions

IAM permissions

Users performing remote configuration management need to belong to a group bound to a policy with the following permissions:

  • deployment:activegates.network-zones:write
  • deployment:activegates.groups:write
  • deployment:oneagents.network-zones:write
  • deployment:oneagents.host-groups:write

The permissions are fine-grained so that you can limit the permissions to a single configuration action, such as changing the OneAgent host group assignment only.

For more information on Dynatrace IAM permissions, see Manage policies and groups with Dynatrace IAM.

Access tokens

To make configuration changes using the Dynatrace API, you need an access token with the following scopes:

  • ActiveGate: ActiveGates.write (to validate the payload, generate a preview, and trigger a configuration change)
  • OneAgent: OneAgents.write (to validate the payload, generate a preview, and trigger a configuration change)

Remote configuration management using UI

The configuration workflow is similar for OneAgents and ActiveGates.

Configure OneAgents

  1. From the Dynatrace menu, go to Deployment status and select OneAgents.
  2. Filter for and select the OneAgents you want to configure. You can use the select box in the table header to select all filtered OneAgents or you can select OneAgents individually.
  3. After you select OneAgents, the edit pane appears at the bottom of the page. Select the configuration you want to perform and then select Run bulk action.
  4. Specify the assignment. You have two options:
    • You can assign the selected OneAgents to an existing host group or network zone.
    • You can remove the current assignment.
  5. Select Next.
  6. Review your changes.
  7. Select Apply changes.
  8. Select Continue to start the bulk action. OneAgents will be restarted to apply the configuration. If you change the host group assignment, you need to restart OneAgent-injected processes manually. Restarting the injected processes isn't necessary when changing the network zone assignment.
  9. While the bulk action is being run, the status bar at the top of the Deployment status page informs you about the bulk action's progress. Don't start another bulk action until the current one is finished.

After up to 10 minutes, your changes will be reflected on the Deployment status page.

Configure ActiveGates

  1. From the Dynatrace menu, go to Deployment status and select ActiveGates.
  2. Filter for and select the ActiveGates you want to configure. You can use the select box in the table header to select all filtered ActiveGates or you can select ActiveGates individually.
  3. After you select ActiveGates, the edit pane appears at the bottom of the page. Select the configuration you want to perform and then select Run bulk action.
  4. Specify the assignment. You have two options:
    • You can assign the selected ActiveGates to an existing ActiveGate group or network zone. For an ActiveGate group, you can type a new name to create a new group and assign the selected ActiveGates to it.
    • You can remove the current assignment.
  5. Select Next.
  6. Review your changes.
  7. Select Apply changes to run the bulk action.
  8. While the bulk action is being run, the bar at the top of the Deployment status page informs you about the bulk action's progress. Don't start another bulk action until the current one is finished. ActiveGate restart isn't necessary to apply changes.

After up to 10 minutes, your changes will be reflected on the Deployment status page.

Remote configuration management using Dynatrace API

The Dynatrace API has a set of endpoints that let you manage the configuration remotely in a safe and controlled manner.

See the Remote configuration management API for more information.

OneAgent configuration management example

Below is an example of how to assign multiple OneAgents to a host group using Dynatrace API.

Filter OneAgents to configure

Create payload

Validate payload

Generate preview

Run bulk configuration

Filter OneAgents to configure

Use the OneAgent on a host API endpoint to specify the list of OneAgents for which you want to modify the host assignment.

You can use any of the available OneAgent properties as filtering criteria. For example, to list all OneAgents installed on Windows, issue the following request.

shell
curl --request GET \
  --url 'https://myenvironment.com/api/v2/oneagents?osType=WINDOWS \
  --header 'Authorization: Api-Token <token>'

Create payload

The payload lists OneAgents for which you'll perform the bulk action and the details of the action itself. The example payload below will result in changing the host group assignment to some-host-group for the three listed OneAgents identified by their host IDs.

json
{
    "entities": ["HOST-0000000000000001", "HOST-0000000000000002", "HOST-0000000000000003"],
    "operations": [
        {
            "operation": "SET",
            "attribute": "hostGroup",
            "value": "some-host-group"
        }
    ]
}

Validate payload

Before you run your configuration job, you can validate the payload you created by issuing the following request. In the example below, the payload is passed to the request as the payload.json file.

shell
curl --request POST \
  --url https://myenvironment.com/api/v2/oneagents/remoteConfigurationManagement/validator \
  --header 'Authorization: Api-Token <token>' \
  --header 'Content-Type: application/json' \
  --data @payload.json

A valid payload returns the HTTP 204 response. An invalid payload returns a response indicating details of the violation.

Generate preview

You can generate a preview before performing the actual configuration change. The preview provides information on how many entities are currently configured as described in the payload and how many will be configured this way when the reconfiguration request is sent.

To run a preview, issue the following request:

shell
curl --request POST \
  --url https://myenvironment.com/api/v2/oneagents/remoteConfigurationManagement/preview \
  --header 'Authorization: Api-Token <token>' \
  --header 'Content-Type: application/json' \
  --data @payload.json

The response contains information on how many OneAgents are assigned to the host group and how many will be assigned to the host group after the configuration is complete.

json
{
    "previews": [
        {
            "operation": "SET",
            "attribute": "hostgroup",
            "existingEntitiesCount": 3,
            "targetEntitiesCount": 6
        }
    ]
}

Run bulk configuration

To run the bulk configuration, issue the following request:

shell
curl --request POST \
  --url https://myenvironment.com/api/v2/oneagents/remoteConfigurationManagement \
  --header 'Authorization: Api-Token <token>' \
  --header 'Content-Type: application/json' \
  --data @payload.json

A successful request returns the HTTP 201 response. It means that the configuration job started. The change isn't applied instantly. Each OneAgent first performs the configuration on its own and then sends the information to your environment, and then the Dynatrace cluster updates the host group assignment. It may take up to 10 minutes for the change to be reflected in your environment.

You can validate the change by running the OneAgent on a host API request filtered to the host group to which you just assigned your hosts.

shell
curl --request GET \
  --url 'https://myenvironment.com/api/v2/oneagents?hostGroupName=some-host-group \
  --header 'Authorization: Api-Token <token>'

The response should contain the three host IDs you added to your configuration job.