Elasticsearch:Upload and install a custom plug-in

Prerequisites

• Prepare the plug-in that you want to upload and ensure its availability and security.

  The plug-in must be a .zip file. Its name must be 8 to 128 characters long and can only contain letters, digits, hyphens (-), or periods (.). The plug-in's plugin-descriptor.properties file must be in the root directory of the ZIP package.

• If you want to upload a custom SQL plug-in, you must set the xpack.sql.enabled parameter to false in the YAML file of your Alibaba Cloud Elasticsearch cluster.

  For more information, see Configure YML parameters.

Limitations

• An ES cluster has one of two control architectures: Basic Control Architecture (v2) or Cloud-native new control architecture (v3). To check which architecture your ES cluster uses, log on to the Elasticsearch console and go to the Basic Information page. The Control Architecture Type field will show either Cloud-native Control Architecture (v3) or Basic Control Architecture (v2).

• You cannot upload plug-ins that define any permission class, such as the elasticsearch-analysis-hanlp plug-in.

Considerations

• For help with errors during upload and installation (such as console errors, stalled changes, or verification failures), see Troubleshoot and resolve custom plug-in installation errors.

• A cluster upgrade does not automatically upgrade plug-ins. You must re-upload and reinstall them.

• Custom plug-ins cannot access the Internet by default. To enable access, configure a NAT Gateway. To access a private service across VPCs on the new network architecture, you can use PrivateLink. For more information, see Configure a private connection for a cluster. On the original network architecture, plug-ins can access only the network environment within the same VPC.

• Plug-ins can affect cluster stability. Ensure your custom plug-ins are available and secure.

Procedure

1. Log on to the Alibaba Cloud Elasticsearch console.

2. In the left-side navigation pane, click Elasticsearch Clusters.

3. 1. In the top menu bar, select the resource group and region where your cluster resides.

   2. Click the ID of the target cluster.

4. In the left-side navigation pane, choose Configuration and Management > Plug-in Configuration.

5. On the Plug-in Configuration page, click the Custom Plug-ins tab, and then click Upload.

6. Upload and install the custom plug-in.

   For clusters that use the cloud-native architecture, the upload and installation steps are separate. You can cancel an installation that is in progress. The procedures and validation checks differ depending on the cluster's control architecture.

   Cloud-native new control architecture (v3)

   1. In the Upload Plug-in dialog box, select a Plug-in Source, which can be Local File or OSS Object. If you select Local File, click Select files, or drag and drop files to this area and select the plug-in to upload.

      Your plug-in file must meet the following conditions to pass verification.

      • The plug-in's .zip file name must be 8 to 128 characters long and can only contain letters, digits, hyphens (-), and periods (.).

      • Each file cannot exceed 100 MB, and you can upload a maximum of 50 plug-in files per cluster.

      • The plug-in must be compatible with your cluster. Its name cannot conflict with any installed built-in or custom plug-ins, including others in the same batch upload.

   2. Select the The uploaded file does not take effect immediately. Go to the plug-in list to install the plug-in. message at the bottom of the page, and click OK.

   3. On the Custom Plug-ins tab, find your plug-in and click the icon to expand its details.

      The upload is successful if the plug-in appears in the list with a Status of Not Installed. If you no longer need an uploaded but not installed plug-in, you can click Delete in the Actions column to delete it.

   4. In the Actions column for the plug-in you want to install, click Install.

      The system verifies that the plug-in is compatible with your Elasticsearch version. The installation fails if the versions do not match.

      You can also select multiple plug-ins and click Batch Install at the bottom of the page to install multiple plug-ins at a time.

   5. In the Install Plug-in dialog box, read the cluster restart warning and click Continue.

      The installation triggers a cluster restart. We recommend that you perform this operation during off-peak hours. After the cluster restarts, the installation is successful if the plug-in's Status on the Custom Plug-ins tab is Installed. Once installed, you can update or uninstall the plug-in:

      • Update a plug-in

        To update a plug-in, upload the new version with the same name and then install it.

      • Uninstall a plug-in

        Click Uninstall in the Actions column for the plug-in to uninstall it. For detailed operations and notes, see Install or uninstall built-in plug-ins.

      Note

      During the installation, you can click Cancel Installation in the Actions column. This is useful if the installation fails due to an incompatibility with the ES cluster, as canceling rolls back the change.

   Basic Control Architecture (v2)

   1. In the Upload Plug-in dialog box, click Select files, or drag and drop files to this area, select the plug-in to upload, and click Open.

      Your plug-in file must meet the following conditions to pass verification:

      • The plug-in's .zip file name must be 8 to 128 characters long and can only contain letters, digits, hyphens (-), and periods (.).

      • Each file cannot exceed 100 MB, and you can upload a maximum of 50 plug-in files per cluster.

      • The plug-in must be compatible with your cluster. Its name cannot conflict with any installed built-in or custom plug-ins, including others in the same batch upload.

   2. Review the precautions, select the corresponding checkbox, and then click Upload.

      After the cluster restarts, the process is successful if the plug-in appears on the Custom Plug-ins tab with a Status of Installed.

      If you no longer need a plug-in, click Remove in its Actions column. For detailed operations and notes, see Install or uninstall built-in plug-ins. Before you uninstall, ensure no index references the plug-in to prevent the cluster from stalling on restart.