Plug-ins personalizados

Os plug-ins personalizados para o Amazon OpenSearch Service são uma nova opção de gerenciamento de plug-ins que amplia a OpenSearch funcionalidade em áreas como análise de linguagem, filtragem personalizada e classificação, permitindo que você crie experiências de pesquisa personalizadas. Os plug-ins personalizados para OpenSearch podem ser desenvolvidos estendendo a org.opensearch.plugins.Plugin classe e, em seguida, empacotados como um arquivo.zip. As seguintes extensões de plug-in são atualmente suportadas pelo Amazon OpenSearch Service:

• Plugin de análise: amplia a funcionalidade de análise adicionando analisadores personalizados, tokenizadores de caracteres ou filtros para processamento de texto.

• Plugin de pesquisa: aprimora os recursos de pesquisa com tipos de consulta personalizados, algoritmos de similaridade, opções de sugestão e agregações.

Você pode usar o console do Amazon OpenSearch Service ou os existentes APIs para pacotes personalizados para carregar e associar um plug-in ao seu domínio do Amazon OpenSearch Service. Para obter mais informações sobre pacotes personalizados, consulte Pacotes personalizados para o Amazon OpenSearch Service. Além disso, você pode usar DescribePackages para descrever todos os pacotes em sua conta para ver detalhes como qual OpenSearch versão está em uso no momento ou detalhes do erro. O Amazon OpenSearch Service valida o pacote de plug-ins quanto à compatibilidade de versões, vulnerabilidades de segurança e operações permitidas de plug-ins.

Os plug-ins personalizados são compatíveis com domínios de OpenSearch serviço que executam a OpenSearch versão 2.15 ou posterior e estão disponíveis em 14 regiões em todo o mundo: Oeste dos EUA (Oregon), Leste dos EUA (Norte da Virgínia), América do Sul (São Paulo), Europa (Paris), Europa (Londres), Europa (Irlanda), Europa (Frankfurt), Canadá (Central), Ásia-Pacífico (Tóquio), Ásia-Pacífico (Sydney), Ásia-Pacífico (Cingapura) Singapura), Ásia-Pacífico (Seul) e Ásia-Pacífico (Mumbai).

nota

Os plug-ins personalizados contêm código desenvolvido pelo usuário. Quaisquer problemas, incluindo SLA violações, causados pelo código desenvolvido pelo usuário não serão elegíveis para SLA créditos. Para obter mais informações, consulte SLA Exclusões do Amazon OpenSearch Service em Amazon OpenSearch Service - Service Level Agreement.

Limites do plug-in

Você pode criar até 25 plug-ins personalizados por conta. O número máximo de plug-ins que podem ser associados a um único domínio é 20. Esse número inclui todos os tipos de plug-ins, ou seja, opcionais, de terceiros ou personalizados. O tamanho máximo permitido sem compressão para um plug-in é de 1 GB.

A tabela a seguir lista os recursos que não estão disponíveis ao usar plug-ins personalizados:

Recursos do Amazon OpenSearch Service	Plug-ins personalizados
Pesquisa entre clusters	Não compatível.
Replicação entre clusters	Sem compatibilidade
Reindexação remota	Sem compatibilidade
Ajuste automático	Sem compatibilidade
Multi-AZ com modo de espera	Sem compatibilidade
Interface de OpenSearch usuário centralizada	Sem compatibilidade

Usando plug-ins personalizados com o OpenSearch Service

Pré-requisitos para usar plug-ins personalizados com o Service OpenSearch

Antes de usar plug-ins personalizados com o Amazon OpenSearch Service, você precisará ter certeza de que tem a seguinte configuração:

• Criptografia de nó a nó

• Criptografia de dados em repouso

• Aplicar HTTPS definido como true

• Os clientes devem suportar TLSSecurityPolicy 'Policy-Min-TLS-1-2-PFS-2023-10', você pode configurar isso com o seguinte comando:

  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.

• O arquivo descriptor.properties da versão do mecanismo compatível com seu plug-in deve ser semelhante à 2.15.0 ou a versão do patch 2.x.0.i.e deve ser zero.

Instalando plug-ins personalizados com AWS CLI

Você pode instalar plug-ins personalizados usando AWS CLI o. Antes de associar um plug-in personalizado ao seu domínio, você deve carregá-lo em um bucket do Amazon S3. Você deve criar o bucket do Amazon S3 na mesma região em que pretende usar o plug-in. Para obter instruções sobre como fazer isso, consulte Carregar objetos no guia O que é o Amazon S3. Se o plug-in contiver informações confidenciais, selecione a criptografia do lado do servidor com chaves gerenciadas pelo S3 ao fazer o upload. Depois de fazer o upload do arquivo, anote o caminho do Amazon S3. Veja o seguinte exemplo de formato de caminho do Amazon S3:

s3://bucket-name/file-path/file-name

Você precisará criar um novo pacote para seu plug-in personalizado. Você pode fazer isso usando o existente CreatePackageAPI. Ao criar seu novo pacote, atualize o bucket e o local da chave para apontar para o arquivo.zip do seu plug-in personalizado no bucket Amazon S3 da conta de chamada. Observe que seu bucket do Amazon S3 deve estar na mesma região do pacote que está sendo criado. Somente arquivos.zip são compatíveis com ZIP-PLUGIN pacotes. O conteúdo do arquivo.zip deve seguir a estrutura de diretórios conforme esperado pelo plug-in. Para criar um pacote, veja o exemplo a seguir:

