本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在 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)命令以查看解除关联的状态。
# 亚马逊 OpenSearch 服务定制包裹 AWS KMS 集成
默认情况下，Amazon S OpenSearch ervice 定制包裹提供加密，以保护您的`ZIP-PLUGIN`包裹处于静态状态 AWS 托管式密钥。
+ **AWS 拥有的密钥**— Amazon S OpenSearch ervice 定制包裹默认使用这些密钥来自动加密您的`ZIP-PLUGIN`包裹。您无法查看、管理、使用 AWS 拥有的密钥 或审核其使用情况。但是，无需执行任何操作或更改任何计划即可保护用于加密数据的密钥。有关更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的 [AWS 拥有的密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk)。
+ **客户托管密钥** — 您可以在创建`ZIP-PLUGIN`自定义软件包时选择客户托管密钥，在现有 AWS 拥有的密钥 密钥的基础上添加第二层加密。
Amazon S OpenSearch ervice 定制套餐支持使用由您创建、拥有并管理的对称客户托管密钥，在现有 AWS 自有加密的基础上添加第二层加密。由于您可以完全控制这层加密，因此可执行以下任务：
+ 建立和维护密钥策略
+ 制定和维护 AWS Identity and Access Management (IAM) 策略和拨款
+ 启用和禁用密钥策略
+ 轮换密钥加密材料
+ 添加标签
+ 创建密钥别名
+ 计划密钥删除
有关更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的[客户托管密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)。
**注意**
Amazon S OpenSearch ervice 定制套餐可自动启用静态加密 AWS 拥有的密钥 ，不收取任何费用。但是，当您使用客户托管密钥时，需要 AWS KMS 付费。有关定价的更多信息，请参阅 [AWS Key Management Service 定价](https://aws.amazon.com/kms/pricing/)。
## Amazon S OpenSearch ervice 定制包裹服务如何使用补助金 AWS KMS
OpenSearch 服务自定义包需要获得授权才能使用您的客户托管密钥。
当您创建使用客户托管密钥加密的`ZIP-PLUGIN`包裹时，Amazon S OpenSearch ervice 定制包裹服务会通过向发送[CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)请求来代表您创建授权 AWS KMS。授 AWS KMS 予 OpenSearch 服务访问您账户中 AWS KMS 密钥的权限。S OpenSearch ervice 自定义软件包创建的授权有一个约束，即只有当请求包含带有您的自定义软件包 ID 的加密上下文时，才允许进行操作。
Amazon S OpenSearch ervice 定制包需要获得授权，才能使用您的客户托管密钥进行以下内部操作：
| 操作 | 说明 |
| --- | --- |
| DescribeKey | 向发送DescribeKey请求， AWS KMS 以验证创建插件包时输入的对称客户托管密钥 ID 是否有效。 |
| GenerateDataKeyWithoutPlaintext | 向发送GenerateDataKeyWithoutPlaintext请求 AWS KMS 以生成由您的客户托管密钥加密的数据密钥。 |
| GenerateDataKey | 向发送GenerateDataKey请求 AWS KMS 以生成数据密钥，以便在内部复制软件包时对其进行加密。 |
| Decrypt | 向发送解密加密数据密钥的Decrypt请求，以便这些密钥可用于解密您的数据。 AWS KMS |
您可以随时撤销授予访问权限，或删除服务对客户托管密钥的访问权限。否则，S OpenSearch ervice 将无法访问由客户托管密钥加密的任何数据，这会影响依赖该数据的操作。例如，如果您尝试关联一个 S OpenSearch ervice 无法访问的插件包，则该操作会返回`AccessDeniedException`错误。
## 创建客户托管密钥
您可以使用 AWS 管理控制台 或创建对称的客户托管密钥。 AWS KMS APIs
**创建对称的客户托管密钥**
+ 按照《AWS Key Management Service 开发人员指南》**中[创建 KMS 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk)的步骤操作。
### 密钥策略
密钥策略控制对客户自主管理型密钥的访问。每个客户托管式密钥必须只有一个密钥策略，其中包含确定谁可以使用密钥以及如何使用密钥的声明。创建客户托管式密钥时，可以指定密钥策略。有关更多信息，请参阅《*AWS Key Management Service 开发人员指南*》中的[在 AWS KMS中使用密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。
要将客户托管密钥与插件资源一起使用，您必须在密钥策略中允许以下 API 操作：
+ `kms:CreateGrant`：向客户托管密钥添加授权。授予对指定 AWS KMS 密钥的控制访问权限，允许授予 OpenSearch 服务自定义包所需的操作的访问权限。有关使用授权的更多信息，请参阅 [AWS KMS 开发人员指南](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html)。
这允许 OpenSearch 服务执行以下操作：
+ 调用 `GenerateDataKeyWithoutPlainText`，以生成加密的数据密钥，并将其存储以供后续验证。
+ 调用 `GenerateDataKey`，以在内部复制插件程序包。
+ 调用 `Decrypt`，以在内部访问插件程序包。
+ 设置停用主体，以允许服务 `RetireGrant`。
+ `kms:DescribeKey`— 提供客户管理的密钥详细信息，以允许 OpenSearch 服务部门验证密钥。
+ `kms:GenerateDataKey`,`kms:GenerateDataKeyWithoutPlaintext`, `kms:Decrypt` — 授予 OpenSearch 服务自定义包访问权限，以便在授权中使用这些操作。
以下是您可以为 OpenSearch 服务自定义包添加的策略声明示例：
```
"Statement" : [
{
"Sid" : "Allow access to principals authorized to use OpenSearch Service custom packages",
"Effect" : "Allow",
"Principal" : {
"AWS" : "*"
},
"Action" : [
"kms:CreateGrant",
"kms:GenerateDataKey",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:Decrypt"
],
"Resource" : "*",
"Condition" : {
"StringEquals" : {
"kms:ViaService" : "custom-packages.region.amazonaws.com"
},
"StringEquals" : {
"kms:EncryptionContext:packageId": "Id of the package"
}
}
},
{
"Sid" : "Allow access to principals authorized to use Amazon OpenSearch Service custom packages",
"Effect" : "Allow",
"Principal" : {
"AWS" : "*"
},
"Action" : [
"kms:DescribeKey"
],
"Resource" : "*",
"Condition" : {
"StringEquals" : {
"kms:ViaService" : "custom-packages.region.amazonaws.com"
}
}
}
]
```
有关在策略中指定权限的更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的[AWS KMS中的密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。
有关密钥访问疑难解答的更多信息，请参阅《*AWS Key Management Service 开发人员指南*》中的[AWS KMS 权限疑难解答](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html)。
## 为亚马逊 OpenSearch 服务定制包指定客户托管密钥
您可以指定客户托管密钥用于 `ZIP-PLUGIN` 程序包的第二层加密。
创建插件包时，您可以通过输入密钥 ID 来指定数据密钥，S OpenSearch ervice 自定义包使用 AWS KMS 密钥 ID 来加密插件包。
*AWS KMS 密钥 ID* — AWS KMS 客户托管密钥的密钥标识符。输入密钥 ID、密钥 ARN、别名名称或别名 ARN。
## 亚马逊 OpenSearch 服务自定义包裹加密上下文
加密上下文是一组可选的键值对，包含有关数据的其他上下文信息。
AWS KMS 使用加密上下文作为其他经过身份验证的数据来支持经过身份验证的加密。当您在加密数据的请求中包含加密上下文时，会将加密上下文 AWS KMS 绑定到加密数据。要解密数据，您必须在请求中包含相同的加密上下文。
### 亚马逊 OpenSearch 服务自定义包裹加密上下文
Amazon S OpenSearch ervice 自定义软件包在所有 AWS KMS 加密操作中使用相同的加密上下文，其中密钥是`packageId`，值是插件包`package-id`的值。
### 使用加密上下文进行监控
使用对称的客户托管密钥加密插件程序包时，您还可以使用审计记录和日志中的加密上下文，以识别客户托管密钥的使用情况。加密上下文还会显示在 AWS CloudTrail 或 Amazon Logs 生成的 CloudWatch 日志中。
### 使用加密上下文控制对客户托管密钥的访问
您可以使用密钥策略和 IAM 策略中的加密上下文作为条件来控制对您的对称客户托管密钥的访问。您也可以在授予中使用加密上下文约束。
OpenSearch 服务自定义包在授权中使用加密上下文约束来控制对您的账户或区域中客户托管密钥的访问权限。授权约束要求授权允许的操作使用指定的加密上下文。
以下是密钥策略声明示例，用于授予对特定加密上下文的客户托管密钥的访问权限。此策略语句中的条件要求授权具有指定加密上下文的加密上下文约束。
```
{
"Sid": "Enable DescribeKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "Enable OpenSearch Service custom packages to use the key",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
},
"Action" : [
"kms:CreateGrant",
"kms:GenerateDataKey",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringEquals" : {
"kms:EncryptionContext:packageId": "ID of the package"
}
}
}
```
## 监控 OpenSearch 自定义包服务的加密密钥
当您在 OpenSearch 服务自定义包服务资源中使用 AWS KMS 客户托管密钥时，您可以使用 CloudTrail 或 CloudWatch 日志来跟踪 OpenSearch 自定义包发送到的请求 AWS KMS。
**了解详情**
以下资源提供有关静态数据加密的更多信息。
+ 有关 AWS KMS 基本概念的更多信息，请参阅*AWS Key Management Service 开发人员指南[AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)*中的。
+ 有关安全最佳实践的更多信息 AWS KMS，请参阅《*AWS 规范性指南*》[AWS Key Management Service 最佳实践](https://docs.aws.amazon.com/kms/latest/developerguide/best-practices.html)指南。