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 the Dynatrace Deployment status page 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:

• 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.

IAM permissions

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

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

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 Manage user permissions with IAM policies.

Access tokens

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

• Write OneAgents (oneAgents.write)—to validate the payload, generate a preview, and trigger a configuration change for OneAgents
• Write ActiveGates (activeGates.write)—to validate the payload, generate a preview, and trigger a configuration change for ActiveGates

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:

• Host group
• Network zone
• Tags
• Properties

To update multiple OneAgents for any of the above

1. From the Dynatrace menu, go to Deployment status > 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.

   After you select OneAgents, an edit pane appears at the bottom of the page.

3. Select the configuration change you want to perform.

   • modify host group
   • modify network zone
   • modify host tags
   • modify host properties

4. Select Run action.

   This starts the Remote configuration management wizard to carry out a configuration change on the selected OneAgents. It does not commit any changes until you select Apply changes and you confirm any required restarts. Before then, you will be able to change or cancel the action.

5. Specify the change you want to make to all the selected OneAgents. Depending on the action you selected, you can:

   • Add or remove the host group assignment
   • Add or remove the network zone assignment
   • Add or remove host tags
   • Add or remove host properties

6. Select Next.

7. Review your changes.

8. Select Apply changes.

9. Select Continue to start the bulk action.

   • OneAgents will be restarted to apply changes to network zone or host group assignments; there is no restart for changes to tags or properties.
   • 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.

10. 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. You can't start another bulk action until the current one is finished.

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:

• ActiveGate group
• Network zone

To update multiple ActiveGates for either of the above

1. From the Dynatrace menu, go to Deployment status > 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, an edit pane appears at the bottom of the page.

4. Select the configuration change you want to perform.

   • modify ActiveGate group
   • modify network zone

5. Select the configuration you want to perform and then select Run action.

   This starts the Remote configuration management wizard to carry out a configuration change on the ActiveGates you have selected. It does not commit any changes until you select Apply changes and you confirm any required restarts. Before then, you will be able to change or cancel the action.

6. Specify the change you want to make to all the selected ActiveGates. Depending on the action you selected, you can:

   • Add or remove the ActiveGate group assignment
   • Add or remove the network zone assignment

7. Select Next.

8. Review your changes.

9. Select Apply changes to run the bulk action.

10. 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.

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.

shellcopydownload
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.

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

shellcopydownload
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:

shellcopydownload
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.

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

Run bulk configuration

To run the bulk configuration, issue the following request:

shellcopydownload
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.

shellcopydownload
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.