AliyunPipelineConfig CRD的YAML配置參數參考-Log Service-阿里雲

當您使用ClusterAliyunPipelineConfig建立日誌採集配置時，需要通過一個結構化的YAML檔案定義採集規則。本文介紹該YAML檔案的整體結構及各欄位的含義。

重要

CRD建立的採集配置內容請以CR為準，禁止在控制台修改，若在控制台進行修改，改動內容會被CR覆蓋，可能導致資料格式異常或丟失。

工作原理

建立CR資源：使用者通過 kubectl 提交ClusterAliyunPipelineConfig YAML 檔案，定義採集規則。
控制器監聽變化：loongcollector-operator 持續監聽叢集中CR資源的變更。
同步配置：當檢測到 CR 變化時，operator 將其轉換為具體配置，並提交到指定Project。
採集器拉取最新配置：loongcollector-ds定時向Log Service發送心跳擷取配置更新，拉取最新的採集配置並熱載入。
開始採集與上報：loongcollector-ds 根據最新配置採集日誌，並通過配置的存取點發送到 SLS。

基礎欄位

定義API版本與資源類型，所有配置都必須以此開頭：

apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig

結構樣本

apiVersion: telemetry.alibabacloud.com/v1alpha1 # 使用預設值，無需修改。
kind: ClusterAliyunPipelineConfig               # 使用預設值，無需修改。
metadata:
  name: test-config                             # 設定資源名，在當前Kubernetes叢集內唯一。
spec:
  project:                                      # 設定目標Project名稱。
    name: k8s-your-project                      
  config:                                       # 設定Logtail採集配置。
    inputs:                                     # 設定Logtail採集配置裡的輸入外掛程式
      ...
    flushers:                                   # 設定Logtail採集配置裡的輸出外掛程式
      ...

核心參數說明

metadata.name

採集配置名稱，必填，在Project內唯一，建立後不可修改。

命名規則：

只能包含：小寫字母、數字、-和_。
必須以小寫字母或數字開頭和結尾。
長度限制：2~128字元。

樣本：

metadata:
  name: nginx-access-log

spec.projecct

目標Project資訊。

說明

project欄位在CR建立後不允許更改，如需切換project請建立新的CR。

參數	資料類型	是否必填	說明
name	string	是	目標 Project 的名稱，若不存在會自動建立。
description	string	否	Project 的描述（僅在建立時生效）。
endpoint	string	否	Project所在地區的服務入口，預設值為叢集所在的地區。該參數僅控制採集配置的建立地區，不控制採集器資料投遞目標。如需跨地區採集，請配置config_server_address和data_server_list。
uid	string	否	目標Project所屬的阿里雲主帳號的uid。預設值為當前叢集所屬的主帳號uid。該參數僅控制採集配置建立到哪個帳號下。如需跨帳號採集日誌，請同步配置`alibaba-log-controller` 組件的環境變數： `ALICLOUD_LOG_ACCOUNT_INFOS={"<uid>":{"accessKeyID":"<your_access_key_id>","accessKeySecret":"<your_access_key_secret>"}}`。

spec.config

採集配置主體，定義具體的輸入、處理、輸出外掛程式。

子欄位	類型	是否必填	說明
`sample`	string	否	日誌範例，支援多條日誌，總長度不超過1500位元組。
`global`	object	否	全域配置。
`inputs`	object列表	是	輸入外掛程式列表，目前只允許配置 1 個輸入外掛程式。
`processors`	object列表	否	處理外掛程式列表：原生外掛程式擴充外掛程式
`flushers`	object列表	是	輸出外掛程式列表，目前只允許存在 1 個 `flusher_sls`外掛程式。

spec.LogStores

可選配置，用於聲明需要建立的LogStore，其作用如下：

僅在建立時生效：所有參數（除 name 外）都只在 LogStore 首次建立時有效。如果 LogStore 已存在，這些配置將被忽略，不會影響已有 LogStore 的屬性。
不決定資料發送目標：此列表不控制日誌發送到哪個 LogStore。真正的發送目標由 config.flushers 中的輸出外掛程式（如 flusher_sls）決定。
可選配置：如果目標 LogStore 已經存在，可以不用在此處定義。
僅支援增刪，不支援修改：可以向列表中添加新的 LogStore 或刪除某項，但無法通過更新此配置來修改已建立的 LogStore 屬性（如 TTL、Shard 數量等）。如需修改，請通過控制台或 API 操作。

