Upgrade and Rollback the Agents

This page describes how to upgrade and rollback the agents. To upgrade and rollback the agents, you find the systemID, find the type of agent you want to upgrade to, and then find the agent version you have available. A systemID is an ID that identifies the Agent Installer system. This functionally is only available using the API. See Agent Installer Platform Service API.

Purge is followed by the installation of the new version of the Agent Installer Platform.

Supported Versions

Versions	Description
>= 21.10.0	An upgrade and rollback is supported for Java Agent Legacy and Machine Agent (Linux).
>= 22.5.0	Upgrade and rollback supported for Java Agent JDK8+ (Linux), along with the OpenTelemetry configuration update. Upgrade and rollback supported for Machine Agent (Windows). Support for Server Visibility (Linux and Windows) and .NET Compatibility (Windows) update using the Machine Agent.

Custom Agent Configurations

The following custom configurations are kept during the upgrade and rollback process:

path: <zero agent path>/java/javaagent/ver***/conf/*.xml

CODE

path: <zero agent path>/zeroagent/agents/machineagent/conf/logging/log4j.xml
path: <zero agent path>/zeroagent/agents/machineagent/conf/controller-info.xml
path: <zero agent path>/zeroagent/agents/machineagent/monitors

CODE

For details on the Machine Agent configurations, see Configure the Machine Agent.

Find the System Information

Find all of the systems that are installed with the Agent Installer. This API provides all systemIDs and hostnames that are present under one account. This API also provides the pervious versions of the monitoring agents, which is used to rollback the Agent Installer.

Format:

GET /maintenance/systemInfos

CODE

Request Example:

curl --location --request GET 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/systemInfos' --header 'Authorization: Bearer {AuthToken}'

CODE

Response Example:

{
  "total": 2,
  "items": [
    {
      "systemId": "1cbcfd90-95ab-4366-b614-1bfab44a9305",
      "hostname": "jboss_host",
      "applicationName": "HelloWorld",
      "rootInstall": true,
      "curVersions": [
        {
          "type": "JAVA",
          "version": "20.3.0.1183"
        }
      ],
      "prevVersions": [
        {
          "type": "JAVA",
          "version": "20.3.0.1183"
        }
      ]
    },
	{
      "systemId": "c44f978d-8db6-452f-9387-9b852d8df03a",
      "hostname": "windows_host",
      "applicationName": "HelloWorld",
      "rootInstall": true,
      "versions": [
         {
            "type": "MACHINE_WINDOWS",
            "version": "22.3.0.3296"
         }
       ],
       "prevVersions": [
        {
          "type": "MACHINE_WINDOWS",
          "version": "22.1.0.3252"
        }
      ]
    }   
  ]
}

JSON

Find the Agent Versions

To find the agent versions, see Find Agent Versions.

Upgrade Agent Versions

Now that you have the systemIDs, hostname, and the latest versions, trigger the upgrade using the API. Once the request is accepted, you receive a maintenanceID. The upgrade happens asynchronously, and you can use the maintenanceID to track the progress of the upgrade.

Specifying the configurations is optional. If none are added, then configurations currently running in the Agent Installer are used. You can upgrade from Java Agent Legacy to Java Agent JKD8+, but you cannot upgrade from Java Agent JDK8+ to Java Agent Legacy.

Format:

POST /maintenance/upgrade/systems

CODE

Request Examples:

{
  "systemDetails": [
    {
      "systemId": "28f7a681-6010-4150-8940-ebee25841215",
      "hostname": "hostname1"
    },
    {
      "systemId": "28f7a681-6010-4150-8940-ebee25841216",
      "hostname": "hostname2"
    }
  ],
  "versions": [
    {
        "type": "JDK8_PLUS",
        "version": "22.4.0.33722"
    },
    {
      "type": "MACHINE",
      "version": "22.4.0.3344"
    }
  ],
  "configurations": {
      "enableOtel": true,
      "otelProperties": {
        "tracesExporter": "otlp,logging",
        "metricsExporter": "otlp,logging",
        "otlpEndpoint": "http://localhost:4317"
      },
      "enableSim": true
  }
}

JSON

{
  "systemDetails": [
    {        
      "systemId": "c44f978d-8db6-452f-9387-9b852d8df03a",
      "hostname": "windows_host"
    }
  ],
  "versions": [
    {
      "type": "MACHINE_WINDOWS",
      "version": "22.4.0.3344"
    }
  ],
  "configurations": {
      "enableSim": true,
      "dotnetCompaibility": true
  }
}

JSON

Input Parameters:

Parameter Name	Parameter Type	Description	Mandatory
`systemDetails.systemId`	Body	`ID` of the Agent Installer system.	Yes
`systemDetails.hostname`		`Hostname` of the Agent Installer system.
`versions.type`		`Type` of the monitoring agents.
`versions.verison`		`Versions` of the monitoring agents to upgrade.
`configurations.enableOtel`		Configuration to enable OpenTelementry for Java Agent JDK8+.	No
`configurations.otelProperties`		Configurations for OpenTelemetry exporter.	Yes, only when `enableOtel` is `true`.
`configurations.otelProperties.tracesExporter`		Configuration for OpenTelemetry traces exporter. Supported values: `otlp`, `logging`.
`configurations.otelProperties.metricsExporter`		Configuration for OpenTelemetry metrics exporter. Supported values: `otlp`, `logging`.
`configurations.otelProperties.otlpEndpoint`		Configuration for OpenTelemetry OTLP Collector endpoint.
`configurations.enableSim`		Configuration to enable Server Visibility for the Machine Agent.	No
`configurations.dotnetCompatibility`		Configuration to enable .NET Compatibility Mode for the Machine Agent.	No

Response Examples:

{
    "maintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fc",
    "operation": "UPGRADE",
    "status": "PENDING",
    "startedAt": "2022-05-06T17:46:04.743Z",
    "updatedAt": "2022-05-06T17:46:04.743Z",
    "applicationName": null,
    "maintAgentVersions": [
        {
            "type": "JDK8_PLUS",
            "version": "22.4.0.33722"
        },
        {
            "type": "MACHINE",
            "version": "22.4.0.3344"
        }
    ],
    "affectedSystemIds": [
        "28f7a681-6010-4150-8940-ebee25841215",
        "28f7a681-6010-4150-8940-ebee25841216"
    ],
    "username": "demo_user",
    "configurations": {
        "enableOtel": true,
        "otelProperties": {
            "tracesExporter": "otlp,logging",
            "metricsExporter": "otlp,logging",
            "otlpEndpoint": "http://localhost:4317"
        },
        "enableSim": true,
        "dotnetCompatibility": null
    }
}

JSON

{
    "maintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fd",
    "operation": "UPGRADE",
    "status": "PENDING",
    "startedAt": "2022-05-11T17:46:04.743Z",
    "updatedAt": "2022-05-11T17:46:04.743Z",
    "applicationName": null,
    "maintAgentVersions": [
        {
            "type": "MACHINE_WINDOWS",
            "version": "22.4.0.3344"
        }
    ],
    "affectedSystemIds": [
        "c44f978d-8db6-452f-9387-9b852d8df03a"
    ],
    "username": "demo_user",
    "configurations": {
        "enableSim": true,
        "dotnetCompatibility": true
    }
}

JSON

Rollback the Upgrade

To rollback the upgrade, trigger the below API with the systemIDs, hostname, and the previous versions. Once the request is accepted, you will receive a response with a maintenanceID.

The rollback happens asynchronously, and uses the maintenanceID. Rollback does not accept any of the configuration inputs, whichever configurations were previously running in the Agent Installer will be used.

Format:

POST /maintenance/rollback/systems

CODE

Request Examples:

curl --location --request POST 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/rollback/systems' \
--header 'Authorization: Bearer {AuthToken}' \
--header 'Content-Type: application/json' \
--data-raw
{
  "systemDetails": [
    {
      "systemId": "28f7a681-6010-4150-8940-ebee25841215",
      "hostname": "hostname1"
    },
    {
      "systemId": "28f7a681-6010-4150-8940-ebee25841216",
      "hostname": "hostname2"
    }
  ],
  "versions": [
    {
      "type": "JAVA",
      "version": "21.7.0.32930"
    }
  ]
}

CODE

curl --location --request POST 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/rollback/systems' \
--header 'Authorization: Bearer {AuthToken}' \
--header 'Content-Type: application/json' \
--data-raw
{
  "systemDetails": [
    {
      "systemId": "c44f978d-8db6-452f-9387-9b852d8df03a",
      "hostname": "windows_host"
    }
  ],
  "versions": [
    {
      "type": "MACHINE_WINDOWS",
      "version": "22.1.0.3252"
    }
  ]
}

CODE

Input Parameters:

Parameter Name	Parameter Type	Description	Mandatory
`systemDetails.systemId`	Body	`ID` of the Agent Installer system.	Yes
`systemDetails.hostname`		`Hostname` of the Agent Installer system.
`versions.type`		`Type` of the monitoring agents.
`versions.verison`		Pervious v`ersions` of the monitoring agents to rollback.

Response Examples:

{
  "maintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fc",
  "operation": "ROLLBACK",
  "status": "PENDING",
  "startedAt": "2021-10-25T18:19:28.607Z",
  "updatedAt": "2021-10-25T18:19:28.607Z",
  "maintAgentVersions": [
    {
      "type": "JAVA",
      "version": "20.3.0.1183"
    }
  ],
  "affectedSystemIds": [
    "d601aacc-97a4-479e-b2b3-db095fef34fc"
  ]
}

JSON

{
  "maintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fd",
  "operation": "ROLLBACK",
  "status": "PENDING",
  "startedAt": "2022-05-12T18:19:28.607Z",
  "updatedAt": "2022-05-12T18:19:28.607Z",
  "maintAgentVersions": [
    {
      "type": "MACHINE_WINDOWS",
      "version": "22.1.0.3252"
    }
  ],
  "affectedSystemIds": [
    "c44f978d-8db6-452f-9387-9b852d8df03a"
  ]
}

JSON

Fetch All Maintenance Request History

Use this API to retrieve the entire upgrade and rollback request history. The history provides the overall maintenance status, and not the status of the individual systems.

Format:

GET /maintenance/history

CODE

Request Example:

curl --location --request GET 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/history' --header 'Authorization: Bearer {AuthToken}'

CODE

Response Example:

{
  "total": 2,
  "items": [
    {
      "maintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fc",
      "operation": "UPGRADE",
      "status": "PENDING",
      "startedAt": "2021-10-25T18:20:55.196Z",
      "updatedAt": "2021-10-25T18:20:55.196Z",
      "maintAgentVersions": [
        {
          "type": "JAVA",
          "version": "20.3.0.1183"
        }
      ],
      "affectedSystemIds": [
        "d601aacc-97a4-479e-b2b3-db095fef34fc"
      ],
      "failedSystemMaintenanceIds": [
        "d601aacc-97a4-479e-b2b3-db095fef34fc"
      ]
    },
    {
      "maintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fd",
      "operation": "UPGRADE",
      "status": "SUCEEDED",
      "startedAt": "2022-05-11T18:20:55.196Z",
      "updatedAt": "2022-05-11T18:20:55.196Z",
      "applicationName": null,
      "maintAgentVersions": [
        {
          "type": "MACHINE_WINDOWS",
          "version": "22.4.0.3344"
        }
      ],
      "affectedSystemIds": [
        "c44f978d-8db6-452f-9387-9b852d8df03a"
      ],
      "failedSystemMaintenanceIds": null
    }   
  ]
}

JSON

Fetch a Specific Maintenance Request Record

Use this API to retrieve a specific upgrade and rollback maintenance record using the maintenanceID. The record provides the overall maintenance status, and not the status of the individual systems.

Format:

GET /maintenance/history/{maintenanceId}

CODE

Request Example:

curl --location --request GET 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/history/{maintenanceId}' --header 'Authorization: Bearer {AuthToken}'

CODE

Input Parameters:

Parameter Name	Parameter Type	Description	Mandatory
`maintenanceId`	Path	`ID` from the rollback and upgrade request.	Yes

Response Examples:

{
    "maintenanceId":"d601aacc-97a4-479e-b2b3-db095fef34fc",
    "operation":"UPGRADE",
    "status":"PENDING",
    "startedAt":"2021-10-25T18:20:55.196Z",
    "updatedAt":"2021-10-25T18:20:55.196Z",
    "maintAgentVersions":[
        {
            "type":"JAVA",
            "version":"20.3.0.1183"
        }
    ],
    "affectedSystemIds":[
        "d601aacc-97a4-479e-b2b3-db095fef34fc"
    ],
    "failedSystemMaintenanceIds":[
        "d601aacc-97a4-479e-b2b3-db095fef34fc"
    ],
    "configurations":{
        "enableOtel":true,
        "otelProperties":{
            "tracesExporter":"otlp,logging",
            "metricsExporter":"otlp,logging",
            "otlpEndpoint":"http://localhost:4317"
        },
        "enableSim":true,
        "dotnetCompatibility":null
    }
}

JSON

{
    "maintenanceId":"d601aacc-97a4-479e-b2b3-db095fef34fd",
    "operation":"UPGRADE",
    "status":"SUCCEEDED",
    "startedAt":"2022-05-11T18:20:55.196Z",
    "updatedAt":"2022-05-11T18:20:55.196Z",     
    "applicationName": null,
    "maintAgentVersions": [
        {
            "type": "MACHINE_WINDOWS",
            "version": "22.4.0.3344"
        }
    ],     
    "affectedSystemIds":[
        "c44f978d-8db6-452f-9387-9b852d8df03a"
    ],
    "failedSystemMaintenanceIds": null,
    "configurations":{
        "enableSim": true,
        "dotnetCompatibility": true
    }
}

JSON

Fetch All System Maintenance Records

Use this API to retrieve all of the system maintenance statuses of a particular maintenance request using the maintenanceId.

When an upgrade for an agent is requested, the Agent Installer automatically upgrades to the latest version. Then, it is represented by the implicitMaintenance field in the response.

The configuration maintenance occurs after the version maintenance. Then, it is represented by the "operation": "CONFIGURATIONS" field in the response.

Format:

GET /maintenance/history/{maintenanceId}/systemMaintenances

CODE

Request Example:

curl --location --request GET 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/history/{maintenanceId}/systemMaintenances' --header 'Authorization: Bearer {AuthToken}'

CODE

Input Parameters:

Parameter Name	Parameter Type	Description	Mandatory
`maintenanceId`	Path	`ID` from the rollback and upgrade request.	Yes

Response Examples:

{
    "total": 3,
    "items": [
        {
            "systemMaintenanceId": "b469f73f-8530-444d-8aa1-256226de0305",
            "systemId": "28f7a681-6010-4150-8940-ebee25841217",
            "hostName": "hostname",
            "startedAt": "1653427594984",
            "updatedAt": "1653427608216",
            "logsAvailable": false,
            "status": "SUCCEEDED",
            "prevAgentVersions": [
                {
                    "type": "ZERO",
                    "version": "20.2.0.1183"
                },
                {
                    "type": "JAVA",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE",
                    "version": "22.2.0.3282"
                }
            ],
            "maintAgentVersions": [
                {
                    "type": "ZERO",
                    "version": "22.5.0.2286"
                }
            ],
            "curAgentVersions": [
                {
                    "type": "ZERO",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "JAVA",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE",
                    "version": "22.3.0.3296"
                }
            ],
            "implicitMaintenance": true,
            "operation": "UPGRADE",
            "configurations": null
        },
        {
            "systemMaintenanceId": "eab11200-cf9a-4ec5-9255-0ddbba320257",
            "systemId": "28f7a681-6010-4150-8940-ebee25841217",
            "hostName": "hostname",
            "startedAt": "1653427594988",
            "updatedAt": "1653427624802",
            "logsAvailable": false,
            "status": "SUCCEEDED",
            "prevAgentVersions": [
                {
                    "type": "ZERO",
                    "version": "20.2.0.1183"
                },
                {
                    "type": "JAVA",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE",
                    "version": "22.2.0.3282"
                }
            ],
            "maintAgentVersions": [
                {
                    "type": "JDK8_PLUS",
                    "version": "22.4.0.33722"
                }
            ],
            "curAgentVersions": [
                {
                    "type": "ZERO",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "JAVA",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE",
                    "version": "22.3.0.3296"
                }
            ],
            "implicitMaintenance": false,
            "operation": "UPGRADE",
            "configurations": null
        },
        {
            "systemMaintenanceId": "913d9929-a94b-472e-830f-ac1a4b68bc40",
            "systemId": "28f7a681-6010-4150-8940-ebee25841217",
            "hostName": "hostname",
            "startedAt": "1653427594989",
            "updatedAt": "1653427642527",
            "logsAvailable": false,
            "status": "SUCCEEDED",
            "prevAgentVersions": [
                {
                    "type": "ZERO",
                    "version": "20.2.0.1183"
                },
                {
                    "type": "JAVA",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE",
                    "version": "22.2.0.3282"
                }
            ],
            "maintAgentVersions": [],
            "curAgentVersions": [
                {
                    "type": "ZERO",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "JAVA",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE",
                    "version": "22.3.0.3296"
                }
            ],
            "implicitMaintenance": false,
            "operation": "CONFIGURATION",
            "configurations": {
                "enableOtel": true,
                "otelProperties": {
                    "tracesExporter": "otlp,logging",
                    "metricsExporter": "otlp",
                    "otlpEndpoint": "http://localhost:4317"
                },
                "enableSim": null,
                "dotnetCompatibility": null
            }
        }
    ]
}

JSON

{
    "total": 3,
    "items": [
        {
            "systemMaintenanceId": "85473377-f46b-4ab8-941f-9c34a555c15a",
            "systemId": "28f7a681-6010-4150-8940-ebee25841217",
            "hostName": "hostname",
            "startedAt": "1653430383251",
            "updatedAt": "1653430397986",
            "logsAvailable": false,
            "status": "SUCCEEDED",
            "prevAgentVersions": [
                {
                    "type": "ZERO_WINDOWS",
                    "version": "20.2.0.1183"
                },
                {
                    "type": "MACHINE_WINDOWS",
                    "version": "22.2.0.3282"
                }
            ],
            "maintAgentVersions": [
                {
                    "type": "ZERO_WINDOWS",
                    "version": "22.5.0.2286"
                }
            ],
            "curAgentVersions": [
                {
                    "type": "ZERO_WINDOWS",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE_WINDOWS",
                    "version": "22.3.0.3296"
                }
            ],
            "implicitMaintenance": true,
            "operation": "UPGRADE",
            "configurations": null
        },
        {
            "systemMaintenanceId": "5e8df22e-3e10-490a-874f-e7a8f9a1cd78",
            "systemId": "28f7a681-6010-4150-8940-ebee25841217",
            "hostName": "hostname",
            "startedAt": "1653430383259",
            "updatedAt": "1653430480344",
            "logsAvailable": false,
            "status": "SUCCEEDED",
            "prevAgentVersions": [
                {
                    "type": "ZERO_WINDOWS",
                    "version": "20.2.0.1183"
                },
                {
                    "type": "MACHINE_WINDOWS",
                    "version": "22.2.0.3282"
                }
            ],
            "maintAgentVersions": [
                {
                    "type": "MACHINE_WINDOWS",
                    "version": "22.4.0.3344"
                }
            ],
            "curAgentVersions": [
                {
                    "type": "ZERO_WINDOWS",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE_WINDOWS",
                    "version": "22.3.0.3296"
                }
            ],
            "implicitMaintenance": false,
            "operation": "UPGRADE",
            "configurations": null
        },
        {
            "systemMaintenanceId": "4327f68b-78b1-4296-abf6-4c63c5012419",
            "systemId": "28f7a681-6010-4150-8940-ebee25841217",
            "hostName": "hostname",
            "startedAt": "1653430383262",
            "updatedAt": "1653430502656",
            "logsAvailable": false,
            "status": "SUCCEEDED",
            "prevAgentVersions": [
                {
                    "type": "ZERO_WINDOWS",
                    "version": "20.2.0.1183"
                },
                {
                    "type": "MACHINE_WINDOWS",
                    "version": "22.2.0.3282"
                }
            ],
            "maintAgentVersions": [],
            "curAgentVersions": [
                {
                    "type": "ZERO_WINDOWS",
                    "version": "20.3.0.1183"
                },
                {
                    "type": "MACHINE_WINDOWS",
                    "version": "22.3.0.3296"
                }
            ],
            "implicitMaintenance": false,
            "operation": "CONFIGURATION",
            "configurations": {
                "enableOtel": null,
                "otelProperties": null,
                "enableSim": true,
                "dotnetCompatibility": true
            }
        }
    ]
}

JSON

Fetch a Specific System Maintenance Record

Use this API to retrieve a specific system maintenance record using the systemMaintenanceId.

Format:

GET /maintenance/systemMaintenances/{systemMaintenanceId}

CODE

Request Example:

curl --location --request GET 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/systemMaintenances/{systemMaintenanceId}' --header 'Authorization: Bearer {AuthToken}'

CODE

Input Parameters:

Parameter Name	Parameter Type	Description	Mandatory
`systemMaintenanceId`	Path	`ID` of the system maintenance activity.	Yes

Response Example:

{
  "systemMaintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fc",
  "systemId": "d601aacc-97a4-479e-b2b3-db095fef34fc",
  "hostName": "HostName",
  "startedAt": "2021-10-25T18:30:52.377Z",
  "updatedAt": "2021-10-25T18:30:52.377Z",
  "logsAvailable": false,
  "status": "SUCCEEDED",
  "prevAgentVersions": [
    {
      "type": "JAVA",
      "version": "20.3.0.1183"
    }
  ],
  "maintAgentVersions": [
    {
      "type": "JAVA",
      "version": "20.3.0.1183"
    }
  ],
  "curAgentVersions": [
    {
      "type": "JAVA",
      "version": "20.3.0.1183"
    }
  ],
  "implicitMaintenance": false
}

JSON

Fetch System Maintenance Failure Log

Use this API to retrieve the failure log of a particular system maintenance activity using the systemMaintenanceId. The max log return is 4,096 characters, if the number exceeds this limit, then logs will be reduced.

Format:

GET /maintenance/systemMaintenances/{systemMaintenanceId}/log

CODE

Request Example:

curl --location --request GET 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/systemMaintenances/{systemMaintenanceId}/log' --header 'Authorization: Bearer {AuthToken}'

CODE

Input Parameters:

Parameter Name	Parameter Type	Description	Mandatory
`systemMaintenanceId`	Path	`ID` of the system maintenance activity.	Yes