- Introducing Elasticsearch Service
- Adding data to Elasticsearch
- Migrating data
- Ingesting data from your application
- Ingest data with Node.js on Elasticsearch Service
- Ingest data with Python on Elasticsearch Service
- Ingest data from Beats to Elasticsearch Service with Logstash as a proxy
- Ingest data from a relational database into Elasticsearch Service
- Ingest logs from a Python application using Filebeat
- Ingest logs from a Node.js web application using Filebeat
- Configure Beats and Logstash with Cloud ID
- Best practices for managing your data
- Configure index management
- Enable cross-cluster search and cross-cluster replication
- Access other deployments of the same Elasticsearch Service organization
- Access deployments of another Elasticsearch Service organization
- Access deployments of an Elastic Cloud Enterprise environment
- Access clusters of a self-managed environment
- Enabling CCS/R between Elasticsearch Service and ECK
- Edit or remove a trusted environment
- Migrate the cross-cluster search deployment template
- Manage data from the command line
- Preparing a deployment for production
- Securing your deployment
- Monitoring your deployment
- Monitor with AutoOps
- Configure Stack monitoring alerts
- Access performance metrics
- Keep track of deployment activity
- Diagnose and resolve issues
- Diagnose unavailable nodes
- Why are my shards unavailable?
- Why is performance degrading over time?
- Is my cluster really highly available?
- How does high memory pressure affect performance?
- Why are my cluster response times suddenly so much worse?
- How do I resolve deployment health warnings?
- How do I resolve node bootlooping?
- Why did my node move to a different host?
- Snapshot and restore
- Managing your organization
- Your account and billing
- Billing Dimensions
- Billing models
- Using Elastic Consumption Units for billing
- Edit user account settings
- Monitor and analyze your account usage
- Check your subscription overview
- Add your billing details
- Choose a subscription level
- Check your billing history
- Update billing and operational contacts
- Stop charges for a deployment
- Billing FAQ
- Elasticsearch Service hardware
- Elasticsearch Service GCP instance configurations
- Elasticsearch Service GCP default provider instance configurations
- Elasticsearch Service AWS instance configurations
- Elasticsearch Service AWS default provider instance configurations
- Elasticsearch Service Azure instance configurations
- Elasticsearch Service Azure default provider instance configurations
- Change hardware for a specific resource
- Elasticsearch Service regions
- About Elasticsearch Service
- RESTful API
- Release notes
- Enhancements and bug fixes - December 2024
- Enhancements and bug fixes - November 2024
- Enhancements and bug fixes - Late October 2024
- Enhancements and bug fixes - Early October 2024
- Enhancements and bug fixes - September 2024
- Enhancements and bug fixes - Late August 2024
- Enhancements and bug fixes - Early August 2024
- Enhancements and bug fixes - July 2024
- Enhancements and bug fixes - Late June 2024
- Enhancements and bug fixes - Early June 2024
- Enhancements and bug fixes - Early May 2024
- Bring your own key, and more
- AWS region EU Central 2 (Zurich) now available
- GCP region Middle East West 1 (Tel Aviv) now available
- Enhancements and bug fixes - March 2024
- Enhancements and bug fixes - January 2024
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- AWS region EU North 1 (Stockholm) now available
- GCP regions Asia Southeast 2 (Indonesia) and Europe West 9 (Paris)
- Enhancements and bug fixes
- Enhancements and bug fixes
- Bug fixes
- Enhancements and bug fixes
- Role-based access control, and more
- Newly released deployment templates for Integrations Server, Master, and Coordinating
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Enhancements and bug fixes
- Cross environment search and replication, and more
- Enhancements and bug fixes
- Enhancements and bug fixes
- Azure region Canada Central (Toronto) now available
- Azure region Brazil South (São Paulo) now available
- Azure region South Africa North (Johannesburg) now available
- Azure region Central India (Pune) now available
- Enhancements and bug fixes
- Azure new virtual machine types available
- Billing Costs Analysis API, and more
- Organization and billing API updates, and more
- Integrations Server, and more
- Trust across organizations, and more
- Organizations, and more
- Elastic Consumption Units, and more
- AWS region Africa (Cape Town) available
- AWS region Europe (Milan) available
- AWS region Middle East (Bahrain) available
- Enhancements and bug fixes
- Enhancements and bug fixes
- GCP Private Link, and more
- Enhancements and bug fixes
- GCP region Asia Northeast 3 (Seoul) available
- Enhancements and bug fixes
- Enhancements and bug fixes
- Native Azure integration, and more
- Frozen data tier and more
- Enhancements and bug fixes
- Azure region Southcentral US (Texas) available
- Azure region East US (Virginia) available
- Custom endpoint aliases, and more
- Autoscaling, and more
- Cross-region and cross-provider support, warm and cold data tiers, and more
- Better feature usage tracking, new cost and usage analysis page, and more
- New features, enhancements, and bug fixes
- AWS region Asia Pacific (Hong Kong)
- Enterprise subscription self service, log in with Microsoft, bug fixes, and more
- SSO for Enterprise Search, support for more settings
- Azure region Australia East (New South Wales)
- New logging features, better GCP marketplace self service
- Azure region US Central (Iowa)
- AWS region Asia Pacific (Mumbai)
- Elastic solutions and Microsoft Azure Marketplace integration
- AWS region Pacific (Seoul)
- AWS region EU West 3 (Paris)
- Traffic management and improved network security
- AWS region Canada (Central)
- Enterprise Search
- New security setting, in-place configuration changes, new hardware support, and signup with Google
- Azure region France Central (Paris)
- Regions AWS US East 2 (Ohio) and Azure North Europe (Ireland)
- Our Elasticsearch Service API is generally available
- GCP regions Asia East 1 (Taiwan), Europe North 1 (Finland), and Europe West 4 (Netherlands)
- Azure region UK South (London)
- GCP region US East 1 (South Carolina)
- GCP regions Asia Southeast 1 (Singapore) and South America East 1 (Sao Paulo)
- Snapshot lifecycle management, index lifecycle management migration, and more
- Azure region Japan East (Tokyo)
- App Search
- GCP region Asia Pacific South 1 (Mumbai)
- GCP region North America Northeast 1 (Montreal)
- New Elastic Cloud home page and other improvements
- Azure regions US West 2 (Washington) and Southeast Asia (Singapore)
- GCP regions US East 4 (N. Virginia) and Europe West 2 (London)
- Better plugin and bundle support, improved pricing calculator, bug fixes, and more
- GCP region Asia Pacific Southeast 1 (Sydney)
- Elasticsearch Service on Microsoft Azure
- Cross-cluster search, OIDC and Kerberos authentication
- AWS region EU (London)
- GCP region Asia Pacific Northeast 1 (Tokyo)
- Usability improvements and Kibana bug fix
- GCS support and private subscription
- Elastic Stack 6.8 and 7.1
- ILM and hot-warm architecture
- Elasticsearch keystore and more
- Trial capacity and more
- APM Servers and more
- Snapshot retention period and more
- Improvements and snapshot intervals
- SAML and multi-factor authentication
- Next generation of Elasticsearch Service
- Branding update
- Minor Console updates
- New Cloud Console and bug fixes
- What’s new with the Elastic Stack
Managing plugins and extensions through the API
editManaging plugins and extensions through the API
editThis guide provides a full list of tasks for managing plugins and extensions in Elasticsearch Service, using the API.
- Create an extension
- Add an extension to a deployment plan
- Get an extension
- Update the name of an existing extension
- Update the type of an existing extension
- Update the version of an existing bundle
- Update the version of an existing plugin
- Update the file associated to an existing extension
- Upgrade Elasticsearch
- Delete an extension
Create an extension
editThere are two methods to create an extension. You can:
- Stream the file from a publicly-accessible download URL.
- 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
editOnce 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
editYou 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
editTo 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
editUpdating 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
editFor 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
editFor 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
editYou 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
editWhen 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:
-
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, from8.4.2
to8.4.3
) or a minor (for example8.3.0
to8.4.3
) version upgrade of Elasticsearch and you are already using8.*
as theversion
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 Elasticsearchversion
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, setversion
to8.*
before the upgrade. Refer to Update the version of an existing bundle. -
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
andresources.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" } } } ] } }
-
Upgrade the version of Elasticsearch to the upgrade version (for example,
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.
-
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’selasticsearch.version
field inplugin-descriptor.properties
that matches the Elasticsearch upgrade version (for example,8.4.3
). -
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
andresources.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.
-
Upgrade the version of Elasticsearch to the upgrade version (for example,
Delete an extension
editYou 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.
On this page
- Create an extension
- Add an extension to a deployment plan
- Get an extension
- Update the name of an existing extension
- Update the type of an existing extension
- Update the version of an existing bundle
- Update the version of an existing plugin
- Update the file associated to an existing extension
- Upgrade Elasticsearch
- Delete an extension