本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在 Amazon OpenSearch 服务中管理自定义插件
使用 OpenSearch 服务自定义插件，您可以扩展语言分析、自定义筛选、排名等领域的 OpenSearch 功能，从而可以打造个性化的搜索体验。的自定义插件 OpenSearch 可以通过扩展`org.opensearch.plugins.Plugin`类然后将其打包到`.zip`文件中来开发。
Amazon OpenSearch 服务目前支持以下插件扩展：
+ **AnalysisPlugin**— 通过添加自定义分析器、字符分词器或用于文本处理的过滤器等来扩展分析功能。
+ **SearchPlugin**— 通过自定义查询类型、相似度算法、建议选项和聚合增强搜索功能。
+ **MapperPlugin**— 允许您在中创建自定义字段类型及其映射配置 OpenSearch，从而可以定义应如何存储和索引不同类型的数据。
+ **ScriptPlugin**— 允许您在自定义脚本中添加自定义脚本功能，例如在搜索或索引期间进行评分、排序和字段值转换等操作。 OpenSearch
您可以使用 OpenSearch 服务控制台或自定义包的现有 API 命令上传插件并将插件与 Amazon S OpenSearch ervice 集群关联。您还可以使用该[DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html)命令来描述您账户中的所有软件包，并查看 OpenSearch 版本和错误详细信息等详细信息。 OpenSearch 服务会验证插件包的版本兼容性、安全漏洞和允许的插件操作。有关自定义程序包的更多信息，请参阅 [在 Amazon OpenSearch 服务中导入和管理包裹](custom-packages.md)。
**OpenSearch 版本和 AWS 区域 支持**
运行以下 OpenSearch AWS 区域版本 2.15 的 OpenSearch 服务域支持自定义插件：
+ 美国东部（俄亥俄州）(us-east-2)
+ 美国东部（弗吉尼亚北部）(us-east-1)
+ 美国西部（俄勒冈州）(us-west-2)
+ 亚太地区（孟买）(ap-south-1)
+ 亚太地区（首尔）(ap-northeast-2)
+ 亚太地区（新加坡）(ap-southeast-1)
+ 亚太地区（悉尼）(ap-southeast-2)
+ 亚太地区（东京）(ap-northeast-1)
+ 加拿大（中部）(ca-central-1)
+ 欧洲地区（法兰克福）(eu-central-1)
+ 欧洲地区（爱尔兰）(eu-west-1)
+ 欧洲地区（伦敦）(eu-west-2)
+ 欧洲地区（巴黎）（eu-west-3）
+ 南美洲（圣保罗）（sa-east-1）
**注意**
自定义插件包含用户开发的代码。任何由用户开发代码导致的问题（包括违反 SLA）均不符合 SLA 积分的适用条件。有关更多信息，请参阅 [Amazon OpenSearch 服务-服务等级协议](https://aws.amazon.com/opensearch-service/sla/)。
**Topics**
+ [插件限额](#plugin-limits)
+ [先决条件](#custom-plugin-prerequisites)
+ [问题排查](#custom-plugin-troubleshooting)
+ [使用控制台安装自定义插件](#custom-plugin-install-console)
+ [使用管理自定义插件 AWS CLI](#managing-custom-plugins-cli)
+ [亚马逊 OpenSearch 服务定制包裹 AWS KMS 集成](custom-package-kms-integration.md)
## 插件限额
+ 每个账户在每个区域最多可创建 25 个自定义插件。
+ 插件的最大未压缩大小为 1 GB。
+ 单个域最多可关联 20 个插件。此限额适用于所有插件类型的组合：可选插件、第三方插件和自定义插件。
+ 运行 2.15 或更高 OpenSearch 版本的域名支持自定义插件。
+ 插件的 `descriptor.properties` 文件必须支持类似于 2.15.0 的引擎版本，或任何 2.x.x 版本，其中补丁版本设置为零。
## 先决条件
在安装自定义插件并将其关联到域名之前，请确保满足以下要求：
+ `descriptor.properties` 文件中插件支持的引擎版本应类似于 `2.15.0` 或 `2.x.0`。也就是说，补丁版本必须为零。
+ 您的域必须启用以下功能：
+ [Node-to-node 加密](ntn.md)
+ [静态加密](encryption-at-rest.md)
+ [`EnforceHTTPS` 设置为 'true'](createupdatedomains.md)
另请参阅[opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html)《*AWS Config 开发人员指南》*。
+ 客户端必须支持 **Policy-Min-TLS-1-2-PFS-2023-10**。您可以使用以下命令指定此支持。*placeholder value*用您自己的信息替换：
```
aws opensearch update-domain-config \
--domain-name domain-name \
--domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }'
```
有关更多信息，请参阅[DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html)《*亚马逊 OpenSearch 服务 API 参考*》。
## 问题排查
如果系统返回错误 `PluginValidationFailureReason : The provided plugin could not be loaded`，请参阅 [自定义插件安装因版本兼容性问题而失败](handling-errors.md#troubleshooting-custom-plugins) 以获取故障排除信息。
## 使用控制台安装自定义插件
要将第三方插件与域关联，请先将插件许可证和配置作为程序包导入。
**安装自定义插件**
1. 在[https://console.aws.amazon.com/aos/家](https://console.aws.amazon.com/aos/home)中登录亚马逊 OpenSearch 服务控制台。
1. 在左侧导航窗格中，选择**程序包**。
1. 选择 **Import package（导入软件包）**。
1. 对于**名称**，输入唯一且易于识别的插件名称。
1. （可选）对于**描述**，提供有关程序包或其用途的所有有用详细信息。
1. 对于**程序包类型**，选择**插件**。
1. 对于**程序包来源**，输入路径或浏览到 Amazon S3 中的插件 ZIP 文件。
1. 对于**OpenSearch 引擎版本**，请选择插 OpenSearch 件支持的版本。
1. 对于**程序包加密**，选择是否为程序包自定义加密密钥。默认情况下，S OpenSearch ervice 使用加密插件包。 AWS 拥有的密钥您也可以使用客户托管型密钥。
1. 选择**导入**。
导入插件程序包后，将其与域关联。有关说明，请参阅[导入程序包并将其与域关联（控制台）](custom-packages.md#associate-console)。
## 使用管理自定义插件 AWS CLI
您可以使用 AWS CLI 来管理许多自定义插件任务。
**Topics**
+ [使用安装自定义插件 AWS CLI](#custom-plugin-install-cli)
+ [使用更新自定义插件 AWS CLI](#custom-plugin-update-cli)
+ [创建或更新带有 AWS KMS 密钥安全的自定义插件](#custom-plugin-kms-key-security-cli)
+ [将带有自定义插件的 OpenSearch 服务域升级到更高版本的 OpenSearch 使用 AWS CLI](#custom-plugin-domain-upgrade-cli)
+ [卸载自定义插件和查看其解除关联状态](#custom-plugin-uninstall-cli)
### 使用安装自定义插件 AWS CLI
**开始前的准备工作**
在您将自定义插件与域关联之前，您必须将其上传到 Amazon Simple Storage Service（Amazon S3）存储桶。存储桶必须位于您打算使用插件 AWS 区域 的位置。有关向 S3 存储桶添加对象的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[上传对象](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)。
如果插件包含敏感信息，请在上传时指定使用 S3 管理的密钥进行服务器端加密。上传文件后，记下其 S3 路径。路径格式为 `s3://amzn-s3-demo-bucket/file-path/file-name`。
**注意**
在创建自定义插件时，您可以选择通过指定 AWS Key Management Service (AWS KMS) 密钥来保护自定义插件。有关信息，请参阅[创建或更新带有 AWS KMS 密钥安全的自定义插件](#custom-plugin-kms-key-security-cli)。
**要安装自定义插件，请使用 AWS CLI**
1. 运行以下 [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) 命令为自定义插件创建新程序包，确保满足以下要求：
+ 存储桶和密钥位置必须指向您运行命令的账户中 S3 存储桶的插件 `.zip` 文件。
+ S3 存储桶必须位于所创建程序包的同一区域。
+ `ZIP-PLUGIN` 程序包仅支持 `.zip` 文件。
+ `.zip` 文件的内容必须遵循插件预期的目录结构。
+ `--engine-version` 的值必须采用格式 `OpenSearch_{MAJOR}.{MINOR}`。例如：**OpenSearch\$12.17**。
*placeholder values*用您自己的信息替换：
```
aws opensearch create-package \
--package-name package-name \
--region region \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--engine-version opensearch-version
```
1. （可选）使用 [describe-packages](https://docs.aws.amazon.com/cli/latest/reference/es/describe-packages.html) 命令查看 `create-package` 操作的状态，包括任何验证和安全漏洞调查发现。*placeholder values*用您自己的信息替换：
```
aws opensearch describe-packages \
--region region \
--filters '[{"Name": "PackageType","Value": ["ZIP-PLUGIN"]}, {"Name": "PackageName","Value": ["package-name"]}]'
```
命令返回类似于下文的信息：
```
{
"PackageDetailsList": [{
"PackageID": "pkg-identifier",
"PackageName": "package-name",
"PackageType": "ZIP-PLUGIN",
"PackageStatus": "VALIDATION_FAILED",
"CreatedAt": "2024-11-11T13:07:18.297000-08:00",
"LastUpdatedAt": "2024-11-11T13:10:13.843000-08:00",
"ErrorDetails": {
"ErrorType": "",
"ErrorMessage": "PluginValidationFailureReason : Dependency Scan reported 3 vulnerabilities for the plugin: CVE-2022-23307, CVE-2019-17571, CVE-2022-23305"
},
"EngineVersion": "OpenSearch_2.15",
"AllowListedUserList": [],
"PackageOwner": "OWNER-XXXX"
}]
}
```
**注意**
在`create-package`操作过程中，Amazon Serv OpenSearch ice 会检查该`ZIP-PLUGIN`值的版本兼容性、支持的插件扩展和安全漏洞。使用 [Amazon Inspector](https://aws.amazon.com/inspector/getting-started/) 服务扫描安全漏洞。这些检查的结果显示在 API 响应的 `ErrorDetails` 字段中。
1. 使用 ass [ociate-package 命令使用上一步中创建的软件包](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html)的软件包 ID 将插件与您选择的 OpenSearch 服务域关联起来。
**提示**
如果您有多个插件，则可改用 [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) 命令，通过单次操作将多个程序包关联至某个域。
*placeholder values*用您自己的信息替换：
```
aws opensearch associate-package \
--domain-name domain-name \
--region region \
--package-id package-id
```
**注意**
使用[蓝绿部署过程](managedomains-configuration-changes.md)安装和卸载插件。
1. （可选）使用[list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)命令查看关联的状态。随着工作流程从 `ASSOCIATING` 到 `ACTIVE` 的进展，关联状态随之变化。插件安装完成后，其状态将更改为“活动”，此时插件已可投入使用。
将 *placeholder values* 替换为您自己的信息。
```
aws opensearch list-packages-for-domain \
--region region \
--domain-name domain-name
```
### 使用更新自定义插件 AWS CLI
使用 [update-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/update-package.html) 命令对插件进行更改。
**注意**
在更新插件时，您可以选择通过指定 AWS Key Management Service (AWS KMS) 密钥来保护自定义插件。有关信息，请参阅[创建或更新带有 AWS KMS 密钥安全的自定义插件](#custom-plugin-kms-key-security-cli)。
**要更新自定义插件，请使用 AWS CLI**
+ 运行如下命令。将 *placeholder values* 替换为您自己的信息。
```
aws opensearch update-package \
--region region \
--package-id package-id \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--package-description description
```
更新程序包后，您可以使用 [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) 或 [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) 命令将程序包更新应用于域。
**注意**
您可以使用审计、创建、更新、关联和取消关联插件上的操作。 AWS CloudTrail有关更多信息，请参阅 [使用监控亚马逊 OpenSearch 服务 API 调用 AWS CloudTrail](managedomains-cloudtrailauditing.md)。
### 创建或更新带有 AWS KMS 密钥安全的自定义插件
创建或更新自定义插件时，您可以通过指定 AWS KMS 密钥保护自定义插件。要完成此操作，请将 `PackageEncryptionOptions` 设置为 `true`，并指定密钥的 Amazon 资源名称（ARN），如下例所示：
**示例：创建具有 AWS KMS 密钥安全性的自定义插件**
```
aws opensearch create-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**示例：使用 AWS KMS 密钥安全更新自定义插件**
```
aws opensearch update-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**重要**
如果您指定的 AWS KMS 密钥被禁用或删除，它可能会使关联的集群无法运行。
有关与自定义包 AWS KMS 集成的更多信息，请参阅[亚马逊 OpenSearch 服务定制包裹 AWS KMS 集成](custom-package-kms-integration.md)。
### 将带有自定义插件的 OpenSearch 服务域升级到更高版本的 OpenSearch 使用 AWS CLI
当您需要将使用自定义插件的 OpenSearch 服务域升级到更高版本时 OpenSearch，请完成以下过程。
**要将带有自定义插件的 OpenSearch 服务域升级到更高版本的 OpenSearch 使用 AWS CLI**
1. 使用 create-package 命令为您的插件创建一个新软件包，指定新 OpenSearch 版本。
确保所有引擎版本的插件程序包名称保持一致。更改软件包名称会导致域升级过程在 blue/green 部署期间失败。
1. 按照 [升级 Amazon OpenSearch Service 域](version-migration.md) 中的步骤将域升级至更高版本。
在此过程中，Amazon Serv OpenSearch ice 会解除先前版本的插件包的关联，并使用 blue/green 部署来安装新版本。
### 卸载自定义插件和查看其解除关联状态
要从任何域中卸载插件，可使用 [dissociate-package](https://docs.aws.amazon.com/cli/latest/reference/es/dissociate-package.html) 命令。执行此命令还会删除任何相关的配置或许可证程序包。然后，您可以使用[list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/es/list-packages-for-domain.html)命令查看解除关联的状态。
**提示**
您还可以使用 [dissociate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/dissociate-packages.html) 命令，一次性从域中卸载多个插件。
**卸载自定义插件和查看其解除关联状态**
1. 在每个索引中禁用插件。这必须在解除插件程序包的关联之前完成。
如果您在从每个索引中禁用插件之前尝试将其卸载，则 blue/green 部署过程仍处于该`Processing`状态。
1. 运行以下命令卸载插件。将 *placeholder values* 替换为您自己的信息。
```
aws opensearch dissociate-package \
--region region \
--package-id plugin-package-id \
--domain-name domain name
```
1. （可选）运行[list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)命令以查看解除关联的状态。