As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Gerenciando plug-ins personalizados no Amazon OpenSearch Service
Usando plug-ins personalizados para o OpenSearch Serviço, você pode estender a OpenSearch funcionalidade em áreas como análise de linguagem, filtragem personalizada, classificação e muito mais, possibilitando a criação de experiências de pesquisa personalizadas. Os plug-ins personalizados para OpenSearch podem ser desenvolvidos estendendo a `org.opensearch.plugins.Plugin` classe e, em seguida, empacotando-a em um `.zip` arquivo.
As seguintes extensões de plug-in são atualmente suportadas pelo Amazon OpenSearch Service:
+ **AnalysisPlugin**— amplia a funcionalidade de análise adicionando, por exemplo, analisadores personalizados, tokenizadores de caracteres ou filtros para processamento de texto.
+ **SearchPlugin**— aprimora os recursos de pesquisa com tipos de consulta personalizados, algoritmos de similaridade, opções de sugestão e agregações.
+ **MapperPlugin**— Permite criar tipos de campo personalizados e suas configurações de mapeamento no OpenSearch, permitindo definir como diferentes tipos de dados devem ser armazenados e indexados.
+ **ScriptPlugin**— Permite adicionar recursos de script personalizados a OpenSearch, por exemplo, scripts personalizados para operações como pontuação, classificação e transformações de valores de campo durante a pesquisa ou indexação.
Você pode usar o console do OpenSearch Service ou os comandos de API existentes para pacotes personalizados para carregar e associar o plug-in ao cluster do Amazon OpenSearch Service. Você também pode usar o [DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html)comando para descrever todos os pacotes em sua conta e visualizar detalhes, como detalhes da OpenSearch versão e do erro. OpenSearch O serviço valida o pacote de plug-ins quanto à compatibilidade de versões, vulnerabilidades de segurança e operações permitidas do plug-in. Para saber mais sobre pacotes personalizados, consulte [Importação e gerenciamento de pacotes no Amazon Service OpenSearch](custom-packages.md).
**OpenSearch versão e Região da AWS suporte**
Os plug-ins personalizados são compatíveis com domínios OpenSearch de serviço que executam a OpenSearch versão 2.15 da seguinte forma: Regiões da AWS
+ Leste dos EUA (Ohio) (us-east-2)
+ Leste dos EUA (Norte da Virgínia) (us-east-1)
+ Oeste dos EUA (Oregon) (us-west-2)
+ Ásia-Pacífico (Mumbai) (ap-south-1)
+ Ásia-Pacífico (Seul) (ap-northeast-2)
+ Ásia-Pacífico (Singapura) (ap-southeast-1)
+ Ásia-Pacífico (Sydney) (ap-southeast-2)
+ Ásia Pacific (Tóquio) (ap-northeast-1)
+ Canadá (Central) (ca-central-1)
+ Europa (Frankfurt) (eu-central-1)
+ Europa (Irlanda) (eu-west-1)
+ Europa (Londres) (eu-west-2)
+ Europa (Paris) (eu-west-3)
+ América do Sul (São Paulo) (sa-east-1)
**nota**
Os plug-ins personalizados contêm código desenvolvido pelo usuário. Os problemas, incluindo violações de SLA, causados por código desenvolvido pelo usuário não são elegíveis a créditos de SLA. Para obter mais informações, consulte [Amazon OpenSearch Service - Service Level Agreement](https://aws.amazon.com/opensearch-service/sla/).
**Topics**
+ [Cotas de plug-ins](#plugin-limits)
+ [Pré-requisitos](#custom-plugin-prerequisites)
+ [Solução de problemas](#custom-plugin-troubleshooting)
+ [Instalar um plug-in personalizado usando o console](#custom-plugin-install-console)
+ [Gerenciando plug-ins personalizados usando o AWS CLI](#managing-custom-plugins-cli)
+ [AWS KMS Integração de pacotes personalizados do Amazon OpenSearch Service](custom-package-kms-integration.md)
## Cotas de plug-ins
+ Você pode criar até 25 plugins personalizados por conta, por região.
+ O tamanho máximo de um plug-in sem compactação é 1 GB.
+ O número máximo de servidores que podem ser associados a um único domínio é 20. Essa cota se aplica a todos os tipos de plug-in combinados: opcionais, de terceiros e personalizados.
+ Os plug-ins personalizados são compatíveis com domínios que executam a OpenSearch versão 2.15 ou posterior.
+ O arquivo `descriptor.properties` do plug-in deve ser compatível com uma versão de mecanismo semelhante à 2.15.0 ou qualquer versão 2.x.x, na qual a versão do patch é definida como zero.
## Pré-requisitos
Antes de instalar um plug-in personalizado e associá-lo a um domínio, certifique-se de que os seguintes requisitos são atendidos:
+ A versão do mecanismo compatível com o plug-in no arquivo `descriptor.properties` deve ser semelhante à `2.15.0` ou `2.x.0`. Ou seja, a versão do patch deve ser zero.
+ Os seguintes atributos devem estar habilitados no domínio:
+ [Node-to-node criptografia](ntn.md)
+ [Criptografia em repouso](encryption-at-rest.md)
+ [`EnforceHTTPS` está definido como 'verdadeiro'](createupdatedomains.md)
Veja também [opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html)no *Guia do AWS Config desenvolvedor*.
+ Os clientes devem ser compatíveis com a **Policy-Min-TLS-1-2-PFS-2023-10**. É possível especificar essa compatibilidade usando o comando a seguir. Substitua *placeholder value* o por suas próprias informações:
```
aws opensearch update-domain-config \
--domain-name domain-name \
--domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }'
```
Para obter mais informações, consulte [DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html)a *Amazon OpenSearch Service API Reference*.
## Solução de problemas
Se o sistema retornar o erro `PluginValidationFailureReason : The provided plugin could not be loaded`, consulte [Ocorre falha na instalação do plug-in personalizado devido a incompatibilidade entre versões](handling-errors.md#troubleshooting-custom-plugins) para obter informações de solução de problemas.
## Instalar um plug-in personalizado usando o console
Para associar um plug-in de terceiros a um domínio, primeiro importe a licença e a configuração do plug-in como pacotes.
**Para instalar um plug-in personalizado**
1. Faça login no console do Amazon OpenSearch Service em [https://console.aws.amazon.com/aos/casa](https://console.aws.amazon.com/aos/home).
1. No painel de navegação à esquerda, selecione **Pacotes**.
1. Escolha **Importar pacote**.
1. Em **Nome**, insira um nome exclusivo e fácil de identificar para o plug-in.
1. (Opcional) Em **Descrição**, forneça todos os detalhes úteis sobre o pacote ou sua finalidade.
1. Em **Tipo de pacote**, escolha **Plug-in**.
1. Em **Origem do pacote**, insira o caminho ou navegue até o arquivo ZIP do plug-in no Amazon S3.
1. Para a **versão do OpenSearch mecanismo**, escolha a versão compatível com OpenSearch o plug-in.
1. Em **Criptografia de pacote**, escolha se a chave de criptografia do pacote será personalizada ou não. Por padrão, o OpenSearch Service criptografa o pacote do plug-in com um Chave pertencente à AWS. Também é possível usar uma chave gerenciada pelo cliente.
1. Escolha **Importar**.
Depois de importar o pacote do plug-in, associe-o a um domínio. Para instruções, consulte [Importar e associar um pacote a um domínio](custom-packages.md#associate-console).
## Gerenciando plug-ins personalizados usando o AWS CLI
Você pode usar o AWS CLI para gerenciar várias tarefas personalizadas do plug-in.
**Topics**
+ [Instalando um plug-in personalizado usando o AWS CLI](#custom-plugin-install-cli)
+ [Atualizando um plug-in personalizado usando o AWS CLI](#custom-plugin-update-cli)
+ [Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança](#custom-plugin-kms-key-security-cli)
+ [Atualizando um domínio OpenSearch de serviço com plug-ins personalizados para uma versão posterior do OpenSearch uso do AWS CLI](#custom-plugin-domain-upgrade-cli)
+ [Desinstalar e visualizar o status de desassociação de um plug-in personalizado](#custom-plugin-uninstall-cli)
### Instalando um plug-in personalizado usando o AWS CLI
**Antes de começar**
Antes de associar um plug-in personalizado ao domínio, você deve carregá-lo em um bucket do Amazon Simple Storage Service (Amazon S3). O bucket deve estar localizado no mesmo Região da AWS local em que você pretende usar o plug-in. Para mais informações sobre carregar um objeto em um buckets do S3, consulte [Fazer upload de objetos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) no *Guia do usuário do Amazon Simple Storage Service*.
Se o pacote contiver informações sensíveis, especifique a criptografia no lado do servidor com chaves gerenciadas pelo S3 ao carregá-lo. Depois de carregar o arquivo, anote o caminho do S3. O formato do caminho é `s3://amzn-s3-demo-bucket/file-path/file-name`.
**nota**
Opcionalmente, você pode proteger um plug-in personalizado ao criar o plug-in especificando uma chave AWS Key Management Service (AWS KMS). Para mais informações, consulte [Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança](#custom-plugin-kms-key-security-cli).
**Para instalar um plug-in personalizado usando o AWS CLI**
1. Crie um novo pacote para seu plug-in personalizado executando o seguinte comando [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) e garantindo que os seguintes requisitos sejam atendidos:
+ O bucket e a localização da chave devem apontar para o arquivo `.zip` do plug-in em um bucket do S3 na conta em que você executa os comandos.
+ O bucket do S3 deve estar na mesma região em que o pacote está sendo criado.
+ Somente arquivos `.zip` são compatíveis com pacotes `ZIP-PLUGIN`.
+ O conteúdo do arquivo `.zip` deve seguir a estrutura de diretórios conforme esperado pelo plug-in.
+ O valor fornecido em `--engine-version` deve estar no formato `OpenSearch_{MAJOR}.{MINOR}`. Por exemplo: **OpenSearch\$12.17**.
Substitua *placeholder values* o por suas próprias informações:
```
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. (Opcional) Visualize o status da operação `create-package`, incluindo quaisquer descobertas de validação e vulnerabilidade de segurança, usando o comando [describe-packages](https://docs.aws.amazon.com/cli/latest/reference/es/describe-packages.html). Substitua *placeholder values* o por suas próprias informações:
```
aws opensearch describe-packages \
--region region \
--filters '[{"Name": "PackageType","Value": ["ZIP-PLUGIN"]}, {"Name": "PackageName","Value": ["package-name"]}]'
```
O comando retorna informações semelhantes às seguintes:
```
{
"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"
}]
}
```
**nota**
Durante a `create-package` operação, o Amazon OpenSearch Service verifica o `ZIP-PLUGIN` valor da compatibilidade de versões, extensões de plug-in suportadas e vulnerabilidades de segurança. As vulnerabilidades de segurança são examinadas usando o serviço [Amazon Inspector](https://aws.amazon.com/inspector/getting-started/). Os resultados dessas verificações são mostrados no campo `ErrorDetails` da resposta da API.
1. Use o comando [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) para associar o plug-in ao domínio de OpenSearch serviço de sua escolha usando o ID do pacote criado na etapa anterior.
**dica**
Se você tiver vários plug-ins, poderá usar o comando [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) para associar vários pacotes a um domínio em uma única operação.
Substitua *placeholder values* o por suas próprias informações:
```
aws opensearch associate-package \
--domain-name domain-name \
--region region \
--package-id package-id
```
**nota**
O plug-in é instalado e desinstalado usando um [processo de implantação azul/verde](managedomains-configuration-changes.md).
1. (Opcional) Use o [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)comando para visualizar o status da associação. O status da associação se altera à medida que o fluxo de trabalho avança de `ASSOCIATING` para `ACTIVE`. O status da associação passa para ATIVO após a conclusão da instalação do plug-in, e ele está pronto para uso.
Substitua *placeholder values* por suas próprias informações.
```
aws opensearch list-packages-for-domain \
--region region \
--domain-name domain-name
```
### Atualizando um plug-in personalizado usando o AWS CLI
Use o comando [update-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/update-package.html) para fazer alterações em um plug-in.
**nota**
Opcionalmente, você pode proteger um plug-in personalizado ao atualizar o plug-in especificando uma chave AWS Key Management Service (AWS KMS). Para mais informações, consulte [Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança](#custom-plugin-kms-key-security-cli).
**Para atualizar um plug-in personalizado usando o AWS CLI**
+ Execute o comando a seguir. Substitua *placeholder values* por suas próprias informações.
```
aws opensearch update-package \
--region region \
--package-id package-id \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--package-description description
```
Depois de atualizar um pacote, você pode usar o comando [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) ou [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) para aplicar atualizações de pacote em um domínio.
**nota**
Você pode auditar, criar, atualizar, associar e desassociar operações no plug-in usando AWS CloudTrail. Para obter mais informações, consulte [Monitorando chamadas OpenSearch de API do Amazon Service com AWS CloudTrail](managedomains-cloudtrailauditing.md).
### Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança
Opcionalmente, você pode proteger um plug-in personalizado ao atualizá-lo ou atualizá-lo especificando uma chave do AWS KMS . Para fazer isso, defina `PackageEncryptionOptions` como `true` e especifique o nome do recurso da Amazon (ARN) da chave, como mostrado nos exemplos a seguir.
**Exemplo: criar um plug-in personalizado com AWS KMS chave de segurança**
```
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"
}
```
**Exemplo: atualizar um plug-in personalizado com a AWS KMS chave de segurança**
```
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"
}
```
**Importante**
Se a AWS KMS chave especificada for desativada ou excluída, ela poderá deixar o cluster associado inoperacional.
Para obter mais informações sobre AWS KMS integração com pacotes personalizados,[AWS KMS Integração de pacotes personalizados do Amazon OpenSearch Service](custom-package-kms-integration.md).
### Atualizando um domínio OpenSearch de serviço com plug-ins personalizados para uma versão posterior do OpenSearch uso do AWS CLI
Quando você precisar atualizar um domínio OpenSearch de serviço que usa plug-ins personalizados para uma versão posterior do OpenSearch, conclua os processos a seguir.
**Para atualizar um domínio OpenSearch de serviço com plug-ins personalizados para uma versão posterior do OpenSearch uso do AWS CLI**
1. Use o comando create-package para criar um novo pacote para seu plug-in especificando a nova versão. OpenSearch
O nome do pacote deve ser o mesmo para o plug-in de todas as versões do mecanismo. A alteração do nome do pacote faz com que o processo de atualização do domínio falhe durante a blue/green implantação.
1. Atualize o domínio para a versão acima seguindo as etapas em [Atualizando domínios do Amazon OpenSearch Service](version-migration.md).
Durante esse processo, o Amazon OpenSearch Service desassocia a versão anterior do pacote de plug-ins e instala a nova versão usando uma implantação. blue/green
### Desinstalar e visualizar o status de desassociação de um plug-in personalizado
Para desinstalar o plug-in de qualquer domínio, use o comando [dissociate-package](https://docs.aws.amazon.com/cli/latest/reference/es/dissociate-package.html). A execução desse comando também remove as configurações ou pacotes de licença relacionados. Em seguida, você pode usar o [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/es/list-packages-for-domain.html)comando para visualizar o status da dissociação.
**dica**
Você também pode usar o comando [dissociate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/dissociate-packages.html) para desinstalar vários plug-ins de um domínio em uma única operação.
**Para desinstalar e visualizar o status de desassociação de um plug-in personalizado**
1. Desabilite o plug-in em todos os índices. Faça isso antes de desassociar o pacote de plug-in.
Se você tentar desinstalar um plug-in antes de desativá-lo de todos os índices, o processo de blue/green implantação permanecerá preso no `Processing` estado.
1. Execute o comando a seguir para desinstalar o plug-in. Substitua *placeholder values* por suas próprias informações.
```
aws opensearch dissociate-package \
--region region \
--package-id plugin-package-id \
--domain-name domain name
```
1. (Opcional) Execute o [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)comando para ver o status da dissociação.
# AWS KMS Integração de pacotes personalizados do Amazon OpenSearch Service
Os pacotes personalizados do Amazon OpenSearch Service fornecem criptografia por padrão para proteger seus `ZIP-PLUGIN` pacotes em repouso usando Chaves gerenciadas pela AWS.
+ **Chaves pertencentes à AWS**— Os pacotes personalizados do Amazon OpenSearch Service usam essas chaves por padrão para criptografar automaticamente seus `ZIP-PLUGIN` pacotes. Você não pode visualizar, gerenciar, usar Chaves pertencentes à AWS ou auditar seu uso. No entanto, você não precisa realizar nenhuma ação nem alterar nenhum programa para proteger as chaves que criptografam seus dados. Para saber mais, consulte [Chaves pertencentes à AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk) no *Guia do desenvolvedor do AWS Key Management Service *.
+ **Chaves gerenciadas pelo cliente** — Você pode adicionar uma segunda camada de criptografia sobre a existente Chaves pertencentes à AWS escolhendo uma chave gerenciada pelo cliente ao criar seu pacote `ZIP-PLUGIN` personalizado.
Os pacotes personalizados do Amazon OpenSearch Service oferecem suporte ao uso de uma chave simétrica gerenciada pelo cliente que você cria, possui e gerencia para adicionar uma segunda camada de criptografia sobre a criptografia existente AWS . Como você tem controle total dessa camada de criptografia, pode realizar as seguintes tarefas:
+ Estabelecer e manter as políticas de chaves
+ Estabelecer e manter AWS Identity and Access Management (IAM) políticas e subsídios
+ Habilitar e desabilitar políticas de chave
+ Alternar o material de criptografia de chaves
+ Adicionar tags.
+ Criar aliases de chaves
+ Programar a exclusão de chaves
Para saber mais, consulte [Chaves mestras do cliente (CMKs)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) no *AWS Key Management Service Guia do desenvolvedor*.
**nota**
Os pacotes personalizados do Amazon OpenSearch Service habilitam automaticamente a criptografia em repouso Chaves pertencentes à AWS , usando gratuitamente. No entanto, AWS KMS cobranças se aplicam quando você usa uma chave gerenciada pelo cliente. Para saber mais sobre preços, consulte [Preços do AWS Key Management Service](https://aws.amazon.com/kms/pricing/).
## Como o OpenSearch serviço de pacotes personalizados do Amazon Service usa subsídios em AWS KMS
OpenSearch Os pacotes personalizados de serviços exigem uma concessão para usar sua chave gerenciada pelo cliente.
Quando você cria um `ZIP-PLUGIN` pacote criptografado com uma chave gerenciada pelo cliente, o OpenSearch serviço de pacotes personalizados do Amazon Service cria uma concessão em seu nome enviando uma [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)solicitação para AWS KMS. As concessões concedem ao OpenSearch Serviço acesso a uma AWS KMS chave em sua conta. AWS KMS As concessões criadas pelos pacotes personalizados do OpenSearch Service têm uma restrição que permite operações somente quando a solicitação inclui um contexto de criptografia com seu ID de pacote personalizado.
Os pacotes personalizados do Amazon OpenSearch Service exigem que a concessão use sua chave gerenciada pelo cliente para as seguintes operações internas:
| Operation | Description |
| --- | --- |
| DescribeKey | Envia DescribeKey solicitações AWS KMS para verificar se o ID simétrico da chave gerenciada pelo cliente inserido ao criar o pacote de plug-ins é válido. |
| GenerateDataKeyWithoutPlaintext | Envia GenerateDataKeyWithoutPlaintext solicitações AWS KMS para gerar chaves de dados criptografadas pela chave gerenciada pelo cliente. |
| GenerateDataKey | Envia GenerateDataKey solicitações AWS KMS para gerar chaves de dados para criptografar o pacote ao copiá-lo internamente. |
| Decrypt | Envia Decrypt solicitações AWS KMS para descriptografar as chaves de dados criptografadas para que elas possam ser usadas para descriptografar seus dados. |
É possível revogar o acesso à concessão ou remover o acesso do serviço à chave gerenciada pelo cliente a qualquer momento. Se você fizer isso, o OpenSearch Serviço não poderá acessar nenhum dado criptografado pela chave gerenciada pelo cliente, o que afeta as operações que dependem desses dados. Por exemplo, se você tentar associar um pacote de plug-in que o OpenSearch Serviço não pode acessar, a operação retornará um `AccessDeniedException` erro.
## Criar uma chave gerenciada pelo cliente
Você pode criar uma chave simétrica gerenciada pelo cliente usando o Console de gerenciamento da AWS ou o. AWS KMS APIs
**Para criar uma chave simétrica gerenciada pelo cliente**
+ Para criar uma chave do KMS, siga as etapas em [Criar uma chave do KMS](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) no *Guia do desenvolvedor do AWS Key Management Service *.
### Política de chave
As políticas de chaves controlam o acesso à chave gerenciada pelo cliente. Cada chave gerenciada pelo cliente deve ter exatamente uma política de chaves, que contém declarações que determinam quem pode usar a chave e como pode usá-la. Ao criar a chave gerenciada pelo cliente, é possível especificar uma política de chave. Para saber mais, consulte [Políticas de chaves no AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) no *Guia do desenvolvedor do AWS Key Management Service *.
Para usar a chave gerenciada pelo cliente com os recursos, você deve permitir as seguintes operações de API na política de chave:
+ `kms:CreateGrant`: adiciona uma concessão a uma chave gerenciada pelo cliente. Concede acesso de controle a uma AWS KMS chave especificada, permitindo o acesso às operações de concessão exigidas pelos pacotes personalizados do OpenSearch Serviço. Para saber mais sobre o uso de concessões, consulte o [Guia do desenvolvedor do AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html).
Isso permite que o OpenSearch Serviço faça o seguinte:
+ Chame `GenerateDataKeyWithoutPlainText` para gerar uma chave de dados criptografada e armazená-la para validações adicionais.
+ Chame `GenerateDataKey` para copiar o pacote do plug-in internamente.
+ Chame `Decrypt` para acessar o pacote do plug-in internamente.
+ Configure uma entidade principal aposentada para permitir que o serviço para `RetireGrant`.
+ `kms:DescribeKey`— Fornece os detalhes da chave gerenciada pelo cliente para permitir que o OpenSearch Serviço valide a chave.
+ `kms:GenerateDataKey`,`kms:GenerateDataKeyWithoutPlaintext`, `kms:Decrypt` — Fornece acesso aos pacotes personalizados do OpenSearch Serviço para usar essas operações na concessão.
Veja a seguir exemplos de declarações de política que você pode adicionar aos pacotes personalizados do OpenSearch Service:
```
"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"
}
}
}
]
```
Para saber mais sobre a especificação de permissões em uma política, consulte [Políticas de chave no AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) no *Guia do desenvolvedor do AWS Key Management Service *.
Para obter mais informações sobre como solucionar problemas de acesso por chave, consulte [Solução de problemas de AWS KMS permissões](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html) no *Guia do AWS Key Management Service desenvolvedor*.
## Especifique uma chave gerenciada pelo cliente para pacotes personalizados do Amazon OpenSearch Service
Você pode especificar uma chave gerenciada pelo cliente como uma segunda camada de criptografia para pacotes `ZIP-PLUGIN`.
Ao criar um pacote de plug-in, você pode especificar a chave de dados inserindo um ID de AWS KMS chave, que os pacotes personalizados do OpenSearch Serviço usam para criptografar o pacote de plug-in.
*AWS KMS ID da chave* — Um identificador de chave para uma chave gerenciada pelo AWS KMS cliente. Insira uma ID de chave, um ARN de chave, um nome de alias ou um ARN de alias.
## Contexto de criptografia de pacotes personalizados do Amazon OpenSearch Service
Um contexto de criptografia é um conjunto opcional de pares de chave/valor que pode conter informações contextuais adicionais sobre os dados.
AWS KMS usa o contexto de criptografia como dados autenticados adicionais para oferecer suporte à criptografia autenticada. Quando você inclui um contexto de criptografia em uma solicitação para criptografar dados, AWS KMS vincula o contexto de criptografia aos dados criptografados. Para descriptografar os dados, você inclui o mesmo contexto de criptografia na solicitação.
### Contexto de criptografia de pacotes personalizados do Amazon OpenSearch Service
Os pacotes personalizados do Amazon OpenSearch Service usam o mesmo contexto de criptografia em todas as operações AWS KMS criptográficas, onde a chave está `packageId` e o valor é o `package-id` do seu pacote de plug-in.
### Usar o contexto de criptografia para monitoramento
Ao usar uma chave simétrica gerenciada pelo cliente para criptografar o pacote de plug-in, você também pode usar o contexto de criptografia em registros e logs de auditoria para identificar como a chave gerenciada pelo cliente está sendo usada. O contexto de criptografia também aparece nos registros gerados pelo AWS CloudTrail ou Amazon CloudWatch Logs.
### Usar o contexto de criptografia para controlar o acesso à chave gerenciada pelo cliente
Você pode usar o contexto de criptografia nas políticas de chave e políticas do IAM como condições para controlar o acesso à sua chave simétrica gerenciada pelo cliente. Você também pode usar restrições no contexto de criptografia em uma concessão.
OpenSearch Os pacotes personalizados de serviços usam uma restrição de contexto de criptografia nas concessões para controlar o acesso à chave gerenciada pelo cliente em sua conta ou região. A restrição da concessão exige que as operações permitidas pela concessão usem o contexto de criptografia especificado.
Veja a seguir exemplos de declarações de políticas de chave para conceder acesso a uma chave gerenciada pelo cliente para um contexto de criptografia específico. A condição nesta declaração de política exige que as concessões tenham uma restrição de contexto de criptografia que especifique o contexto de criptografia.
```
{
"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"
}
}
}
```
## Monitorando suas chaves de criptografia para serviços de pacotes OpenSearch personalizados
Ao usar uma chave gerenciada pelo AWS KMS cliente com seus recursos de OpenSearch serviço de pacotes personalizados de serviços, você pode usar CloudTrail ou CloudWatch Logs para rastrear solicitações enviadas por pacotes OpenSearch personalizados AWS KMS.
**Saiba mais**
Os recursos a seguir fornecem mais informações sobre a criptografia de dados em repouso.
+ Para obter mais informações sobre conceitos AWS KMS básicos, consulte [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)o *Guia do AWS Key Management Service desenvolvedor*.
+ Para obter mais informações sobre as melhores práticas de segurança AWS KMS, consulte o guia de *orientação AWS prescritiva* para obter [AWS Key Management Service as melhores](https://docs.aws.amazon.com/kms/latest/developerguide/best-practices.html) práticas.