翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon OpenSearch Service でのカスタムプラグイン管理
OpenSearch Service のカスタムプラグインを使用すると、言語分析、カスタムフィルタリング、ランキングなどの領域で OpenSearch 機能を拡張できるため、パーソナライズされた検索エクスペリエンスを作成できます。OpenSearch 用のカスタムプラグインは、`org.opensearch.plugins.Plugin` クラスを拡張し、`.zip` ファイルにパッケージ化することで開発できます。
現在、Amazon OpenSearch Service では以下のプラグイン拡張機能がサポートされています。
+ **AnalysisPlugin** – カスタムアナライザー、文字トークナイザ、テキスト処理用のフィルターなどを追加して、分析機能を拡張します。
+ **SearchPlugin** – カスタムクエリタイプ、類似度アルゴリズム、提案オプション、集計を使用して検索機能を強化します。
+ **MapperPlugin** – OpenSearch でカスタムフィールドタイプとそのマッピング設定を作成し、さまざまなタイプのデータの保存方法とインデックス作成方法を定義できます。
+ **ScriptPlugin** – OpenSearch にカスタムスクリプト機能を追加できます。例えば、検索またはインデックス作成中のスコアリング、ソート、フィールド値変換などのオペレーション用のカスタムスクリプトなどです。
+ **SearchPipelinePlugin** – カスタム検索パイプライン機能を追加することで、Amazon OpenSearch Service の検索エクスペリエンスを調整できます。たとえば、調整ノードレベルで検索フェーズ間で実行されるカスタム`SearchPhaseResultsProcessor`実装、複数のスコアリング戦略を組み合わせるためのハイブリッド検索の再ランク付け、複数のデータソースの結果を集約するフェデレーティッド検索パイプラインなどです。
OpenSearch Service コンソールまたはカスタムパッケージの既存の API コマンドを使用して、プラグインをアップロードし、Amazon OpenSearch Service クラスターに関連付けることができます。[DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html) コマンドを使用して、アカウント内のすべてのパッケージを記述し、OpenSearch バージョンやエラーの詳細などの詳細情報を表示することもできます。OpenSearch Service は、プラグインパッケージのバージョン互換性、セキュリティの脆弱性、許可されたプラグインオペレーションを検証します。カスタムパッケージの詳細については、「[Amazon OpenSearch Service でのパッケージのインポートと管理](custom-packages.md)」を参照してください。
**OpenSearch のバージョンと AWS リージョン サポート**
カスタムプラグインは、以下の AWS リージョンで OpenSearch バージョン 2.15 を実行している OpenSearch Service ドメインでサポートされています。
+ 米国東部 (オハイオ) (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 Service - サービスレベルアグリーメント](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)
+ [Amazon OpenSearch Service カスタムパッケージ AWS KMS 統合](custom-package-kms-integration.md)
## プラグインクォータ
+ アカウントにつき、リージョンごとに最大 25 個のカスタムプラグインを作成できます。
+ プラグインの非圧縮状態での最大サイズは 1 GB です。
+ 1 つのドメインに関連付けることができるプラグインの最大数は 20 です。このクォータは、オプション、サードパーティー、カスタムからなるすべてのプラグインタイプの合計に適用されます。
+ カスタムプラグインは、OpenSearch バージョン 2.15 以降を実行しているドメインでサポートされています。
+ プラグインの `descriptor.properties` ファイルは、2.15.0 のようなエンジンバージョン、つまりパッチバージョンがゼロに設定されている 2.x.x バージョンをサポートしている必要があります。
## 前提条件
カスタムプラグインをインストールしてドメインに関連付ける際は、次の要件を満たしていることを確認してください。
+ `descriptor.properties` ファイル内のプラグインでサポートされているエンジンバージョンが `2.15.0` または `2.x.0` と同等であること。つまり、パッチバージョンがゼロである必要があります。
+ ドメインで以下の機能が有効になっていること。
+ [ノード間の暗号化](ntn.md)
+ [保管時の暗号化](encryption-at-rest.md)
+ [`EnforceHTTPS` が「true」に設定されている](createupdatedomains.md)
「*AWS Config デベロッパーガイド*」の「[opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html)」も参照してください。
+ クライアントは **Policy-Min-TLS-1-2-PFS-2023-10** をサポートする必要があります。以下のコマンドを使用することでこのサポートを指定できます。{{プレースホルダー値}}は、ユーザー自身の情報に置き換えてください。
```
aws opensearch update-domain-config \
--domain-name {{domain-name}} \
--domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }'
```
詳細については、「*Amazon OpenSearch Service API リファレンス*」の「[DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html)」を参照してください。
## トラブルシューティング
システムがエラー `PluginValidationFailureReason : The provided plugin could not be loaded` を返した場合、トラブルシューティング情報については「[バージョンの互換性の問題によりカスタムプラグインのインストールが失敗する](handling-errors.md#troubleshooting-custom-plugins)」を参照してください。
## コンソールを使用したカスタムプラグインのインストール
サードパーティープラグインをドメインに関連付けるには、まずプラグインのライセンスと設定をパッケージとしてインポートします。
**カスタムプラグインをインストールするには**
1. [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home) で Amazon OpenSearch Service コンソールにサインインします。
1. 左のナビゲーションペインで **[パッケージ]** を選択します。
1. [**パッケージのインポート**] を選択します。
1. **[名前]** に、このプラグインの一意の識別可能な名前を入力します。
1. (オプション) **[説明]** に、パッケージまたはその目的に関する有用な詳細を入力します。
1. **[パッケージタイプ]** で **[プラグイン]** を選択します。
1. **[パッケージソース]** に、パスを入力するか、Amazon S3 のプラグイン ZIP ファイルを参照して選択します。
1. **[OpenSearch エンジンのバージョン]** で、プラグインがサポートする OpenSearch のバージョンを選択します。
1. **[パッケージ暗号化]** で、パッケージの暗号化キーをカスタマイズするかどうかを選択します。デフォルトでは、OpenSearch Service はプラグインパッケージを 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 Service ドメインを新しいバージョンの 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\_2.17**。
{{プレースホルダー値}}は、ユーザー自身の情報に置き換えてください。
```
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` オペレーションのステータスを表示します。{{プレースホルダー値}}は、ユーザー自身の情報に置き換えてください。
```
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 OpenSearch Service は `ZIP-PLUGIN` の値について、バージョン互換性、サポートされているプラグイン拡張機能、セキュリティの脆弱性をチェックします。セキュリティの脆弱性は、[Amazon Inspector](https://aws.amazon.com/inspector/getting-started/) サービスを使用してスキャンされます。これらのチェックの結果は、API レスポンスの `ErrorDetails` フィールドに表示されます。
1. [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) コマンドを使用して、プラグインを任意の OpenSearch Service ドメインに関連付けます。その際は、前のステップで作成したパッケージのパッケージ ID を使用します。
**ヒント**
複数のプラグインがある場合は、代わりに [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) コマンドを使用します。これにより、1 回のオペレーションで複数のパッケージをドメインに関連付けることができます。
{{プレースホルダー値}}は、ユーザー自身の情報に置き換えてください。
```
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` に進行するにつれて変化します。プラグインのインストールが完了し、プラグインを使用できる状態になると、関連付けステータスは ACTIVE に変わります。
{{プレースホルダー値}}を、ユーザー自身の情報に置き換えます。
```
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**
+ 以下のコマンドを実行してください。{{プレースホルダー値}}を、ユーザー自身の情報に置き換えます。
```
aws opensearch update-package \
--region {{region}} \
--package-id {{package-id}} \
--package-source S3BucketName={{amzn-s3-demo-bucket}},S3Key={{s3-key}} \
--package-description {{description}}
```
パッケージを更新した後は、[ssociate-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。詳細については、「[を使用した Amazon OpenSearch Service 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 の統合の詳細については、「」を参照してください[Amazon OpenSearch Service カスタムパッケージ AWS KMS 統合](custom-package-kms-integration.md)。
### を使用して、カスタムプラグインを使用して OpenSearch Service ドメインを新しいバージョンの OpenSearch にアップグレードする AWS CLI
カスタムプラグインを使用する OpenSearch Service ドメインを、OpenSearch の新しいバージョンにアップグレードする必要がある場合は、以下のプロセスを実行してください。
**を使用して、カスタムプラグインを持つ OpenSearch Service ドメインを新しいバージョンの OpenSearch にアップグレードするには AWS CLI**
1. create-package コマンドを使用して、新しい OpenSearch バージョンを指定するプラグインの新しいパッケージを作成します。
すべてのエンジンバージョンのプラグインでパッケージ名が同じであることを確認します。パッケージ名を変更すると、ブルー/グリーンデプロイ中にドメインのアップグレードプロセスが失敗します。
1. 「[Amazon OpenSearch Service ドメインのアップグレード](version-migration.md)」の手順に従って、ドメインを上位バージョンにアップグレードします。
このプロセス中、Amazon OpenSearch Service は以前のバージョンのプラグインパッケージの関連付けを解除し、ブルー/グリーンデプロイを使用して新しいバージョンをインストールします。
### カスタムプラグインのアンインストールと、関連付け解除ステータスの表示
任意のドメインからプラグインをアンインストールするには、[disssociate-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 回のオペレーションでドメインから複数のプラグインをアンインストールすることもできます。
**カスタムプラグインをアンインストールして、関連付け解除ステータスを表示するには**
1. すべてのインデックスでプラグインを無効にします。これは、プラグインパッケージの関連付けを解除する前に行う必要があります。
すべてのインデックスからプラグインを無効にする前にプラグインをアンインストールしようとすると、ブルー/グリーンデプロイプロセスは `Processing` 状態でスタックしたままになります。
1. 次のコマンドを実行して、プラグインをアンインストールします。{{プレースホルダー値}}を、ユーザー自身の情報に置き換えます。
```
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) コマンドを実行して、関連付け解除のステータスを表示します。