Amazon OpenSearch インジェストパイプラインの作成 - Amazon OpenSearch サービス

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon OpenSearch インジェストパイプラインの作成

パイプラインは、Amazon OpenSearch Ingestion がソース (データの出所) からシンク (データの移動先) にデータを移動するために使用するメカニズムです。 OpenSearch インジェストでは、シンクは常に単一の Amazon OpenSearch サービスドメインですが、データのソースは Amazon S3、Fluent Bit、Collector などのクライアントである可能性があります。 OpenTelemetry

詳細については、ドキュメントの「パイプライン」を参照してください。 OpenSearch

前提条件と必要なロール

OpenSearch Ingestion パイプラインを作成するには、以下のリソースが必要です。

  • OpenSearch Ingestion がシンクに書き込むために引き受ける IAM ロール。このロールの ARN をパイプライン設定に含めます。

  • OpenSearch OpenSearch シンクとして機能するサービスドメインまたはサーバーレスコレクション。ドメインに書き込む場合は、 OpenSearch 1.0 以降、または Elasticsearch 7.4 以降を実行している必要があります。シンクには、IAM パイプラインロールに適切な許可を付与するアクセスポリシーが必要です。

これらのリソースの作成手順については、次の各トピックを参照してください。

注記

きめ細かなアクセスコントロールを使用するドメインに書き込む場合は、追加の手順を実行する必要があります。ステップ 3: パイプラインロールをマッピングする (きめ細かいアクセスコントロールを使用するドメインについてのみ) を参照してください。

必要なアクセス許可

OpenSearch インジェストでは、次の IAM 権限を使用してパイプラインを作成します。

  • osis:CreatePipeline — パイプラインを作成します。

  • osis:ValidatePipeline — パイプライン設定が有効かどうかを確認します。

  • iam:PassRole— パイプラインロールを OpenSearch Ingestion に渡して、ドメインにデータを書き込めるようにします。このアクセス許可は、パイプラインロールリソース (パイプライン設定の sts_role_arn オプションで指定する ARN) にある必要があります。また、パイプラインごとに異なるロールを使用する場合は、* を使用します。

例えば、次のポリシーは、パイプラインを作成するためのアクセス許可を付与します。

