Alibaba Cloud Elasticsearch supports custom plug-ins for functionality not available with built-in plug-ins. Use this guide if you need to install a third-party plug-in or a plug-in you've built yourself.
Prerequisites
Before you begin, make sure that:
The plug-in file meets all requirements listed in Plug-in file requirements
(For custom SQL plug-ins only) Set the
xpack.sql.enabledparameter tofalsein the YML configuration file of your instance. For details, see Configure YML parameters
Plug-in file requirements
Your plug-in ZIP file must meet all of the following requirements. Validation fails if any condition is not met.
| Requirement | Details |
|---|---|
| File naming | Uppercase letters, lowercase letters, digits, hyphens (-), or periods (.) only. Length: 8–128 characters. Extension: .zip. |
| Internal structure | The plugin-descriptor.properties file must be in the root directory of the ZIP package. |
| File size | Maximum 100 MB per file. |
| File count | Maximum 50 uploaded files per instance. |
| Name uniqueness | The plug-in name must differ from all built-in plug-ins and from any plug-in already installed or included in the current batch. |
| Version uniqueness | The plug-in must differ in version from any plug-in already installed or in the current batch. |
| Format compatibility | The file format must be compatible with your instance. |
Limitations
| Limitation | Details |
|---|---|
| Operation permissions | Cannot upload plug-ins that define operation permissions, such as elasticsearch-analysis-hanlp. |
| Cluster upgrades | Plug-ins are not automatically upgraded when you upgrade the cluster. Re-upload and reinstall them manually after each cluster upgrade. |
| Internet access | Custom plug-ins cannot access the Internet by default. To enable Internet access, configure a NAT Gateway. For cross-Virtual Private Cloud (VPC) private access on the new network architecture, use PrivateLink. On the original network architecture, custom plug-ins can access only resources in the same VPC. For details, see Configure private connections for your instance. |
Usage notes
Installing a custom plug-in triggers a restart of your Elasticsearch instance. Perform this operation during off-peak hours.
A plug-in may affect cluster stability. Make sure the plug-in is usable and secure before uploading.
If errors occur during upload or installation—such as console errors, stalled changes, or failed verification—see Troubleshoot and resolve custom plug-in installation errors.
Upload and install a custom plug-in
Alibaba Cloud Elasticsearch clusters run on one of two control architectures: Cloud-native Control Architecture (v3) or Basic Control Architecture (v2). The upload and installation flow differs between them.
To check your cluster's architecture, log on to the Elasticsearch console, open the Basic Information page of your cluster, and check the Control Architecture Type field.
Navigation path for all clusters:
Log on to the Alibaba Cloud Elasticsearch console.
In the left navigation pane, click Elasticsearch Clusters.
In the top menu bar, select a resource group and region, then click the ID of your target instance.
In the left navigation pane, choose Configuration and Management > Plug-in Configuration.
On the Plug-in Configuration page, click the Custom Plug-ins tab, then click Upload.
Cloud-native new control architecture (v3)
On v3, upload and installation are separate steps. You can cancel installation after it starts.
Step 1: Upload the plug-in
In the Upload Plug-in dialog box, select a Plug-in Source: Local File or OSS Object.
For Local File: click Select files, or drag and drop files to this area, then select or drag your plug-in file.
Click OK to confirm the message: *The uploaded file does not take effect immediately. Go to the plug-in list to install the plug-in.*
On the Custom Plug-ins tab, click the expand icon next to the plug-in name to view its details. If the plug-in appears with a Status of Not Installed, the upload succeeded. To remove an uploaded but not yet installed plug-in, click Delete in the Actions column.
Step 2: Install the plug-in
In the plug-in list, click Install in the Actions column. The system checks whether the plug-in's Elasticsearch version matches the cluster. Installation fails if versions do not match. To install multiple plug-ins at once, select them and click Batch Install at the bottom of the page.
In the Install Plug-in dialog box, confirm that the operation triggers a cluster restart, then click Continue.
After the restart completes, go to the Custom Plug-ins tab. If the plug-in's Status is Installed, installation succeeded.
During installation, click Actions > Cancel Installation to stop the process. This lets you roll back safely if the plug-in fails to adapt to your cluster.
After installation: update or uninstall
Update: Upload the latest version of the same plug-in, then install it from the plug-in list.
Uninstall: Click Uninstall in the Actions column. For detailed steps, see Install or uninstall a built-in plug-in.
Basic control architecture (v2)
On v2, upload and installation happen in a single step.
In the Upload Plug-in dialog box, click Select files, or drag and drop files to this area, select the plug-in file, and click Open. You can also drag the file directly into the area.
Read the precautions in the dialog box, select the check box, and click Upload. The system uploads and installs the plug-in, then restarts the cluster. After the restart completes, go to the Custom Plug-ins tab. If the plug-in appears with a Status of Installed, the operation succeeded.
To remove a plug-in, click Remove in the Actions column. Before removing, make sure no indexes reference the plug-in—otherwise the cluster restart may stall. For detailed steps, see Install or uninstall a built-in plug-in.