Remote configuration management of OneAgents and ActiveGates

Use remote configuration management to help you organize multiple OneAgents or ActiveGates with a single command instead of performing the same actions one by one (whether during installation, by editing configuration files, or by using the oneagentctl command-line tool).

When using remote configuration management, the action is still performed on the respective hosts, but you trigger it and control it centrally from Deployment Status in the Dynatrace web UI or via the Dynatrace API.

Capabilities

With remote configuration management, you can use a single command to carry out any of the following actions on multiple OneAgents or ActiveGates that meet the version requirements.

OneAgent

ActiveGate

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:

Permissions

We recommend that you limit the number of users permitted to use remote configuration management. Multiple users performing configuration at the same time might 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.

IAM permissions

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

With IAM permissions, you can limit a user's activities down to a single configuration action, such as changing only the OneAgent host group assignment.

For more information on Dynatrace IAM permissions, see Working with policies.

Access tokens

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

Web UI procedures

The Dynatrace web UI remote configuration workflow is similar for OneAgents and ActiveGates.

Configure OneAgents

You can assign the following to multiple OneAgents:

To update multiple OneAgents for any of the above

Changing network zones and host groups may require up to 10 minutes to take effect. Removing host properties and tags may require up to seven hours to take effect.

Configure ActiveGates

You can assign the following to multiple ActiveGates:

To update multiple ActiveGates for either of the above

Your changes may require up to 10 minutes to take effect.

API procedures

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

The following is an example of how to assign multiple OneAgents to a host group using the 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.

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.

{
    "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.

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:

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.

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

Run bulk configuration

To run the bulk configuration, issue the following request:

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.

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.