This guide provides a full list of tasks for managing plugins and extensions in Elasticsearch Service, using the API.

Create an extensionedit

There are two methods to create an extension. You can:

These two examples are for the plugin extension type. For bundles, change extension_type to bundle.

For plugins, version must match (exactly) the elasticsearch.version field defined in the plugin’s plugin-descriptor.properties file. Check Help for plugin authors for details. For plugins larger than 5GB, the plugin-descriptor.properties file needs to be at the top of the archive. This ensures that the our verification process is able to detect that it is an Elasticsearch plugin; otherwise the plugin will be rejected by the API. This order can be achieved by specifying at time of creating the ZIP file: zip -r name-of-plugin.zip plugin-descriptor.properties *.

For bundles, we recommend setting version using wildcard notation that matches the major version of the Elasticsearch deployment. For example, if Elasticsearch is on version 8.4.3, simply set 8.* as the version. The value 8.* means that the bundle is compatible with all 8.x versions of Elasticsearch.

Option 1: Stream the file from a publicly-accessible download URL

curl -X POST \
  https://api.elastic-cloud.com/api/v1/deployments/extensions \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
   "download_url" : "https://my_site/custom-plugin-8.4.3.zip",
   "extension_type" : "plugin",
   "name" : "custom-plugin",
   "version" : "8.4.3"
}'

The single POST request creates an extension with the metadata, validates, and streams the file from the download_url specified. The accepted protocols for download_url are http and https.

Option 2: Upload the file from a local file path

This option requires a two step process. First, create the metadata for the extension:

curl -X POST \
  https://api.elastic-cloud.com/api/v1/deployments/extensions \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "extension_type": "plugin",
    "name": "custom-plugin",
    "version" : "8.4.3"
}'

{
    "url": "repo://4226448541",
    "version": "8.4.3",
    "extension_type": "plugin",
    "id": "4226448541",
    "name": "custom-plugin"
}

The response returns a url you can reference later in the plan (the numeric value in the url is the EXTENSION_ID). Use this EXTENSION_ID in the following PUT call:

curl -v -X PUT "https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID" \
-H 'Content-type:application/zip' \
-H "Authorization: ApiKey $CLOUD_API_KEY" \
-H 'Expect:' \
-T "/path_to/custom-plugin-8.4.3.zip"

The above PUT request uploads the file from the local path specified. This request is synchronous. An HTTP 200 response indicates that the file has been successfully uploaded and is ready for use.

{
    "url": "repo://2286113333",
    "version": "8.4.3",
    "extension_type": "plugin",
    "id": "2286113333",
    "name": "custom-plugin"
}

Add an extension to a deployment planedit

Once the extension is created and uploaded, you can add the extension using its EXTENSION_ID in an update deployment API call.

The following are examples of a GCP plan. Your specific deployment plan will be different. The important parts related to extensions are in the user_plugins object.

{
    "name": "Extensions",
    "prune_orphans": false,
    "resources": {
        "elasticsearch": [
            {
                "region": "gcp-us-central1",
                "ref_id": "main-elasticsearch",
                "plan": {
                    "cluster_topology": [

                      ...

                    ],
                    "elasticsearch": {
                        "version": "8.4.3",
                        "enabled_built_in_plugins": [ ],
                      "user_bundles": [
                        {
                          "name": "custom-plugin",
                          "url": "repo://2286113333",
                          "elasticsearch_version": "8.4.3"
                        }
                      ]
                    },
                    "deployment_template": {
                        "id": "gcp-storage-optimized-v3"
                    }
                }
            }
        ]
    }
}

You can use the cat plugins API to confirm that the plugin has been deployed successfully to Elasticsearch.

The previous examples are for plugins. For bundles, use the user_bundles construct instead.

      "user_bundles": [
              {
                    "elasticsearch_version": "8.*",
                    "name": "custom-bundle",
                    "url": "repo://5886113212"
              }
       ]

Get an extensionedit

You can use the GET call to retrieve information about an extension.

To list all extensions for the account:

curl -X GET \
  https://api.elastic-cloud.com/api/v1/deployments/extensions \
  -H 'Content-Type: application/json' \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \

To get a specific extension:

curl -X GET \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \
  -H 'Content-Type: application/json' \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \

The previous GET calls support an optional include_deployments parameter. When set to true, the call also returns the deployments that currently have the extension in-use:

curl -X GET \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID?include_deployments=true \
  -H 'Content-Type: application/json' \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \

For example, the previous call returns:

