建立 Amazon OpenSearch 擷取管道

管道是 Amazon OpenSearch Intetion 用來將資料從其來源 (資料來源) 移至接收器 (資料傳送位置) 的機制。在 OpenSearch 擷取中，接收器永遠是單一 Amazon OpenSearch 服務網域，而資料來源可能是 Amazon S3、Fluent Bit 或 OpenTelemetry 收集器等用戶端。

如需詳細資訊，請參閱 OpenSearch 文件中的管道。

必要條件和必要角色

若要建立 OpenSearch 擷取管線，您必須具備下列資源：

• OpenSearch 擷取將假設為寫入接收器的 IAM 角色。您將在管線組態中包含此角色 ARN。

• 作為接收器的 OpenSearch 服務網域或 OpenSearch 無伺服器集合。如果您要寫入網域，則該網域必須執行 OpenSearch 1.0 或更新版本，或是彈性搜尋 7.4 或更新版本。接收器必須具有為您的 IAM 管道角色授予適當許可的存取政策。

如需建立這些資源的指示，請參閱下列主題：

• 授予 Amazon OpenSearch 擷取管道對網域的存取權

• 授與 Amazon OpenSearch 擷取管道對集合的存取權

注意

如果您要寫入使用精細存取控制的網域，您需要完成額外的步驟。請參閱步驟 3：對應管線角色 (僅適用於使用精細存取控制的網域)。

必要許可

OpenSearch 擷取會使用下列 IAM 許可來建立管道：

• osis:CreatePipeline— 建立管線。

• osis:ValidatePipeline-檢查配管組態是否有效。

