创建 Amazon OpenSearch Ingestion 管道 - 亚马逊 OpenSearch 服务
先决条件和所需 IAM 角色所需的 IAM 权限指定管道版本指定提取路径创建管道跟踪管道创建的状态

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

创建 Amazon OpenSearch Ingestion 管道

管道是 Amazon OpenSearch Ingestion 用来将数据从其来源（数据来源）移动到接收器（数据目的地）的一种机制。在 OpenSearch Ingestion 中，接收器将始终是单一的 Amazon OpenSearch Service 域，而您的数据来源可能是 Amazon S3、Fluent Bit 或 OpenTelemetry Collector 等客户端。

有关更多信息，请参阅 OpenSearch 文档中的管道。

先决条件和所需 IAM 角色

要创建 OpenSearch Ingestion 管道，您必须具有以下资源：

  • OpenSearch Ingestion 为了写入接收器而将代入的 IAM 角色。您将在您的管道配置中包含此角色 ARN。

  • OpenSearch Service 域或 OpenSearch 无服务器集合充当接收器。如果您正在写入域，则该域必须运行 OpenSearch 1.0 或更高版本或者 Elasticsearch 7.4 或更高版本。接收器必须具有向您的 IAM 管道角色授予相应权限的访问策略。

有关创建这些资源的说明，请参阅以下主题：

注意

如果您要写入使用精细访问控制的域，则需要完成一些额外的步骤。请参阅 步骤 3：映射管道角色（仅适用于使用精细访问控制的域）。

所需的 IAM 权限

OpenSearch Ingestion 使用以下 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 Ingestion 还包括一项名为 osis:Ingest 的权限，只有拥有该权限才能将签名的请求发送到使用 Signature 版本 4 的管道。有关更多信息，请参阅 创建摄取角色。

注意

此外，第一个在账户中创建管道的用户必须拥有 iam:CreateServiceLinkedRole 操作的权限。有关更多信息，请参阅管道角色资源。

有关每个权限的更多信息，请参阅《服务授权参考》中的 OpenSearch Ingestion 操作、资源和条件键。

指定管道版本

配置管道时，必须指定管道将运行的 Data Prepper 的主要版本。要指定版本，请在您的管道配置中包含以下 version 选项：

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

当您选择创建时，OpenSearch Ingestion 会确定您指定的主要版本的最新可用次要版本，并使用该版本预调配管道。例如，如果您指定 version: "2"，并且支持的 Data Prepper 最新版本为 2.1.1，则 OpenSearch Ingestion 会使用版本 2.1.1 来预调配您的管道。我们不会公开显示您的管道正在运行的次要版本。

要在 Data Prepper 新的主要版本可用时升级管道，请编辑管道配置并指定新版本。您无法将管道降级到较早版本。

注意

Data Prepper 新版本发布后，OpenSearch Ingestion 不会立即给予支持。新版本公开发布后，OpenSearch Ingestion 会在一段时间后才会给予支持。此外，OpenSearch Ingestion 可能会明确表示不支持某些主要版本或次要版本。有关完整列表，请参阅支持的 Data Prepper 版本。

每当您对启动蓝绿部署的管道进行更改时，OpenSearch Ingestion 都可以将其升级到管道 YAML 文件中当前配置的主要版本的最新次要版本。有关更多信息，请参阅 使用蓝绿部署进行管道更新。除非在管道配置中明确更新 version 选项，否则 OpenSearch Ingestion 无法更改管道的主要版本。

指定提取路径

对于基于拉取的来源，例如 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 Service 控制台和 AWS CLI 创建 OpenSearch Ingestion 管道。