{
    "name": "custom-plugin",
    "url": "repo://2286113333",
    "extension_type": "plugin",
    "deployments": [
        "f91f3a9360a74e9d8c068cd2698c92ea"
    ],
    "version": "8.4.3",
    "id": "2286113333"
}

Update the name of an existing extensionedit

To update the name of an existing extension, simply update the name field without uploading a new file. You do not have to specify the download_url when only making metadata changes to an extension.

Example using the Option 1 create an extension method:

curl -X POST \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
   "extension_type" : "plugin",
    "name": "custom-plugin-07012020",
   "version" : "8.4.3"
}'

Example using the Option 2 create an extension method:

curl -X POST \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
   "extension_type" : "plugin",
    "name": "custom-plugin-07012020",
   "version" : "8.4.3"
}'

Updating the name of an existing extension does not change its EXTENSION_ID.

Update the type of an existing extensionedit

Updating extension_type has no effect. You cannot change the extension’s type (plugin versus bundle) after the initial creation of a plugin.

Update the version of an existing bundleedit

For bundles, we recommend setting version using wildcard notation that matches the major version of the Elasticsearch deployment. For example, if Elasticsearch is on version 8.4.3, simply set 8.* as the version. The value 8.* means that the bundle is compatible with all 7.x versions of Elasticsearch.

For example, if the bundle was previously uploaded with the version 8.4.2, simply update the version field. You no longer have to specify the download_url when only making metadata changes to a bundle.

Example using the Option 1 create an extension method:

curl -X POST \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
   "extension_type" : "bundle",
    "name": "custom-bundle",
   "version" : "8.*"
}'

Example using the Option 2 create an extension method:

curl -X POST \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "extension_type" : "bundle",
    "name": "custom-bundle",
    "version" : "8.*"
}'

Updating the name of an existing extension does not change its EXTENSION_ID.

Update the version of an existing pluginedit

For plugins, version must match (exactly) the elasticsearch.version field defined in the plugin’s plugin-descriptor.properties file. Check Help for plugin authors for details. If you change the version, the associated plugin file must also be updated accordingly.

Update the file associated to an existing extensionedit

You may want to update an uploaded file for an existing extension without performing an Elasticsearch upgrade. If you are updating the extension to prepare for an Elasticsearch upgrade, check the Upgrade Elasticsearch scenario later on this page.

This example is for the plugin extension type. For bundles, change extension_type to bundle.

If you used Option 1 to create the extension, simply re-run the POST request with the download_url pointing to the location of your updated extension file.

curl -X POST \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
   "download_url" : "https://my_site/custom-plugin-8.4.3-10212022.zip",
   "extension_type" : "plugin",
    "name": "custom-plugin-10212022",
   "version" : "8.4.3"
}'

If you used Option 2 to create the extension, simply re-run the PUT request with the file parameter pointing to the location of your updated extension file.

curl -v -X PUT "https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID" \
-H 'Content-type:application/zip' \
-H "Authorization: ApiKey $CLOUD_API_KEY" \
-H 'Expect:' \
-T "/path_to/custom-plugin-8.4.3-10212022.zip"

Updating the file of an existing extension or bundle does not change its EXTENSION_ID.

Upgrade Elasticsearchedit

When you upgrade Elasticsearch in a deployment, you must ensure that:

To prepare existing bundle and update the plan:

To create a new plugin and update the plan:

Unlike bundles, plugins must match the Elasticsearch version down to the patch level (for example, 8.4.3). When upgrading Elasticsearch to a new patch, minor, or major version, update the version in the extension metadata and update the extension file. The following example updates an existing plugin and upgrades the Elasticsearch deployment from version 8.3.0 to 8.4.3.

Delete an extensionedit

You can delete an extension simply by calling a DELETE against the EXTENSION_ID of interest:

curl -X DELETE \
  https://api.elastic-cloud.com/api/v1/deployments/extensions/EXTENSION_ID \
  -H "Authorization: ApiKey $CLOUD_API_KEY" \
  -H 'Content-Type: application/json'

Only extensions not currently referenced in a deployment plan can be deleted. If you attempt to delete an extension that is in use, you will receive an HTTP 400 Bad Request error like the following, indicating the deployments that are currently using the extension.

{
    "errors": [
        {
            "message": "Cannot delete extension [EXTENSION_ID]. It is used by deployments [DEPLOYMENT_NAME].",
            "code": "extensions.extension_in_use"
        }
    ]
}

To remove an extension reference from a deployment plan, simply update the deployment with the extension reference deleted from the user_plugins or user_bundles arrays. Check Add an extension to a deployment plan for where these are specified in the plan.