• iam:PassRole— 將管線角色傳遞至 OpenSearch 擷取，以便將資料寫入網域。此權限必須位於管線角色資源 (您為管線組態中的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 擷取的動作、資源和條件金鑰。

指定管線版本

設定管線時，您必須指定管線將執行的主要資料預留程式版本。若要指定版本，請在管線組態中包含version選項：

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

當您選擇建立時， OpenSearch 擷取會決定您指定之主要版本的最新可用次要版本，並以該版本佈建管道。例如，如果您指定version: "2"，且最新支援的資料預留程式版本為 2.1.1，則 OpenSearch 擷取會以 2.1.1 版佈建管道。我們不會公開顯示您的管道正在執行的次要版本。

若要在有新的主要資料預留程式版本可供使用時升級管線，請編輯管線組態並指定新版本。您無法將管道降級為較早的版本。

注意

OpenSearch 擷取不會立即支援新版本的資料預留器，一旦推出。新版本可公開使用到「 OpenSearch 擷取」支援時，會有一些延遲。此外， OpenSearch 擷取可能完全不支援某些主要或次要版本。如需完整清單，請參閱支援的資料預留程式版本。

每當您對啟動藍/綠部署的管道進行變更時， OpenSearch 擷取都可以將其升級到管線 YAML 檔案中目前設定的主要版本的最新次要版本。如需詳細資訊，請參閱管道更新的藍色/綠色部署。 OpenSearch 除非您在管道組態中明確更新version選項，否則擷取無法變更管道的主要版本。

指定擷取路徑

對於 oTel 追蹤和 oTel 指標等提取式來源， OpenSearch 擷取需要來源組態中的其他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 用服 OpenSearch 務主控台和. AWS CLI

主控台

建立管道

1. 登錄到 Amazon OpenSearch 服務控制台 https://console.aws.amazon.com/aos/home.

2. 在左側導覽窗格中選擇「管線」，然後選擇「建立管線」

3. 輸入管道的名稱。

4. (選擇性) 選擇「啟用持續緩衝區」。持續性緩衝區會將您的資料儲存在跨多個 AZ 的磁碟型緩衝區中。如需詳細資訊，請參閱持續性緩衝。如果您啟用持續性緩衝區，請選取 AWS Key Management Service 要加密緩衝區資料的金鑰。

5. 在擷取 OpenSearch 運算單元 (OCU) 中設定最小和最大管線容量。如需詳細資訊，請參閱 調整管線。

6. 在管線組態下，以 YAML 格式提供管線組態。單一配管組態檔案可以包含 1-10 個子配管。每個子管線都是單一來源、零個或多個處理器以及單一接收器的組合。對於 OpenSearch 擷取，接收器必須始終是 OpenSearch 服務網域。如需支援選項的清單，請參閱Amazon OpenSearch 擷取管道支援的外掛程式和選項。

   注意

   您必須在每個子配管中包括sts_role_arn和sigv4選項。管線會採用中定義的角色，sts_role_arn將要求簽署至網域。如需詳細資訊，請參閱 授予 Amazon OpenSearch 擷取管道對網域的存取權。

   下列範例設定檔使用 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 管線定義中指定多個接收器，它們都必須是相同的 OpenSearch 服務網域。 OpenSearch 擷取管線無法寫入多個不同的網域。

   您可以建立自己的管線組態，或選擇 [上傳檔案] 並匯入自我管理的資料預留程式管線的現有組態。或者，您可以使用組態藍圖。

7. 設定管線後，請選擇驗證管線以確認您的組態正確無誤。如果驗證失敗，請修正錯誤並重新執行驗證。

8. 在 [網路組態] 下，選擇 [VPC 存取] 或 [公用存取]。如果選擇 Public access (公開存取)，請跳到下一步驟。如果您選擇 VPC 存取，請進行下列設定：

   設定	描述
   VPC	選擇您想使用的虛擬私有雲端 (VPC) ID。VPC 和管線必須在相同 AWS 區域的位置。
   子網	選擇一或多個子網路。 OpenSearch 服務會在子網路中放置 VPC 端點和彈性網路介面。
   安全群組	選擇一或多個 VPC 安全性群組，以允許所需的應用程式在管線公開的連接埠 (80 或 443) 和通訊協定 (HTTP 或 HTTPS) 上連接到 OpenSearch 擷取管線。
   VPC 附件選項	如果您的來源是自我管理的端點，請將管線連接到 VPC。選擇其中一個提供的預設 CIDR 選項，或使用自訂 CIDR。

   如需詳細資訊，請參閱 為 Amazon OpenSearch 擷取管道設定 VPC 存取。

9. (選用) 在「標籤」下，將一或多個標籤 (金鑰/值配對) 新增至管線。如需詳細資訊，請參閱 標記亞馬遜OpenSearch導入管道。

10. (選擇性) 在日誌發佈選項下，開啟 Amazon CloudWatch 日誌的管道日誌發佈功能。建議您啟用記錄發佈，以便更輕鬆地疑難排解管線問題。如需詳細資訊，請參閱 監控管道日誌。

11. 選擇下一步。

12. 檢閱管線組態，然後選擇「建立」。

OpenSearch 擷取會執行非同步處理程序來建置管線。管道狀態為後Active，您就可以開始擷取資料。

AWS CLI

建立管線命令接受管線組態做為字串或 .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 擷取 API

若要使用 OpenSearch 擷取 API 建立 OpenSearch 擷取管線，請呼叫作業。CreatePipeline

成功建立管道後，您可以設定用戶端並開始將資料擷取到您的 OpenSearch 服務網域。如需詳細資訊，請參閱 使用 Amazon OpenSearch 擷取管道整合。

追蹤管道建立的狀態

您可以在 OpenSearch 擷取佈建管道時追蹤管道的狀態，並準備擷取資料。

主控台

在您初始建立管道之後，它會經過多個階段，因為 OpenSearch 擷取準備擷取資料。若要檢視管線建立的各個階段，請選擇管線名稱以查看其「管線設定」 頁面。在狀態下，選擇檢視詳細資料。

管道會先經過下列階段，才能擷取資料：

• 驗證 — 驗證管線組態。當此階段完成時，所有驗證都已成功。

• 建立環境 — 準備和佈建資源。當此階段完成時，就會建立新的管線環境。

• 部署管線 — 部署管線。當此階段完成時，管線已成功部署。

• 檢查管道健康狀況 — 檢查管道的健康狀況。當這個階段完成時，所有健康狀態檢查都已通過。

• 啟用流量 — 讓管道能夠擷取資料。完成此階段後，您就可以開始將資料擷取到管線中。

CLI

使用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 擷取 API

若要使用 OpenSearch 擷取 API 追蹤管道建立的狀態，請呼叫GetPipelineChangeProgress作業。

使用藍圖建立管道

您可以使用設定藍圖，而不是從頭開始建立管線定義，而是針對追蹤分析或 Apache 記錄等常見擷取案例預先設定的 YAML 範本。組態藍圖可協助您輕鬆佈建管線，而不必從頭開始編寫組態。

主控台

使用管線藍圖

1. 登錄到 Amazon OpenSearch 服務控制台 https://console.aws.amazon.com/aos/home.

2. 在左側導覽窗格中選擇「管線」，然後選擇「建立管線」

3. 選取藍圖。配管組態會根據您選取的使用案例填入子配管。

4. 檢閱已註解的文字，以引導您完成藍圖的設定。

   重要

   管線藍圖不是有效的。您需要進行一些修改，例如提供 AWS 區域 和角色 ARN 以用於驗證，否則管線驗證將會失敗。

CLI

若要使用取得所有可用藍圖的清單 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 擷取 API

若要使用 OpenSearch 擷取 API 取得管線藍圖的相關資訊，請使用ListPipelineBlueprints和GetPipelineBlueprint作業。