aws opensearch --region $REGION create-package --package-name <package-name> --package-type ZIP-PLUGIN --package-source S3BucketName=<bucket>,S3Key=<key> --engine-version OpenSearch_2.15

Você pode visualizar o status da operação de criação de pacote, incluindo quaisquer erros de validação e descoberta de vulnerabilidade de segurança usando o describe-packages. Para fazer isso, veja o exemplo a seguir:

aws opensearch --region $REGION describe-packages --filters '[{"Name": "PackageType","Value": ["ZIP-PLUGIN"]}, {"Name": "PackageName","Value": ["<package-name>"]}]'

A seguir está um exemplo de resposta dos pacotes describe: API

{ "PackageDetailsList": [ { 
"PackageID": "pkg-identifier", 
"PackageName": "custom-plugin-test", 
"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 operação de criação do pacote, o Amazon OpenSearch Service verifica a ZIP-PLUGIN compatibilidade da versão, as extensões de plug-in suportadas e as vulnerabilidades de segurança. Em particular, as vulnerabilidades de segurança são verificadas usando o serviço Amazon Inspector. Os resultados dessas verificações são mostrados no ErrorDetails campo da API resposta.

Use o AssociatePackageAPIpara associar o plug-in ao seu domínio do Amazon OpenSearch Service usando o ID do pacote criado na etapa anterior. Se você tiver vários plug-ins, poderá usar o AssociatePackagesAPIpara associar vários pacotes a um domínio em uma única operação. Para fazer isso, veja o exemplo a seguir:

aws opensearch --region $REGION associate-package --domain-name <domain-name> --package-id <package-id>

nota

Os plug-ins são instalados e desinstalados usando um processo de implantação azul/verde.

Você pode usar o ListPackagesForDomainAPIpara ver o status da associação. O status da associação mudará à medida que o fluxo de trabalho progride de ASSOCIATING paraACTIVE. O status da associação muda para ACTIVE quando o fluxo de trabalho de instalação do plug-in estiver concluído e seu plug-in estiver pronto para ser usado. Para fazer isso, veja o exemplo a seguir:

aws opensearch --region $REGION list-packages-for-domain
      --domain-name <domain-name>

Atualizando plug-ins personalizados

Você pode atualizar plug-ins personalizados usando os existentes UpdatePackageAPI. Você pode usar o API exemplo de pacotes associados a seguir para aplicar atualizações de pacotes a um domínio. Para fazer isso, veja o exemplo a seguir:

aws opensearch --region $REGION update-package --package-id <package-id>  --package-source S3BucketName=<bucket>,S3Key=<key> --package-description <description>

nota

Você pode auditar as operações de criação, atualização, associação e dissociação em seu plug-in usando AWS CloudTrail. Para obter mais informações, consulte a documentação Monitorando API chamadas do Amazon OpenSearch Service com AWS CloudTrail.

Atualizando seu domínio com plug-ins personalizados

Para atualizar seu domínio do Amazon OpenSearch Service que tem plug-ins personalizados associados a uma versão posterior do OpenSearch, você pode usar o CreatePackageAPIpara criar um novo pacote para seu plug-in.

nota

Certifique-se de que o nome do pacote seja o mesmo para o plug-in em todas as versões do mecanismo. A alteração do nome do pacote fará com que o processo de upgrade do domínio falhe durante a implantação azul/verde.

Para obter instruções sobre como atualizar seu domínio do Amazon OpenSearch Service, consulte Atualizando o Amazon OpenSearch Service. O Amazon OpenSearch Service desassociará a versão anterior do seu pacote de plug-in e instalará a nova versão do plug-in por meio de uma implantação azul/verde.

Criptografando plug-ins personalizados

Ao usar o CreatePackageAPI, você pode definir o PackageEncryptionOptions para true e passar a KMS chave ARN que você gostaria de usar para criptografia. Para fazer isso, veja o exemplo a seguir:

aws opensearch --region $REGION create-package --package-name <package-name> --package-type ZIP-PLUGIN --package-source S3BucketName=<bucket>,S3Key=<key> --engine-version OpenSearch_2.15   
"PackageConfigOptions": {
     ...
  }
  "PackageEncryptionOptions": {
    "Enabled": true,
    "KmsKeyId":"kms_key_arn"
  }

Você pode ativar a mesma opção ao atualizar o pacote usando UpdatePackageAPIo.

nota

Se uma KMS chave de chave for desativada ou excluída, ela poderá deixar o cluster inoperacional.

Desinstalando plug-ins personalizados

Você pode desinstalar plug-ins personalizados usando os existentes DissociatePackageAPIpara desinstalar um plug-in de um domínio. Essa etapa também remove qualquer configuração relacionada e/ou pacotes de licença associados ao plug-in. Você pode usar o existente ListPackagesForDomainAPIpara ver o status da dissociação. Além disso, você também pode usar o DissociatePackagesAPIpara desinstalar vários plug-ins de um domínio em uma única operação.

Você pode usar o API exemplo de pacotes dissociados a seguir para aplicar atualizações de pacotes a um domínio. Para fazer isso, veja o exemplo a seguir:

aws opensearch --region $REGION dissociate-package --package-id <plugin-package-id> --domain-name <domain-name>

nota

Para desinstalar um plug-in, primeiro você precisará desabilitar o plug-in de todos os índices antes de dissociar o pacote do plug-in. Se você tentar desinstalar um plug-in sem desativá-lo de todos os índices, o processo de implantação azul/verde ficará preso no estado de processamento.