Upgrade and Rollback the Agents

This page describes how to upgrade and rollback the agents. To upgrade and rollback agents use the Agent Installer API starting with version 21.10.0.

To upgrade and rollback the agents, you will find the systemID, find the type of agent you want to upgrade to, and find the agent version you have available. A systemID is an ID that identifies the Agent Installer system. Right now, this functionally is available only via the API, and not via the UI. The following configurations are kept during the upgrade and rollback process:

Java Agent configuration (on Linux):

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

CODE

Machine Agent configuration:

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

Purge followed by the installation of the new version of the Agent Installer Platform. For more information on the Agent Installer API, see Agent Installer Platform Service API.

Find the System Information

Find all of the systems that are installed with the Agent Installer. This API can provide 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

Request Example:

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

CODE

Response Example:

{
  "total": 1,
  "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"
        }
      ]
    }
  ]
}

JSON

Find the Agent Versions

Obtain the latest version to upgrade using the API below:

Format:

GET /install/agentVersions?latest=true

Request Example:

curl --location --request GET 'https://demo.saas.appdynamics.com/zero/v1beta/install/agentVersions?latest=true' --header 'Authorization: Bearer {AuthToken}'

CODE

Response Example:

{
    "total": 1,
    "items": [
        {
            "os": "linux",
            "agents": [
                {
                    "agentType": "sun_java",
                    "descriptions": [
                        {
                            "version": "21.8.0.32958",
                            "md5Checksum": "ca5472b4c6691d65f35399bc61a4c180",
                            "s3Path": "download-file/sun-jvm/21.8.0.32958/AppServerAgent-21.8.0.32958.zip",
                            "supportsIbl": false
                        }
                    ]
                },
                {
                    "agentType": "ibm_java",
                    "descriptions": [
                        {
                            "version": "21.8.0.32958",
                            "md5Checksum": "eb35b7dfb1166c7a20586e30d231f337",
                            "s3Path": "download-file/ibm-jvm/21.8.0.32958/AppServerAgent-ibm-21.8.0.32958.zip",
                            "supportsIbl": false
                        }
                    ]
                },
                {
                    "agentType": "machine",
                    "descriptions": [
                        {
                            "version": "21.7.0.3160",
                            "md5Checksum": "24cd76b6144c56c78063112f154b53bd",
                            "s3Path": "download-file/machine-bundle/21.7.0.3160/machineagent-bundle-64bit-linux-21.7.0.3160.zip",
                            "supportsIbl": true
                        }
                    ]
                },
                {
                    "agentType": "infra",
                    "descriptions": [
                        {
                            "version": "21.5.0.1826",
                            "md5Checksum": "6df412722d125dc058d35d8cd39a39df",
                            "s3Path": "download-file/infra-agent/21.5.0.1826/appdynamics-infra-agent-linux-64-21.5.0.1826.zip",
                            "supportsIbl": false
                        }
                    ]
                },
                {
                    "agentType": "zero",
                    "descriptions": [
                        {
                            "version": "21.9.0.569",
                            "md5Checksum": "720597f2dc67ecf0b5f02b45b51d46ee",
                            "s3Path": "download-file/zero-agent/21.9.0.569/appdynamics-zero-agent-21.9.0.569.zip",
                            "supportsIbl": false
                        }
                    ]
                }
            ]
        }
    ]
}

JSON

Upgrade Agent Versions

Now that you have the systemIDs, hostname, and the latest versions, trigger the upgrade with the below API:

The request will be accepted and you will get the response with a maintenanceID. The upgrade will happen asynchronously, and you will use the maintenanceID to track the progress of the upgrade.

Format:

POST /maintenance/upgrade/systems

Request Example:

curl --location --request POST 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/upgrade/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

Input Parameters:

Parameter Name	Parameter Type	Value	Mandatory
systemDetails.systemId	Body	`ID` of the Agent Installer system	Yes
`systemDetails.hostname`	Body	`Hostname` of the Agent Installer system	Yes
versions.type	Body	`Type` of the monitoring agents	Yes
versions.verison	Body	`Versions` of the monitoring agents to upgrade	Yes

Response Example:

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

JSON

Rollback the Upgrade

To rollback the upgrade, trigger the below API with the systemIDs, hostname, and the previous versions.

The request will be accepted and you will get a response with a maintenanceID. The rollback will happen asynchronously, and you will use the maintenanceID to track the progress of the rollback.

Format:

POST /maintenance/rollback/systems

Request Example:

curl --location --request POST 'https://demo.saas.appdynamics.com/zero/v1beta/maintenance/rollback/systems' \
--header 'Authorization: Bearer {AuthToken}' \
--header 'Content-Type: application/' \
--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

Input Parameters:

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

Response Example:

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

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

Request Example:

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

CODE

Response Example:

{
  "total": 1,
  "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"
      ]
    }
  ]
}

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}

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	Value	Mandatory
`maintenanceId`	Path	`ID` from the rollback and upgrade request	Yes

Response Example:

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

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.

Format:

GET /maintenance/history/{maintenanceId}/systemMaintenances

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	Value	Mandatory
`maintenanceId`	Path	`ID` from the rollback and upgrade request	Yes

Response Example:

{
  "total": 1,
  "items": [
    {
      "systemMaintenanceId": "d601aacc-97a4-479e-b2b3-db095fef34fc",
      "systemId": "d601aacc-97a4-479e-b2b3-db095fef34fc",
      "hostName": "HostName",
      "startedAt": "2021-10-25T18:25:14.754Z",
      "updatedAt": "2021-10-25T18:25:14.754Z",
      "logsAvailable": false,
      "status": "success",
      "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 a Specific System Maintenance Record

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

Format:

GET /maintenance/systemMaintenances/{systemMaintenanceId}

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	Value	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": "success",
  "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 the logs will be reduced.

Format:

GET /maintenance/systemMaintenances/{systemMaintenanceId}/log

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	Value	Mandatory
`systemMaintenanceId`	Path	`ID` of the system maintenance activity	Yes