本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 创建 Amazon OpenSearch Ingestion 管道 *管道*是 Amazon OpenSearch Ingestion 用来将数据从其*来源*（数据来源）移动到*接收器*（数据所在的地方）的机制。在 OpenSearch Ingestion 中，接收器将始终是单个亚马逊 OpenSearch 服务域，而您的数据来源可以是 Amazon S3、Fluent Bit 或 Collector 等客户端。 OpenTelemetry 有关更多信息，请参阅 OpenSearch 文档中的[管道](https://opensearch.org/docs/latest/clients/data-prepper/pipelines/)。 **Topics** + [先决条件和所需 IAM 角色](#manage-pipeline-prerequisites) + [所需的 IAM 权限](#create-pipeline-permissions) + [指定管道版本](#pipeline-version) + [指定提取路径](#pipeline-path) + [创建管道](#create-pipeline) + [跟踪管道创建的状态](#get-pipeline-progress) + [使用蓝图](pipeline-blueprint.md) ## 先决条件和所需 IAM 角色 要创建 OpenSearch 摄取管道，您必须拥有以下资源： + 一个名为*管道角色的 IAM 角色*， OpenSearch Ingestion 为了写入接收器而担任该角色。您可以提前创建此角色，也可以让 OpenSearch Ingestion 在创建管道时自动创建该角色。 + 充当接收器的 OpenSearch 服务域或 OpenSearch 无服务器集合。如果您要写入某个域，则该域必须运行的是 OpenSearch 1.0 或更高版本，或者运行 Elasticsearch 7.4 或更高版本。接收器必须具有向您的 IAM 管道角色授予相应权限的访问策略。 有关创建这些资源的说明，请参阅以下主题： + [向 Amazon OpenSearch Ingestion 管道授予对域名的访问权限](pipeline-domain-access.md) + [授予 Amazon OpenSearch Ingestion 管道访问集合的权限](pipeline-collection-access.md) **注意** 如果您要写入使用精细访问控制的域，则需要完成一些额外的步骤。请参阅[映射管道角色（仅适用于使用精细访问控制的域）](pipeline-domain-access.md#pipeline-access-domain-fgac)。 ## 所需的 IAM 权限 OpenSearch Ingestion 使用以下 IAM 权限来创建管道： + `osis:CreatePipeline`：创建管道。 + `osis:ValidatePipeline`：检查管道配置是否有效。 + `iam:CreateRole`以及 `iam:AttachPolicy` — 让 OpenSearch Ingestion 自动为您创建管道角色。 + `iam:PassRole`— 将管道角色传递给 OpenSearch Ingestion，这样它就可以向域写入数据。此权限必须位于[管道角色资源](pipeline-domain-access.md#pipeline-access-configure)上，或者如果您计划在每个管道中使用不同的角色，则仅 `*`。 例如，以下策略授予创建管道的权限： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Resource":"*", "Action":[ "osis:CreatePipeline", "osis:ListPipelineBlueprints", "osis:ValidatePipeline" ] }, { "Resource":[ "arn:aws:iam::111122223333:role/pipeline-role" ], "Effect":"Allow", "Action":[ "iam:CreateRole", "iam:AttachRolePolicy", "iam:PassRole" ] } ] } ``` ------ OpenSearch Ingestion 还包括一项名为的权限`osis:Ingest`，该权限是使用签[名版本](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) 4 向管道发送签名请求所必需的。有关更多信息，请参阅 [创建摄取角色](configure-client.md#configure-client-auth)。 **注意** 此外，第一个在账户中创建管道的用户必须拥有 `iam:CreateServiceLinkedRole` 操作的权限。有关更多信息，请参阅[管道角色资源](pipeline-security.md#pipeline-vpc-slr)。 有关每项权限的更多信息，请参阅《*服务授权*参考[ OpenSearch 》中的 “摄取操作、资源和条件密钥](https://docs.aws.amazon.com/service-authorization/latest/reference/list_opensearchingestionservice.html)”。 ## 指定管道版本 使用配置编辑器创建管道时，必须指定管道将运行的 [Data Prepper 的主要版本](https://github.com/opensearch-project/data-prepper/releases)。要指定版本，请在您的管道配置中包含以下 `version` 选项： ``` version: "2" log-pipeline: source: ... ``` 选择 “**创建**” 时， OpenSearch Ingestion 会确定您指定的主要版本的最新可用*次*要版本，并使用该版本预置管道。例如，如果您指定`version: "2"`，并且最新支持的 Data Prepper 版本为 2.1.1，则 OpenSearch Ingestion 会使用版本 2.1.1 来配置您的管道。我们不会公开显示您的管道正在运行的次要版本。 要在 Data Prepper 新的主要版本可用时升级管道，请编辑管道配置并指定新版本。您无法将管道降级到较早版本。 **注意** OpenSearch 新版本的 Data Prepper 发布后，Ingestion 不会立即支持这些版本。在新版本公开发行和 OpenSearch Ingestion 支持新版本之间会有一些延迟。此外， OpenSearch Ingestion 可能明确不完全支持某些主要版本或次要版本。有关完整列表，请参阅[支持的 Data Prepper 版本](ingestion.md#ingestion-supported-versions)。 每当你对启动 blue/green 部署的管道进行更改时， OpenSearch Ingestion 都可以将其升级到当前为管道配置的主要版本的最新次要版本。有关更多信息，请参阅[使用蓝绿部署进行管道更新](update-pipeline.md#pipeline-bg)。 OpenSearch 除非您在工作流配置中明确更新该`version`选项，否则 Ingestion 无法更改管道的主要版本。 ## 指定提取路径 对于基于拉取的来源，例如[OTel 跟踪](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/)和[OTel 指标](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/)， OpenSearch Ingestion 需要在源配置中添加其他`path`选项。路径是字符串（例如，`/log/ingest`），它表示提取的 URI 路径。此路径定义用于向管道发送数据的 URI。 例如，假设您为包含 HTTP 源的管道指定以下路径： ![\[Input field for specifying the path for ingestion, with an example path entered.\]](http://docs.aws.amazon.com/zh_cn/opensearch-service/latest/developerguide/images/ingestion-path.png) 向管道中[摄取数据](configure-client.md)时，必须在客户端配置中指定以下端点：`https://pipeline-name-abc123.us-west-2.osis.amazonaws.com/my/test_path`。 路径必须以斜杠 (/) 开头，可以包含特殊字符 '-'、'\$1'、'.'、'/' 以及 `${pipelineName}` 占位符。如果您使用`${pipelineName}`（例如`/${pipelineName}/test_path`）， OpenSearch Ingestion 会将变量替换为关联子管道的名称。 ## 创建管道 本节介绍如何 OpenSearch 使用 OpenSearch 服务控制台和。 AWS CLI ### 控制台 **要创建管道，请登录 [https://console.aws.amazon.com/aos/osis/hom](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) e 的亚马逊 OpenSearch 服务控制台，然后选择创建管道。** 您可以选择空白管道，也可以选择配置蓝图。蓝图包含针对多种常见使用案例预先配置的管道。有关更多信息，请参阅 [使用蓝图](pipeline-blueprint.md)。 选择**选择蓝图**。 #### 配置源 1. 如果您从空白管道开始，请从下拉菜单中选择源。可用来源可能包括其他 AWS 服务 OpenTelemetry、或 HTTP。有关更多信息，请参阅 [将 Amazon OpenSearch Ingestion 管道与其他服务和应用程序集成](configure-client.md)。 1. 根据您选择的源，为源配置其他设置。例如，要使用 Amazon S3 作为源，则必须指定管道接收消息的 Amazon SQS 队列的 URL。有关支持的源插件列表及其文档链接，请参阅 [Amazon OpenSearch Ingestion 管道支持的插件和选项](pipeline-config-reference.md)。 1. 对于某些源，必须指定**源网络选项**。选择 **VPC 访问权限**或**公共访问权限**。如果您选择**公有访问权限**，请跳至下一步。如果您选择 **VPC 访问**，请配置以下设置： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/opensearch-service/latest/developerguide/creating-pipeline.html) 有关更多信息，请参阅 [为 Amazon OpenSearch Ingestion 管道配置 VPC 访问权限](pipeline-security.md)。 1. 选择**下一步**。 #### 配置处理器 向管道添加一个或多个处理器。处理器是子管道中的组件，可在将记录发布到域或集合接收器之前对事件进行筛选、转换和增强。有关支持的处理器列表及其文档链接，请参阅 [Amazon OpenSearch Ingestion 管道支持的插件和选项](pipeline-config-reference.md)。 您可以选择**操作**，并添加以下内容： + **条件路由**：根据特定条件将事件路由到不同的接收器。有关更多信息，请参阅[条件路由](https://opensearch.org/docs/latest/data-prepper/pipelines/pipelines/#conditional-routing)。 + **子管道**：每个子管道都由一个来源、零个或多个处理器以及一个接收器组成。仅有一个子管道可以拥有外部源。其余所有子管道的源必须是整体管道配置中的其他子管道。单个管道配置可以包含 1-10 个子管道。 选择**下一步**。 #### 配置接收器 选择管道发布记录的目标位置。每个子管道必须至少包含一个接收器。最多可向管道添加 10 个接收器。 对于 OpenSearch 汇，请配置以下字段： | 设置 | 说明 | | --- | --- | | 网络策略名称（仅限无服务器接收器） | 如果您选择了 OpenSearch 无服务器集合，请输入**网络策略名称**。 OpenSearch Ingestion 要么创建策略（如果不存在），要么使用允许访问连接管道和集合的 VPC 终端节点的规则对其进行更新。有关更多信息，请参阅 [授予 Amazon OpenSearch Ingestion 管道访问集合的权限](pipeline-collection-access.md)。 | | 索引名 | 管道发送数据的索引名称。 OpenSearch 如果此索引尚不存在，则 Ingestion 会创建该索引。 | | 索引映射选项 | 选择管道如何将文档及其字段存储和索引到 OpenSearch 接收器中。如果选择 “**动态映射**”，则在为文档编制索引时会自动 OpenSearch 添加字段。如果选择**自定义映射**，则输入索引映射模板。有关更多信息，请参阅[索引模板](https://opensearch.org/docs/latest/im-plugin/index-templates/)。 | | 启用 DLQ | 为管道配置 Amazon S3 死信队列（DLQ）。有关更多信息，请参阅 [死信队列](osis-features-overview.md#osis-features-dlq)。 | | 其他设置 | 为 OpenSearch 水槽配置高级选项。有关更多信息，请参阅 Data Prepper 文档中的[配置选项](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/opensearch/#configuration-options)。 | 要添加 Amazon S3 接收器，请选择**添加接收器**和 **Amazon S3**。有关更多信息，请参阅 [Amazon S3 作为目标](configure-client-s3.md#s3-destination)。 选择**下一步**。 #### 配置管道 配置以下其他管道设置： | 设置 | 说明 | | --- | --- | | 管道名称 | 管道的唯一名称。 | | 持久缓冲区 | 持久缓冲功能将您的数据存储在跨多个可用区、基于磁盘的缓冲区中。有关更多信息，请参阅 [持久缓冲功能](osis-features-overview.md#persistent-buffering)。 如果启用持久缓冲功能，请选择 AWS Key Management Service 密钥以加密缓冲区数据。 | | 管道容量 | 最小和最大管道容量，以摄取 OpenSearch 计算单位 () OCUs 为单位。有关更多信息，请参阅 [在 Amazon OpenSearch Ingestion 中扩展管道](ingestion-scaling.md)。 | | 管道角色 | IAM 角色，为管道提供所需权限，使其能够向接收器写入数据并从基于拉取的源读取数据。你可以自己创建角色，也可以让 OpenSearch Ingestion 根据你选择的用例为你创建角色。 有关更多信息，请参阅 [在 Amazon OpenSearch Ingestion 中设置角色和用户](pipeline-security-overview.md)。 | | 标签 | 向管道添加一个或多个标签。有关更多信息，请参阅 [标记 Amazon OpenSearch Ingestion 管道](tag-pipeline.md)。 | | 日志发布选项 | 启用向 Amazon 日志发布管道 CloudWatch 日志。建议您启用日志发布，以便更轻松地解决管道问题。有关更多信息，请参阅 [监控管道日志](monitoring-pipeline-logs.md)。 | 选择**下一步**，然后检查您的管道配置，并选择**创建管道**。 OpenSearch Ingestion 运行异步进程来构建管道。当管道状态为 `Active` 时，您可以开始将数据提取到管道。 ### AWS CLI [create-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/create-pipeline.html) 命令接受以字符串形式或者在 .yaml 或 .json 文件中的管道配置。如果您以字符串形式提供配置，则必须使用 `\n` 转义每一个新行。例如，`"log-pipeline:\n source:\n http:\n processor:\n - grok:\n ...` 以下示例命令采用以下配置创建管道： + 最少 4 次摄入 OCUs，最多 10 次摄入 OCUs + 在虚拟私有云 (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" \ --pipeline-role-arn arn:aws:iam::1234456789012:role/pipeline-role ``` OpenSearch Ingestion 运行异步进程来构建管道。当管道状态为 `Active` 时，您可以开始将数据提取到管道。要检查管道的状态，请使用[GetPipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipeline.html)命令。 ### OpenSearch 摄取 API 要使用 OpenSearch Ingestion API 创建 OpenSearch 摄取管道，请调用该操作。[CreatePipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_CreatePipeline.html) 成功创建管道后，您可以配置客户端并开始将数据提取到您的 OpenSearch 服务域中。有关更多信息，请参阅 [将 Amazon OpenSearch Ingestion 管道与其他服务和应用程序集成](configure-client.md)。 ## 跟踪管道创建的状态 在 OpenSearch Ingestion 配置管道并准备好接收数据时，您可以跟踪管道的状态。 ### 控制台 最初创建管道后，在 OpenSearch Ingestion 准备采集数据时，它会经历多个阶段。要查看管道创建的各个阶段，请选择管道名称以查看其**管道设置**页面。在**状态**下，选择**查看详细信息**。 管道要经过以下几个阶段才可以摄取数据： + **验证** — 验证管道配置。此阶段完成后，所有验证均已成功。 + **创建环境** — 准备和预调配资源。此阶段完成后，即创建了新的管道环境。 + **部署管道** — 部署管道。此阶段完成后，管道已成功部署。 + **检查管道运行状况** — 检查管道的运行状况。此阶段完成后，所有运行状况检查均已通过。 + **启用流量** — 允许管道摄取数据。此阶段完成后，您可以开始将数据提取到管道。 ### CLI 使用[get-pipeline-change-progress](https://docs.aws.amazon.com/cli/latest/reference/osis/get-pipeline-change-progress.html)命令检查管道的状态。以下 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 摄取 API 要使用 OpenSearch Ingestion API 跟踪管道创建的状态，请调用该操作。[GetPipelineChangeProgress](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipelineChangeProgress.html)