« Upload custom plugins and bundles Custom endpoint aliases »
Elastic Docs ›Elasticsearch Service Documentation ›Preparing a deployment for production ›Add plugins and extensions

Managing plugins and extensions through the API

edit

Managing plugins and extensions through the API

edit

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

Create an extension

edit

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

  1. Stream the file from a publicly-accessible download URL.
  2. Upload the file from a local file path.

For plugins larger than 200MB the download URL option must be used. Plugins larger than 8GB cannot be uploaded with either method.

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.

The download_url must be directly and publicly accessible. There is currently no support for redirection or authentication unless it contains security credentials/tokens expected by your HTTP service as part of the URL. Otherwise, use the following Option 2 to upload the file from a local path.

When the file is larger than 5GB, the request may timeout after 2-5 minutes, but streaming will continue on the server. Check the Extensions page in the Cloud UI after 5-10 minutes to make sure that the plugin has been created. A successfully created plugin will contain correct name, type, version, size, and last modified information.

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"

When using curl, always use the -T option. DO NOT use -F (we have seen inconsistency in curl behavior across systems; using -F can result in partially uploaded or truncated files).

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 plan

edit

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 extension

edit

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 extension

edit

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 extension

edit

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 bundle

edit

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 plugin

edit

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 extension

edit

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"

If you are not making any other plan changes and simply updating an extension file, you need to issue a no-op plan so that Elasticsearch will make use of this new file. A no-op (no operation) plan triggers a rolling restart on the deployment, applying the same (unchanged) plan as the current plan.

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

Upgrade Elasticsearch

edit

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

  • Bundles are on versions that are compatible with the Elasticsearch version that you are upgrading to.
  • Plugins match (exactly) the Elasticsearch upgrade version.

To prepare existing bundle and update the plan:

  1. Update the bundle version to be compatible with the Elasticsearch upgrade version.

    Bundles using wildcard notation for versions (for example, 7.*, 8.*) in their extension metadata are compatible with all minor versions of the same Elasticsearch major version. In other words, if you are performing a patch (for example, from 8.4.2 to 8.4.3) or a minor (for example 8.3.0 to 8.4.3) version upgrade of Elasticsearch and you are already using 8.* as the version for the extension, you are ready for the Elasticsearch upgrade and can proceed to Step 2.

    However, if you are using a specific version for bundles, or upgrading to a major version, you must update the metadata of the extension to specify the matching Elasticsearch version that you are upgrading to, or use the wildcard syntax described in the previous paragraph. For example, if you are upgrading from version 7.x to 8.x, set version to 8.* before the upgrade. Refer to Update the version of an existing bundle.

  2. Update the bundle reference as part of an upgrade plan.

    Submit a plan change that performs the following operations in a single update deployment API call:

    • Upgrade the version of Elasticsearch to the upgrade version (for example, 8.4.3).
    • Update reference to the existing bundle to be compatible with Elasticsearch upgrade version (for example, 8.*).

    This triggers a rolling upgrade plan change to the later Elasticsearch version and updates the reference to the bundle at the same time.

    The following example shows the upgrade of an Elasticsearch deployment and its bundle. You can also upgrade other deployment resources within the same plan change.

    Update resources.elasticsearch.plan.elasticsearch.version and resources.elasticsearch.plan.cluster_topology.elasticsearch.user_bundles.elasticsearch_version accordingly.

    {
    "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": [
                            {
                                  "elasticsearch_version": "7.*",
                                  "name": "custom-bundle",
                                  "url": "repo://5886113212"
                            }
                        ]

                    },
                    "deployment_template": {
                        "id": "gcp-storage-optimized-v3"
                    }
                }
            }
        ]
    }
}

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.

  1. Create a new plugin that matches the Elasticsearch upgrade version.

    Follow the steps in Get an extension to create a new extension with a version metadata field and the plugin’s elasticsearch.version field in plugin-descriptor.properties that matches the Elasticsearch upgrade version (for example, 8.4.3).

  2. Remove the old plugin and add the new plugin to the upgrade plan.

    Submit a plan change that performs the following operations in a single update deployment API call:

    • Upgrade the version of Elasticsearch to the upgrade version (for example, 8.4.3).
    • Remove reference to the the plugin on the older version (for example, 8.3.0) from the plan.
    • Add reference to the new plugin on the upgrade version (for example, 8.4.3) to the plan.

    This triggers a rolling upgrade plan change to the later Elasticsearch version, removes reference to the older plugin, and deploys your updated plugin at the same time.

    The following example shows the upgrade of an Elasticsearch deployment and its plugin. You can also upgrade other deployment resources within the same plan change.

    Update deployment plans, update resources.elasticsearch.plan.elasticsearch.version and resources.elasticsearch.plan.cluster_topology.elasticsearch.user_plugins.elasticsearch_version accordingly.

    {
    "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_plugins": [
                           {
                                "elasticsearch_version": "8.4.3",
                                "name": "custom-plugin",
                                "url": "repo://4226448541"
                            }
                        ]

                    },
                    "deployment_template": {
                        "id": "gcp-storage-optimized-v3"
                    }
                }
            }
        ]
    }
}

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

Delete an extension

edit

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.

« Upload custom plugins and bundles Custom endpoint aliases »