要创建管道

  1. 登录到位于 https://console.aws.amazon.com/aos/home 的 Amazon OpenSearch Service 控制台。

  2. 在左侧导航窗格中选择管道，然后选择创建管道。

  3. 您可以选择空白管道，也可以选择配置蓝图。蓝图包含针对各种常见用例预先配置的 YAML 和 JSON 配置文件。有关更多信息，请参阅 使用蓝图创建管道。

    选择选择蓝图。

  4. 输入管道的名称。

  5. （可选）选择启用持久缓冲功能。持久缓冲功能将您的数据存储在跨多个可用区的、基于磁盘的缓冲区中。更多信息，请参阅持久缓冲功能。如果启用持久缓冲功能，请选择 AWS Key Management Service 密钥以加密缓冲区数据。

  6. 在 Ingestion OpenSearch 计算单位 (OCU) 中配置最小和最大管道容量。有关更多信息，请参阅 扩缩管道。

  7. 在管道配置下，以 YAML 格式提供您的管道配置。如果您使用的是蓝图，则配置已预先填充，但必须进行一些修改。

    单个管道配置文件可以包含 1-10 个子管道。每个子管道都由一个来源、零个或多个处理器以及一个接收器组成。对于 OpenSearch Ingestion，接收器必须始终是 OpenSearch Service 域。有关支持的选项列表，请参阅 Amazon OpenSearch Ingestion 管道支持的插件和选项。

    注意

    您必须在每个子管道中包含 sts_role_arn 选项。管道会代入 sts_role_arn 中定义的角色来签署对域的请求。有关更多信息，请参阅 向 Amazon OpenSearch Ingestion 管道授予访问域的权限。

    以下示例配置文件使用 HTTP 源和 Grok 插件，以处理非结构化日志数据并将其发送到 OpenSearch Service 域。子管道命名为 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"

    您可以构建自己的管道配置，也可以选择上传文件并导入自行管理的 Data Prepper 管道的现有配置。此外，您也可以使用配置蓝图。

  8. 配置管道后，选择验证管道以确认您的配置正确无误。如果验证失败，请修复错误并重新运行验证。

  9. 在网络配置下，选择 VPC 访问或公有访问。如果您选择 Public access (公有访问权限)，请跳至下一步。如果您选择 VPC 访问，请配置以下设置：

    设置 描述
    端点管理

    选择是要自己创建 VPC 端点，还是让 OpenSearch Ingestion 为您创建端点。端点管理默认会选择由 OpenSearch Ingestion 托管的端点。
    VPC

    选择要使用的虚拟私有云 (VPC) 的 ID。VPC 和管道必须位于同一 AWS 区域 中。
    子网

    选择一个或多个子网。OpenSearch Service 会将 VPC 端点和弹性网络界面放入子网中。
    安全组

    选择一个或多个 VPC 安全组，以允许您所需的应用程序在管道公开的端口（80 或 443）和协议（HTTP 或 HTTPs）上访问 OpenSearch Ingestion 管道。
    VPC 挂载选项

    如果您的源是自主管理型端点，请将您的管道挂载到某个 VPC。选择提供的默认 CIDR 选项之一，或使用自定义 CIDR。

    有关更多信息，请参阅 为 Amazon OpenSearch Ingestion 管道配置 VPC 访问。

  10. （可选）在标签下，将一个或多个标签（键值对）添加到您的管道。有关更多信息，请参阅 标记 Amazon OpenSearch Ingestion 管道。

  11. （可选）在日志发布选项下，启用向 Amazon CloudWatch Logs 发布管道日志。建议您启用日志发布，以便更轻松地解决管道问题。有关更多信息，请参阅 监控管道日志。

  12. 选择下一步。

  13. 检查您的管道配置，然后选择创建。

OpenSearch Ingestion 运行一个异步流程来构建管道。当管道状态为 Active 时，您可以开始将数据提取到管道。

create-pipeline 命令接受以字符串形式或在 .yaml 文件中的管道配置。如果您以字符串形式提供配置，则必须使用 \n 转义每一个新行。例如，"log-pipeline:\n source:\n http:\n processor:\n - grok:\n ...

以下示例命令采用以下配置创建管道：

  • 最少 4 个 Ingestion OCU，最多 10 个 Ingestion 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 Ingestion 运行一个异步流程来构建管道。当管道状态为 Active 时，您可以开始将数据提取到管道。要查看管道的状态，请使用 GetPipeline 命令。

要使用 OpenSearch Ingestion API 创建 OpenSearch Ingestion 管道，请调用 CreatePipeline 操作。

成功创建管道后，您可以配置客户端并开始将数据提取到 OpenSearch Service 域中。有关更多信息，请参阅 将 Amazon OpenSearch Ingestion 管道与其他服务和应用程序集成。

跟踪管道创建的状态

在 OpenSearch Ingestion 预调配管道并准备摄取数据时，您可以跟踪管道的状态。

最初创建管道后，OpenSearch Ingestion 要经历多个阶段才可以准备摄取数据。要查看管道创建的各个阶段，请选择管道名称以查看其管道设置页面。在状态下，选择查看详细信息。

管道要经过以下几个阶段才可以摄取数据：

  • 验证 — 验证管道配置。此阶段完成后，所有验证均已成功。

  • 创建环境 — 准备和预调配资源。此阶段完成后，即创建了新的管道环境。

  • 部署管道 — 部署管道。此阶段完成后，管道已成功部署。

  • 检查管道运行状况 — 检查管道的运行状况。此阶段完成后，所有运行状况检查均已通过。

  • 启用流量 — 允许管道摄取数据。此阶段完成后，您可以开始将数据提取到管道。

使用 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 Ingestion API 跟踪管道创建的状态，请调用 GetPipelineChangeProgress 操作。