Perform Upgrade API
Introduced 2.14
The Perform Upgrade API allows you to upgrade your Security plugin configuration components. This API is typically used after identifying necessary upgrades with the Check for Upgrades API. It updates your configuration components to ensure compatibility with the current version of the Security plugin.
This API adds and updates resources on the cluster’s existing security configuration from the configuration bundled with the installed version of the Security plugin. The bundled configuration files are located in the <OPENSEARCH_HOME>/security/config directory. Default configuration files are updated when OpenSearch is upgraded, whereas the cluster configuration is only updated by cluster operators, so this API lets an operator upgrade missing defaults and stale default definitions.
Endpoints
POST /_plugins/_security/api/_upgrade_perform
Request body fields
The request body is optional. It is a JSON object with the following fields.
| Property | Data type | Description |
|---|---|---|
config | Array of Strings | A list of specific configuration components to upgrade. If omitted, all components requiring upgrades will be processed. Valid values include roles, rolesmapping, actiongroups, config, internalusers, and tenants. |
Example request
POST /_plugins/_security/api/_upgrade_perform
{
"configs": [
"roles"
]
}
Example response
The upgrades object lists the changes that were applied:
{
"status": "OK",
"upgrades": {
"roles": {
"add": [
"flow_framework_full_access"
]
}
}
}
If the named configuration is already current, the request fails with 400 Bad Request:
{
"status": "BAD_REQUEST",
"message": "Unable to upgrade, no differences found in 'roles' config"
}
Response body fields
The response body is a JSON object with the following fields.
| Property | Data type | Description |
|---|---|---|
status | String | The status of the request. A successful request returns OK. |
upgrades | Object | A container for the upgrade results, organized by configuration type, such as roles. Each changed configuration type is represented as a key in this object. |
Response body fields: upgrades
Each configuration type in upgrades maps to an object whose keys are the actions applied to that type, such as add or modify. Each action maps to a list of the names of the objects modified by the upgrade.