{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Resource":"*", "Action":[ "osis:CreatePipeline", "osis:ListPipelineBlueprints", "osis:ValidatePipeline" ] }, { "Resource":[ "arn:aws:iam::{your-account-id}:role/{pipeline-role}" ], "Effect":"Allow", "Action":[ "iam:PassRole" ] } ] }

OpenSearch インジェストにはosis:Ingest署名バージョン 4 を使用して署名付きリクエストをパイプラインに送信するために必要な、という権限も含まれます。詳細については、「取り込みロールの作成」を参照してください。

注記

また、アカウントで最初にパイプラインを作成するユーザーは、iam:CreateServiceLinkedRole アクションの許可を有している必要があります。詳細については、「パイプラインロールリソース」を参照してください。

各権限について詳しくは、『サービス認証リファレンス』の「 OpenSearch インジェストのアクション、リソース、および条件キー」を参照してください。

パイプラインのバージョンの指定

パイプラインを設定するときは、パイプラインを実行する Data Prepper のメジャーバージョンを指定する必要があります。バージョンを指定するには、パイプライン設定に version オプションを含めます。

version: "2" log-pipeline: source: ...

Create を選択すると、 OpenSearch Ingestion は指定したメジャーバージョンの最新マイナーバージョンを判断し、そのバージョンでパイプラインをプロビジョニングします。たとえば、Data Prepper の最新サポートバージョンが 2.1.1 version: "2" と指定した場合、 OpenSearch Ingestion はパイプラインをバージョン 2.1.1 でプロビジョニングします。パイプラインで実行されているマイナーバージョンは公開されません。

Data Prepper の新しいメジャーバージョンが利用可能になったときに、パイプラインをアップグレードするには、パイプライン設定を編集して新しいバージョンを指定します。パイプラインを以前のバージョンにダウングレードすることはできません。

注記

OpenSearch インジェストは、新しいバージョンの Data Prepper がリリースされてもすぐにはサポートされません。新しいバージョンが一般公開されてから、Ingestion でサポートされるまでの間には多少の遅れがあります。 OpenSearch さらに、 OpenSearch Ingestion は特定のメジャーバージョンまたはマイナーバージョンを完全にサポートしない場合があります。詳細な一覧については、「サポートされている Data Prepper のバージョン」を参照してください。

ブルー/グリーンデプロイを開始するパイプラインに変更を加えると、 OpenSearch Igestion はパイプラインの YAML ファイルに現在設定されているメジャーバージョンの最新のマイナーバージョンにアップグレードできます。詳細については、「」を参照してください。パイプライン更新用のブルー/グリーンデプロイ OpenSearch versionパイプライン設定内のオプションを明示的に更新しない限り、取り込みによってパイプラインのメジャーバージョンを変更することはできません。

取り込みパスの指定

Otel トレースや oTel メトリクスなどのプルベースのソースの場合、 OpenSearch Ingestion path ではソース設定に追加のオプションが必要です。パスは /log/ingest のような文字列で、取り込み用の URI パスを示しています。このパスが、データをパイプラインに送信する際に使用する URI を定義します。

例えば、logs という名前の取り込みパイプラインに次のエントリサブパイプラインを指定したとします。

entry-pipeline: source: http: path: "/my/test_path"

パイプラインにデータを取り込むときは、クライアント設定で次のエンドポイントを指定する必要があります: https://logs-abcdefgh.us-west-2.osis.amazonaws.com/my/test_path

パスはスラッシュ (/) から開始し、「-」、「_」、「.、「/」などの特殊文字や ${pipelineName} プレースホルダーを含めることができます。${pipelineName} (path: "/${pipelineName}/test_path" のように) を使用すると、変数は関連するサブパイプラインの名前に置き換えられます。この例では、https://logs.us-west-2.osis.amazonaws.com/entry-pipeline/test_path のようになります。

パイプラインの作成

このセクションでは、サービスコンソールとを使用して OpenSearch Igestion パイプラインを作成する方法について説明します。 OpenSearch AWS CLI

パイプラインを作成するには
  1. https://console.aws.amazon.com/aos/home の Amazon OpenSearch サービスコンソールにサインインします。

  2. 左側のナビゲーションペインで [パイプライン] をクリックし、次に [パイプラインを作成] をクリックします。

  3. パイプラインの名前を入力します。

  4. (オプション) [永続的バッファリングを有効にする] を選択します。永続的バッファリングは、複数の AZ にまたがってディスクベースのバッファにデータを保存します。詳細については、「永続的バッファリング」を参照してください。永続バッファを有効にする場合は、 AWS Key Management Service バッファデータを暗号化するキーを選択します。

  5. OpenSearch パイプラインの最小容量と最大容量をインジェストコンピュートユニット (OCU) で設定します。詳細については、「パイプラインのスケーリング」を参照してください。

  6. [パイプライン設定] で、パイプライン設定を YAML 形式で入力します。1 個のパイプライン設定ファイルには、1~10 個のサブパイプラインを含めることができます。各サブパイプラインは、1 個のソース、0 個以上のプロセッサ、1 個のシンクの組み合わせです。 OpenSearch Ingestion では、シンクは常にサービスドメインでなければなりません。 OpenSearch サポートされているオプションのリストについては、「Amazon OpenSearch Ingestion パイプラインでサポートされているプラグインとオプション」を参照してください。

    注記

    各サブパイプラインには sts_role_arn オプションと sigv4 オプションを含める必要があります。パイプラインは、sts_role_arn で定義されたルールを前提として、ドメインへのリクエストに署名します。詳細については、「Amazon OpenSearch Ingestion パイプラインへのドメインへのアクセス権の付与」を参照してください。

    以下のサンプル設定ファイルは、HTTP ソースと Grok プラグインを使用して非構造化ログデータを処理し、サービスドメインに送信します。 OpenSearch サブパイプラインには、log-pipeline という名前が付けられています。

    version: "2" log-pipeline: source: http: path: "/log/ingest" processor: - grok: match: log: [ '%{COMMONAPACHELOG}' ] - date: from_time_received: true destination: "@timestamp" sink: - opensearch: hosts: [ "https://search-my-domain.us-east-1.es.amazonaws.com" ] index: "apache_logs" aws: sts_role_arn: "arn:aws:iam::123456789012:role/{pipeline-role}" region: "us-east-1"
    注記

    YAML パイプライン定義内で複数のシンクを指定する場合、それらはすべて同じ Service ドメインでなければなりません。 OpenSearch OpenSearch Ingestion パイプラインは複数の異なるドメインに書き込むことはできません。

    独自のパイプライン設定を作成することもできますが、[ファイルをアップロード] をクリックして、セルフマネージド型の Data Prepper パイプラインの既存設定をインポートすることもできます。または、設定のブループリントを使用することもできます。

  7. パイプラインを設定したら、[パイプラインを検証] をクリックして設定が正しいことを確認します。検証に失敗した場合、エラーを修正して検証を再実行します。

  8. [ネットワーク] セクションで、[VPC アクセス] または [パブリックアクセス] を選択します。[パブリックアクセス] を選択した場合は、次のステップに進みます。[VPC アクセス] を選択した場合は、次の設定を行います。

    設定 説明
    VPC

    使用する仮想プライベートクラウド (VPC) の ID を選択します。VPC とパイプラインは同じ AWS リージョンの中になければなりません。

    サブネット

    1 つ以上のサブネットを選択してください。 OpenSearch サービスはサブネットに VPC エンドポイントと Elastic Network インターフェースを配置します

    セキュリティグループ

    パイプラインによって公開されるポート (80 または 443) とプロトコル (HTTP または HTTPS) で、必要なアプリケーションが OpenSearch Ingestion パイプラインに到達できるようにする VPC セキュリティグループを 1 つ以上選択します。

    詳細については、「VPC 内の Amazon OpenSearch Ingestion パイプラインの保護」を参照してください。

  9. (オプション) [タグ] で、1 つ以上のタグ (キーと値のペア) をパイプラインに追加します。詳細については、「Amazon OpenSearch Ingestion パイプラインのタグ付け」を参照してください。

  10. (オプション) [ログ公開オプション] で、Amazon CloudWatch Logs へのパイプラインログ発行を有効にします。パイプラインの問題をより簡単にトラブルシューティングできるように、ログの発行を有効にすることをお勧めします。詳細については、「パイプラインのログのモニタリング」を参照してください。

  11. [次へ] を選択します。

  12. パイプライン設定を確認したら、[作成] をクリックします。

OpenSearch インジェストはパイプラインを構築する非同期プロセスを実行します。パイプラインのステータスが Active になると、データの取り込みを開始できます。

create-pipeline コマンドは、パイプライン設定を文字列として、またはは .yaml ファイル内で受け入れます。設定を文字列として入力する場合、改行するたびに \n でエスケープする必要があります。例えば、次のようになります: "log-pipeline:\n source:\n http:\n processor:\n - grok:\n ...

次のサンプルコマンドは、以下にある設定でパイプラインを作成します。

  • 最低 4 つの取り込み OCU、最大 10 個の取り込み OCU

  • 仮想プライベートクラウド (VPC) 内でプロビジョニング

  • ログ発行の有効化

aws osis create-pipeline \ --pipeline-name my-pipeline \ --min-units 4 \ --max-units 10 \ --log-publishing-options IsLoggingEnabled=true,CloudWatchLogDestination={LogGroup="MyLogGroup"} \ --vpc-options SecurityGroupIds={sg-12345678,sg-9012345},SubnetIds=subnet-1212234567834asdf \ --pipeline-configuration-body "file://pipeline-config.yaml"

OpenSearch インジェストは非同期プロセスを実行してパイプラインを構築します。パイプラインのステータスが Active になると、データの取り込みを開始できます。パイプラインのステータスを確認するには、コマンドを使用します。GetPipeline

OpenSearch OpenSearch Ingestion API を使用してインジェストパイプラインを作成するには、オペレーションを呼び出します。CreatePipeline

パイプラインが正常に作成されたら、クライアントを設定し、サービスドメインへのデータの取り込みを開始できます。 OpenSearch 詳細については、「Amazon OpenSearch インジェストパイプラインインテグレーションとの連携」を参照してください。

パイプラインの作成ステータスの追跡

OpenSearch Ingestion がパイプラインをプロビジョニングし、データを取り込む準備をしている間、パイプラインのステータスを追跡できます。

パイプラインを最初に作成した後、 OpenSearch Igestion がデータを取り込む準備をする間、パイプラインは複数の段階を経ます。パイプライン作成のさまざまな段階を確認するには、パイプライン名をクリックして[パイプラインの設定] ページを表示します。[ステータス] で、[詳細を表示] をクリックします。

パイプラインは、データの取り込みが可能になるまでに次の段階を経ます。

  • 検証 — パイプライン設定を検証する。この段階が完了すると、すべての検証が成功したことになります。

  • 環境の作成 — リソースの準備とプロビジョニングを行います。この段階が完了すると、新しいパイプライン環境が作成されます。

  • パイプラインのデプロイ — パイプラインをデプロイします。この段階が完了すると、パイプラインは正常にデプロイされます。

  • パイプラインのヘルスチェック — パイプラインのヘルス状態をチェックします。この段階が完了すると、すべてのヘルスチェックを通過したことになります。

  • トラフィックの有効化 — パイプラインがデータを取り込むことができるようにします。この段階が完了すると、パイプラインへのデータの取り込みを開始できます。

get-pipeline-change-progressコマンドを使用して、パイプラインのステータスを確認します。 AWS CLI 次のリクエストは、という名前のパイプラインのステータスをチェックしますmy-pipeline

aws osis get-pipeline-change-progress \ --pipeline-name my-pipeline

レスポンス:

{ "ChangeProgressStatuses": { "ChangeProgressStages": [ { "Description": "Validating pipeline configuration", "LastUpdated": 1.671055851E9, "Name": "VALIDATION", "Status": "PENDING" } ], "StartTime": 1.671055851E9, "Status": "PROCESSING", "TotalNumberOfStages": 5 } }

OpenSearch Igestion API を使用してパイプライン作成のステータスを追跡するには、オペレーションを呼び出します。GetPipelineChangeProgress

ブループリントを使用したパイプラインの作成

パイプラインの定義をゼロから作成するのではなく、設定のブループリントを使用できます。設定のブループリントは、トレース分析や Apache ログなどの一般的な取り込みシナリオ用に事前設定された YAML テンプレートです。設定のブループリントを使用すると、設定をゼロから作成しなくても、パイプラインを簡単にプロビジョニングできます。

パイプラインのブループリントを使用するには
  1. https://console.aws.amazon.com/aos/home の Amazon OpenSearch サービスコンソールにサインインします。

  2. 左側のナビゲーションペインで [パイプライン] をクリックし、次に [パイプラインを作成] をクリックします。

  3. [パイプライン設定] で、[設定のブループリント] をクリックします。

  4. ブループリントを選択します。パイプライン設定には、選択したユースケースのサブパイプラインが入力されます。

  5. コメントアウトされたテキストを確認します。ここには、ブループリント設定についての説明が記載されています。

    重要

    パイプラインのブループリントは、そのままでは有効になりません。 AWS リージョン 認証に使用するおよびロール ARN を提供するなど、いくつかの変更を行う必要があります。そうしないと、パイプラインの検証が失敗します。

を使用して利用可能なすべてのブループリントのリストを取得するには AWS CLI、リクエストを送信してください。list-pipeline-blueprints

aws osis list-pipeline-blueprints

このリクエストは、利用可能なすべてのブループリントのリストを返します。

特定のブループリントに関する詳細情報を取得するには、以下のコマンドを使用します。get-pipeline-blueprint

aws osis get-pipeline-blueprint --blueprint-name AWS-ApacheLogPipeline

このリクエストは、Apache ログパイプラインブループリントの内容を返します。

{ "Blueprint":{ "PipelineConfigurationBody":"###\n # Limitations: https://docs.aws.amazon.com/opensearch-service/latest/ingestion/ingestion.html#ingestion-limitations\n###\n###\n # apache-log-pipeline:\n # This pipeline receives logs via http (e.g. FluentBit), extracts important values from the logs by matching\n # the value in the 'log' key against the grok common Apache log pattern. The grokked logs are then sent\n # to OpenSearch to an index named 'logs'\n###\n\nversion: \"2\"\napache-log-pipeline:\n source:\n http:\n # Provide the path for ingestion. ${pipelineName} will be replaced with pipeline name configured for this pipeline.\n # In this case it would be \"/apache-log-pipeline/logs\". This will be the FluentBit output URI value.\n path: \"/${pipelineName}/logs\"\n processor:\n - grok:\n match:\n log: [ \"%{COMMONAPACHELOG_DATATYPED}\" ]\n sink:\n - opensearch:\n # Provide an AWS OpenSearch Service domain endpoint\n # hosts: [ \"https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com\" ]\n aws:\n # Provide a Role ARN with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com\n # sts_role_arn: \"arn:aws:iam::123456789012:role/Example-Role\"\n # Provide the region of the domain.\n # region: \"us-east-1\"\n # Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection\n # serverless: true\n index: \"logs\"\n # Enable the S3 DLQ to capture any failed requests in an S3 bucket\n # dlq:\n # s3:\n # Provide an S3 bucket\n # bucket: \"your-dlq-bucket-name\"\n # Provide a key path prefix for the failed requests\n # key_path_prefix: \"${pipelineName}/logs/dlq\"\n # Provide the region of the bucket.\n # region: \"us-east-1\"\n # Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com\n # sts_role_arn: \"arn:aws:iam::123456789012:role/Example-Role\"\n", "BlueprintName":"AWS-ApacheLogPipeline" } }

OpenSearch Igestion API を使用してパイプラインブループリントに関する情報を取得するには、およびオペレーションを使用します。ListPipelineBlueprintsGetPipelineBlueprint