參數	資料類型	是否必填	說明
name	string	是	需要建立的LogStore名稱。
queryMode	string	否	LogStore規格對比。預設值為`standard`，可選值： `query`：查詢型LogStore。 `standard`：標準型LogStore。
ttl	int	否	資料保留天數（1~3650）預設30，3650表示永久。
hotTtl	int	否	熱資料存放區時間（以天為單位）。預設0，需要小於ttl且大於等於 7。
infrequentAccessTTL	int	否	目標LogStore的低頻儲存時間（以天為單位）。預設值為0，需要hotTtl存在、小於ttl且大於等於30，如果hotTtl+infrequentAccessTTL不等於ttl，還需要`ttl-(hotTtl+infrequentAccessTTL)>=60`。該參數需要`loongcollector-operator`組件版本號碼大於等於1.0.6有效。
shardCount	int	否	Shard數量。預設值為2，取值範圍為1~100。
maxSplitShard	int	否	最大自動分裂Shard數量。預設值為64，取值範圍為1~256。
autoSplit	bool	否	是否開啟自動分裂Shard。預設值為true。
telemetryType	string	否	可觀測資料類型。預設值為None，可選值： `None`：日誌資料。 `Metrics`：時序資料。
appendMeta	bool	否	是否記錄外網IP地址和日誌接收時間。預設值為true。 `true`：開啟記錄外網 IP 和日誌接收時間功能，開啟後Log Service自動把日誌來源裝置的公網 IP 位址和日誌到達服務端的時間添加到日誌的 Tag 欄位中。 `false`：不開啟記錄外網 IP 和日誌接收時間功能。
enableTracking	bool	否	是否啟用WebTracking功能。預設值為false。
encryptConf	object	否	加密配置資料結構，包含參數`enable`、 `encrypt_type`、 `user_cmk_info`。預設值為空白。
meteringMode	string	否	計費模式。更多資訊，請參見管理LogStore。預設值為空白，可選值： `ChargeByFunction`：按功能計費 `ChargeByDataIngest`：按寫入量計費。說明如果LogStore的queryMode為query，只支援按功能計費。如果帳號未開通寫入量計費，無法配置為ChargeByDataIngest。
index	object	否	指定索引（僅限LogStore建立時生效），格式參考通用資料格式 index。該參數需要loongcollector-operator組件版本號碼大於等於1.0.6有效。

spec.machineGroups

指定哪些機器組可以應用此採集配置。

預設行為：安裝LoongCollector時，系統會自動建立的名為k8s-group-${clusterId}的機器組。若未顯式設定 machineGroups，將預設關聯該機器組。
同步機制：loongcollector-operator 會確保採集配置所關聯的機器組嚴格等於 machineGroups 中定義的列表。任何不在該列表中的機器組都會被自動解除關聯。
自動建立支援：如果指定的機器組不存在，系統會自動建立同名的標識型機器組，並將其與當前採集配置綁定。

參數	資料類型	是否必填	說明
name	string	否	要關聯的機器組名稱。

spec.enableUpgradeOverride

可選，是否允許覆蓋舊配置。用於解決新舊版採集配置之間的衝突問題，預設為false。

true：loongcollector-operator會對已有的AliyunLogConfig定義的採集配置進行覆蓋升級。
false：採集配置存在衝突，AliyunPipelineConfig應用失敗。

使用情境：當叢集中存在AliyunLogConfig定義的採集配置、且與當前的AliyunPipelineConfig指向同一個採集配置時，就會發生衝突。

同一個採集配置的定義：

Project 相同
- AliyunLogConfig：使用叢集預設 Project 或 spec.project
- AliyunPipelineConfig：使用 spec.project.name
採集配置名稱相同
- AliyunLogConfig：spec.logtailConfig.configName
- AliyunPipelineConfig：metadata.name

覆蓋升級過程：

新配置生效
ClusterAliyunPipelineConfig 被應用，更新採集配置。
舊配置清理
如果更新成功，控制器會自動刪除叢集中對應的 AliyunLogConfig 資源。
完成遷移
完成從舊方式到新方式的平滑過渡。