opensearch

您可以使用 opensearch 接收器插件将数据发送到 OpenSearch 集群、旧版 Elasticsearch 集群或 Amazon OpenSearch Service 域。

该插件支持 OpenSearch 1.0 及更高版本以及 Elasticsearch 7.3 及更高版本。

用法

要配置 opensearch 接收器，请在管道配置中指定 opensearch 选项。

pipeline:
  ...
  sink:
    opensearch:
      hosts: ["https://:9200"]
      cert: path/to/cert
      username: YOUR_USERNAME
      password: YOUR_PASSWORD
      index_type: trace-analytics-raw
      dlq_file: /your/local/dlq-file
      max_retries: 20
      bulk_size: 4

要配置 Amazon OpenSearch Service 接收器，请将域端点指定为 hosts 选项，如以下示例所示。

pipeline:
  ...
  sink:
    opensearch:
      hosts: ["https://your-amazon-opensearch-service-endpoint"]
      aws_sigv4: true
      cert: path/to/cert
      insecure: false
      index_type: trace-analytics-service-map
      bulk_size: 4

配置选项

下表描述了您可以为 opensearch 接收器配置的选项。

aws

actions

以下选项可以在 actions 选项中使用。

无服务器选项

以下选项可在 serverless_options 对象中使用。

配置 max_retries

您可以在管道配置中包含 max_retries 选项，以控制源尝试以指数退避写入接收器的次数。如果您不包含此选项，管道将无限期地重试。

如果您指定了 max_retries 并且管道配置了死信队列 (DLQ)，则管道将持续尝试写入接收器，直到达到最大重试次数，此时它将开始向 DLQ 发送失败数据。

如果您不指定 max_retries，则只有被接收器拒绝的数据才会写入 DLQ。管道会继续尝试将所有其他数据写入接收器。

OpenSearch 集群安全

为了使用 opensearch 接收器插件将数据发送到 OpenSearch 集群，您必须在管道配置中指定您的用户名和密码。以下 pipelines.yaml 示例文件演示了如何指定管理员安全凭证。

sink:
  - opensearch:
      username: "admin"
      password: "admin"
      ...

或者，除了管理员凭证，您还可以指定映射到具有以下部分中列出的最低权限的用户的凭证。

集群权限

• cluster_all
• indices:admin/template/get
• indices:admin/template/put

索引权限

• 索引：otel-v1*；索引权限：indices_all
• 索引：.opendistro-ism-config；索引权限：indices_all
• 索引：*；索引权限：manage_aliases

有关如何将用户映射到角色的说明，请参阅 将用户映射到角色。

Amazon OpenSearch Service 域安全

opensearch 接收器插件可以将数据发送到使用 IAM 进行安全的 Amazon OpenSearch Service 域。该插件使用默认凭证链。使用 AWS 命令行界面 (AWS CLI) 运行 aws configure 来设置您的凭证。

确保您配置的凭证具有所需的 IAM 权限。以下域访问策略演示了最低所需的权限。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AccountId>:user/data-prepper-user"
      },
      "Action": "es:ESHttp*",
      "Resource": [
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/otel-v1*",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_template/otel-v1*",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_plugins/_ism/policies/raw-span-policy",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_alias/otel-v1*",
        "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_alias/_bulk"
      ]
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AccountId>:user/data-prepper-user"
      },
      "Action": "es:ESHttpGet",
      "Resource": "arn:aws:es:us-east-1:<AccountId>:domain/<domain-name>/_cluster/settings"
    }
  ]
}

有关如何配置域访问策略的说明，请参阅 Amazon OpenSearch Service 文档中的基于资源的策略。

细粒度访问控制

如果您的 OpenSearch Service 域使用精细访问控制，则 opensearch 接收器插件需要一些额外的配置。

将 IAM ARN 作为主用户

如果您将 IAM Amazon 资源名称 (ARN) 用作主用户，请在接收器配置中包含 aws_sigv4 选项。

...
sink:
    opensearch:
      hosts: ["https://your-fgac-amazon-opensearch-service-endpoint"]
      aws_sigv4: true

