本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
建立 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管線角色適當權限的存取原則。
如需建立這些資源的指示,請參閱下列主題:
注意
如果您要寫入使用精細存取控制的網域,您需要完成額外的步驟。請參閱步驟 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追蹤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
建立管道
-
在https://console.aws.amazon.com/aos/家
中登錄 Amazon OpenSearch 服務控制台。 -
在左側導覽窗格中選擇「管線」,然後選擇「建立管線」
-
輸入管道的名稱。
-
(選擇性) 選擇啟用持續性緩衝區。持續性緩衝區會將您的資料儲存在多個磁碟型緩衝區中。AZs如需詳細資訊,請參閱持續性緩衝。如果您啟用持續性緩衝區,請選取 AWS Key Management Service 要加密緩衝區資料的金鑰。
-
在擷取 OpenSearch 運算單元 (OCUs) 中設定最小和最大管線容量。如需詳細資訊,請參閱 調整管線。
-
在「管線組態」下,以YAML格式提供管線組態。單一配管組態檔案可以包含 1-10 個子配管。每個子管線都是單一來源、零個或多個處理器以及單一接收器的組合。對於 OpenSearch 擷取,接收器必須始終是 OpenSearch 服務網域。如需支援選項的清單,請參閱Amazon OpenSearch 擷取管道支援的外掛程式和選項。
注意
您必須在每個子配管中包括
sts_role_arn
和sigv4
選項。管線會採用中定義的角色,sts_role_arn
將要求簽署至網域。如需詳細資訊,請參閱 授予 Amazon OpenSearch 擷取管道對網域的存取權。下列範例設定檔使用HTTP來源和 Grok 外掛程式來處理非結構化記錄資料,並將其傳送至 OpenSearch 服務網域。子管線命名
log-pipeline
為。例子 YAML
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
"例子 JSON
{ "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 Service 網域。 OpenSearch 擷取管線無法寫入多個不同的網域。
您可以建立自己的管線組態,或選擇 [上傳檔案] 並匯入自我管理的資料預留程式管線的現有組態。或者,您可以使用組態藍圖。
-
設定管線後,選擇驗證管線以確認您的組態正確無誤。如果驗證失敗,請修正錯誤並重新執行驗證。
-
在 [網路組態] 下,選擇 [VPC存取] 或 [公用存取]。如果選擇 Public access (公開存取),請跳到下一步驟。如果您選擇VPC存取權,請進行下列設定:
設定 描述 端點管理 選擇是要自行建立VPC端點,還是要讓 OpenSearch 擷取為您建立端點。端點管理預設為由 OpenSearch 擷取管理的端點。
VPC 選擇您要使用的虛擬私有雲 (VPC) ID。VPC和管線必須是相同的 AWS 區域。
子網 選擇一或多個子網路。 OpenSearch 服務會在子網路中放置VPC端點和彈性網路介面。
安全群組 選擇一個或多個VPC安全群組,讓所需的應用程式在管線公開的連接埠 (80 或 443) 和通訊協定 (HTTP或HTTPs) 上連接埠進 OpenSearch 入擷取管線。
VPC貼附選項 如果您的來源是自我管理的端點,請將您的管道附加到VPC. 選擇提供的預設CIDR選項之一,或使用自訂選項CIDR。
如需詳細資訊,請參閱 為 Amazon OpenSearch 擷取管道設定 VPC 存取。
-
(選擇性) 在標籤下,將一或多個標籤 (鍵值配對) 新增至管線。如需詳細資訊,請參閱 標記亞馬遜OpenSearch導入管道。
-
(選擇性) 在日誌發佈選項下,開啟 Amazon CloudWatch 日誌的管道日誌發佈功能。建議您啟用記錄發佈,以便更輕鬆地疑難排解管線問題。如需詳細資訊,請參閱 監控管道日誌。
-
選擇下一步。
-
檢閱管線組態,然後選擇「建立」。
OpenSearch 擷取會執行非同步處理程序來建置管線。管道狀態為後Active
,您就可以開始擷取資料。
建立管線命令接受管線組態做為字串或 .yaml 檔案。如果您將配置作為字符串提供,則每個新行都必須使用轉義\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
"
OpenSearch 擷取會執行非同步處理程序來建置管線。管道狀態為後Active
,您就可以開始擷取資料。若要檢查管線的狀態,請使用GetPipeline指令。
若要使用 OpenSearch 擷取建立 OpenSearch 擷取管線API,請呼叫作業。CreatePipeline
成功建立管道後,您可以設定用戶端並開始將資料擷取到您的 OpenSearch 服務網域。如需詳細資訊,請參閱 使用 Amazon OpenSearch 擷取管道整合。
追蹤管道建立的狀態
您可以在 OpenSearch 擷取佈建管道時追蹤管道的狀態,並準備擷取資料。
在您初始建立管道之後,它會經過多個階段,因為 OpenSearch 擷取準備擷取資料。若要檢視管線建立的各個階段,請選擇管線名稱以查看其「管線設定」 頁面。在狀態下,選擇檢視詳細資料。
管道會先經過下列階段,才能擷取資料:
-
驗證 — 驗證管線組態。當此階段完成時,所有驗證都已成功。
-
建立環境 — 準備和佈建資源。完成此階段後,便會建立新的管線環境。
-
部署管線 — 部署管線。當此階段完成時,管線已成功部署。
-
檢查管道健康狀況 — 檢查管道的健康狀況。當此階段完成時,所有健康狀態檢查都已通過。
-
啟用流量 — 讓管道擷取資料。完成此階段後,您就可以開始將資料擷取到管線中。
使用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,請呼叫GetPipelineChangeProgress作業。
使用藍圖建立管道
您可以使用組態藍圖,而不是從頭開始建立管線定義,而是針對追蹤分析或 Apache 記錄等常見擷取案例的預先設定YAML範本。組態藍圖可協助您輕鬆佈建管線,而不必從頭開始編寫組態。
使用管線藍圖
-
在https://console.aws.amazon.com/aos/家
中登錄 Amazon OpenSearch 服務控制台。 -
在左側導覽窗格中選擇「管線」,然後選擇「建立管線」
-
選取藍圖。配管組態會根據您選取的使用案例填入子配管。
-
檢閱註解文字,以引導您完成藍圖的設定。
重要
管線藍圖不是有效的。您需要進行一些修改,例如提供 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 擷取取得管線藍圖的相關資訊API,請使用ListPipelineBlueprints和GetPipelineBlueprint作業。