使用 AWS CLI 运行 aws configure 以使用主 IAM 用户凭证。如果您不想使用主用户，可以使用 aws_sts_role_arn 选项指定不同的 IAM 角色。然后，插件将使用此角色签署发送到域接收器的请求。您指定的 ARN 必须包含在域访问策略中。

内部用户数据库中的主用户

如果您的域使用内部用户数据库中的主用户，请指定主用户名和密码以及 aws_sigv4 选项。

sink:
    opensearch:
      hosts: ["https://your-fgac-amazon-opensearch-service-endpoint"]
      username: "master-username"
      password: "master-password"

有关更多信息，请参阅 Amazon OpenSearch Service 文档中的推荐配置。

注意：您可以创建具有 all_access 权限的新 IAM 角色或内部用户数据库用户，并将其替代主用户。

OpenSearch Serverless 集合安全

opensearch 接收器插件可以将数据发送到 Amazon OpenSearch Serverless 集合。

OpenSearch Serverless 集合接收器有以下限制：

• 您无法写入使用虚拟私有云 (VPC) 访问的集合。该集合必须可从公共网络访问。
• OTel 跟踪组处理器目前不支持集合接收器。

创建管道角色

首先，创建一个 IAM 角色，管道将承担此角色以写入集合。该角色必须具有以下最低权限：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "aoss:BatchGetCollection"
            ],
            "Resource": "*"
        }
    ]
}

该角色必须具有以下信任关系，这允许管道承担它：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AccountId>:root"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

创建集合

接下来，使用以下设置创建集合：

• OpenSearch 端点和 OpenSearch Dashboards 的公共网络访问。

• 以下数据访问策略，它授予管道角色所需的权限：

  [
   {
      "Rules":[
         {
            "Resource":[
               "index/collection-name/*"
            ],
            "Permission":[
               "aoss:CreateIndex",
               "aoss:UpdateIndex",
               "aoss:DescribeIndex",
               "aoss:WriteDocument"
            ],
            "ResourceType":"index"
         }
      ],
      "Principal":[
         "arn:aws:iam::<AccountId>:role/PipelineRole"
      ],
      "Description":"Pipeline role access"
   }
  ]
  

  重要：请务必将 Principal 元素中的 ARN 替换为您在前面步骤中创建的管道角色的 ARN。

  有关如何创建集合的说明，请参阅 Amazon OpenSearch Service 文档中的创建集合。

创建管道

在您的 pipelines.yaml 文件中，将 OpenSearch Serverless 集合端点指定为 hosts 选项。此外，您必须将 serverless 选项设置为 true。在 sts_role_arn 选项中指定管道角色。

log-pipeline:
  source:
    http:
  processor:
    - date:
        from_time_received: true
        destination: "@timestamp"
  sink:
    - opensearch:
        hosts: [ "https://<serverless-public-collection-endpoint>" ]
        index: "my-serverless-index"
        aws:
          serverless: true
          sts_role_arn: "arn:aws:iam::<AccountId>:role/PipelineRole"
          region: "us-east-1"

包含 template_content 和 actions 的示例

以下示例管道包含 template_content 和条件 actions 列表。

log-pipeline:
  source:
    http:
  processor:
    - date:
        from_time_received: true
        destination: "@timestamp"
  sink:
    - opensearch:
        hosts: [ "https://<serverless-public-collection-endpoint>" ]
        index: "my-serverless-index"
        template_type: index-template
        template_content: >
          {
            "template" : {
              "mappings" : {
                "properties" : {
                  "Data" : {
                    "type" : "binary"
                  },
                  "EncodedColors" : {
                    "type" : "binary"
                  },
                  "Type" : {
                    "type" : "keyword"
                  },
                  "LargeDouble" : {
                    "type" : "double"
                  }          
                }
              }
            }
          }
        # index is the default case  
        actions:
         - type: "delete"
           when: '/operation == "delete"'
         - type: "update"
           when: '/operation == "update"'
         - type: "index"
        aws:
          sts_role_arn: "arn:aws:iam::<AccountId>:role/PipelineRole"
          region: "us-east-1"