跳至主要内容

K3s 叢集配置參考

本節涵蓋了 Rancher 中新建或現有 K3s Kubernetes 叢集可用的配置選項。

概述​

你可以透過以下兩種方式之一配置 Kubernetes 選項：

  • Rancher UI：使用 Rancher UI 選擇設定 Kubernetes 叢集時常用的自訂選項。
  • 叢集配置檔案：進階使用者可以建立 K3s 配置檔案，而不是使用 Rancher UI 來選擇叢集的 Kubernetes 選項。使用配置檔案可以讓你設定 K3s 安裝期間可用的任何選項。

在 Rancher UI 中編輯叢集​

Rancher UI 提供兩種編輯叢集的方式：

  1. 使用表單。
  2. 使用 YAML。

使用表單編輯叢集​

表單涵蓋了叢集最常需要的選項。

要編輯你的叢集，

  1. 點選 ☰ > Cluster Management。
  2. 前往你想要配置的叢集並點選 ⋮ > Edit Config。

在 YAML 中編輯叢集​

有關 YAML 中 K3s 叢集可配置選項的完整參考，請參閱 K3s 文件。

要使用 YAML 編輯你的叢集：

  1. 點選 ☰ > Cluster Management。
  2. 前往你想要配置的叢集並點選 ⋮ > Edit as YAML。
  3. 在 rkeConfig 指令下編輯 RKE 選項。

Rancher UI 中的配置選項​

機器池配置​

本小節涵蓋通用機器池配置。有關特定基礎設施提供者配置，請參閱以下內容：

池名稱​

機器池的名稱。

機器數量​

池中的機器數量。

角色​

為節點分配 etcd、控制平面和 worker 角色的選項。

進階​

自動替換​

節點在自動刪除和替換之前可以無法存取的時間量。

刪除前清空​

在刪除節點之前透過驅逐所有 pod 來啟用清空節點。

Kubernetes 節點標籤​

新增標籤到節點，以幫助組織和物件選擇。

有關標籤語法要求的詳細資訊，請參閱 Kubernetes 文件。

污點​

新增污點到節點，以防止 pod 被排程到節點或在節點上執行，除非 pod 具有匹配的容忍度。

叢集配置​

基礎​

Kubernetes 版本​

安裝在叢集節點上的 Kubernetes 版本。

有關升級或回滾 Kubernetes 的詳細資訊，請參閱本指南。

Pod 安全准入配置範本​

叢集的預設 pod 安全准入配置範本。

加密金鑰​

啟用或停用金鑰加密的選項。啟用後，金鑰將使用 AES-CBC 金鑰進行加密。如果停用，任何先前的金鑰將無法讀取，直到再次啟用加密。有關詳細資訊，請參閱 K3s 文件。

專案網路隔離​

如果你的網路提供者允許專案網路隔離，你可以選擇啟用或停用專案間通訊。

SELinux​

啟用或停用 SELinux 支援的選項。

CoreDNS​

預設情況下，CoreDNS 作為預設 DNS 提供者安裝。如果未安裝 CoreDNS，則必須自行安裝備用的 DNS 提供者。有關詳細資訊，請參閱 K3s 文件。

Klipper Service LB​

啟用或停用 Klipper 服務負載平衡器的選項。有關詳細資訊，請參閱 K3s 文件。

Traefik Ingress​

啟用或停用 Traefik HTTP 反向代理和負載平衡器的選項。有關更多詳細資訊和配置選項，請參閱 K3s 文件。

本機儲存​

啟用或停用節點上的本機儲存的選項。

Metrics Server​

啟用或停用 metrics server 的選項。如果啟用，請確保為入站 TCP 流量打開端口 10250。

Add-On 配置​

要在啟動時應用於叢集的其他 Kubernetes 清單，作為 Add-on 管理。有關詳細資訊，請參閱 K3s 文件。

Agent 環境變數​

為 K3s agents 設定環境變數的選項。環境變數可以使用鍵值對設定。有關更多詳細資訊，請參閱 K3 文件。

etcd​

自動快照​

啟用或停用定期 etcd 快照的選項。如果啟用，使用者可以選擇配置快照的頻率。有關詳細資訊，請參閱 K3s 文件。

指標​

選擇是將 etcd 指標公開到公共還是僅在叢集內公開的選項。

網路​

叢集 CIDR​

用於 pod IP 的 IPv4/IPv6 網路 CIDR（預設值：10.42.0.0/16）。

範例值：

  • 僅 IPv4：10.42.0.0/16
  • 僅 IPv6：2001:cafe:42::/56
  • 雙堆疊：10.42.0.0/16,2001:cafe:42::/56

有關與雙堆疊或僅 IPv6 網路相關的其他要求和限制，請參閱以下資源：

警告

你必須在首次建立叢集時配置 Service CIDR。在叢集啟動後，你無法在現有叢集上啟用 Service CIDR。

Service CIDR​

用於服務 IP 的 IPv4/IPv6 網路 CIDR（預設值：10.43.0.0/16）。

範例值：

  • 僅 IPv4：10.43.0.0/16
  • 僅 IPv6：2001:cafe:43::/112
  • 雙堆疊：10.43.0.0/16,2001:cafe:43::/112

有關與雙堆疊或僅 IPv6 網路相關的其他要求和限制，請參閱以下資源：

警告

你必須在首次建立叢集時配置 Service CIDR。在叢集啟動後，你無法在現有叢集上啟用 Service CIDR。

叢集 DNS​

coredns 服務的 IPv4 叢集 IP。應該在你的 service-cidr 範圍內（預設值：10.43.0.10）。

叢集域​

選擇叢集的域。預設為 cluster.local。

NodePort Service 端口範圍​

更改可用於 NodePort 服務的端口範圍的選項。預設值為 30000-32767。

截斷主機名稱​

將主機名稱截斷為 15 個字元或更少的選項。你只能在叢集的初始建立期間設定此欄位。在叢集建立後，你無法啟用或停用 15 個字元限制。

此設定僅影響機器佈建的叢集。由於自訂叢集在其自己的節點建立過程中設定主機名稱，該過程發生在 Rancher 之外，因此此欄位不會限制自訂叢集的主機名稱長度。

在叢集中截斷主機名稱可以提高與基於 Windows 的系統的相容性。雖然 Kubernetes 允許主機名稱長度最多為 63 個字元，但使用 NetBIOS 的系統將主機名稱限制為 15 個字元或更少。

TLS 替代名稱​

在伺服器 TLS 憑證上新增主機名稱或 IPv4/IPv6 位址作為主體替代名稱。

已授權叢集端點​

已授權叢集端點可用於直接存取 Kubernetes API 伺服器，而無需透過 Rancher 進行通訊。

有關已授權叢集端點如何工作以及為何使用它的更多詳細資訊，請參閱架構章節。

我們建議將負載平衡器與已授權叢集端點一起使用。有關詳細資訊，請參閱建議架構章節。

堆疊偏好​

為叢集選擇網路堆疊。此選項影響：

  • 用於元件（如 Calico、etcd、kube-apiserver、kube-scheduler、kube-controller-manager 和 kubelet）的健康和就緒探測的位址。
  • 已授權叢集端點的 authentication-token-webhook-config-file 中的伺服器 URL。
  • 快照還原期間 etcd 的 advertise-client-urls 設定。

選項為 ipv4、ipv6、dual：

  • 當設定為 ipv4 時，叢集使用 127.0.0.1
  • 當設定為 ipv6 時，叢集使用 [::1]
  • 當設定為 dual 時，叢集使用 localhost

堆疊偏好必須與叢集的網路配置匹配：

  • 對於僅 IPv4 叢集，設定為 ipv4
  • 對於僅 IPv6 叢集，設定為 ipv6
  • 對於雙堆疊叢集，設定為 dual
警告

確保環回位址配置正確對於成功的叢集佈建至關重要。 有關更多資訊，請參閱節點要求頁面。

登錄檔​

選擇要從中拉取 Rancher 映像的映像倉庫。有關更多詳細資訊和配置選項，請參閱 K3s 文件。

升級策略​

控制平面並發​

選擇可以同時升級多少個節點。可以是固定數量或百分比。

Worker 並發​

選擇可以同時升級多少個節點。可以是固定數量或百分比。

清空節點（控制平面）​

在升級之前從節點中移除所有 pod 的選項。

清空節點（Worker 節點）​

在升級之前從節點中移除所有 pod 的選項。

進階​

為不同節點設定 kubelet 選項的選項。有關可用選項，請參閱 Kubernetes 文件。

叢集配置檔案參考​

在 YAML 中編輯叢集允許你設定已經在 Rancher UI 中的配置選項中列出的配置，以及設定 Rancher 特定的參數。

叢集配置檔案範例片段
apiVersion: provisioning.cattle.io/v1
kind: Cluster
spec:
  cloudCredentialSecretName: cattle-global-data:cc-fllv6
  clusterAgentDeploymentCustomization: {}
  fleetAgentDeploymentCustomization: {}
  kubernetesVersion: v1.26.7+k3s1
  localClusterAuthEndpoint: {}
  rkeConfig:
    additionalManifest: ""
    chartValues: {}
    etcd:
      snapshotRetention: 5
      snapshotScheduleCron: 0 */5 * * *
    machineGlobalConfig:
      disable-apiserver: false
      disable-cloud-controller: false
      disable-controller-manager: false
      disable-etcd: false
      disable-kube-proxy: false
      disable-network-policy: false
      disable-scheduler: false
      etcd-expose-metrics: false
      kube-apiserver-arg:
        - audit-policy-file=/etc/rancher/k3s/user-audit-policy.yaml
        - audit-log-path=/etc/rancher/k3s/user-audit.logs
      profile: null
      secrets-encryption: false
    machinePools:
    - controlPlaneRole: true
      etcdRole: true
      machineConfigRef:
        kind: Amazonec2Config
        name: nc-test-pool1-pwl5h
      name: pool1
      quantity: 1
      unhealthyNodeTimeout: 0s
      workerRole: true
    machineSelectorConfig:
      - config:
          docker: false
          protect-kernel-defaults: false
          selinux: false
    machineSelectorFiles:
      - fileSources:
          - configMap:
              name: ''
            secret:
              name: audit-policy
              items:
                - key: audit-policy
                  path: /etc/rancher/k3s/user-audit-policy.yaml
        machineLabelSelector:
          matchLabels:
            rke.cattle.io/control-plane-role: 'true'
    registries: {}
    upgradeStrategy:
      controlPlaneConcurrency: '1'
      controlPlaneDrainOptions:
        deleteEmptyDirData: true
        disableEviction: false
        enabled: false
        force: false
        gracePeriod: -1
        ignoreDaemonSets: true
        ignoreErrors: false
        postDrainHooks: null
        preDrainHooks: null
        skipWaitForDeleteTimeoutSeconds: 0
        timeout: 120
      workerConcurrency: '1'
      workerDrainOptions:
        deleteEmptyDirData: true
        disableEviction: false
        enabled: false
        force: false
        gracePeriod: -1
        ignoreDaemonSets: true
        ignoreErrors: false
        postDrainHooks: null
        preDrainHooks: null
        skipWaitForDeleteTimeoutSeconds: 0
        timeout: 120

additionalManifest​

指定要傳遞到控制平面節點的其他清單。

值為字串，將放置在目標節點上的路徑 /var/lib/rancher/k3s/server/manifests/rancher/addons.yaml。

範例：

additionalManifest: |-
  apiVersion: v1
  kind: Namespace
  metadata:
    name: name-xxxx
備註

如果你想要自訂系統圖表，你應該使用如下所述的 chartValues 欄位。

替代方案，例如使用 HelmChartConfig 透過 additionalManifest 自訂系統圖表，可能會因為對同一圖表有多個 HelmChartConfig 而導致意外行為。

chartValues​

指定 K3s 安裝的系統圖表的值。

有關 K3s 如何管理打包元件的更多資訊，請參閱 K3s 文件。

範例：

chartValues:
    chart-name:
        key: value

machineGlobalConfig​

指定 K3s 配置。在此處所做的任何配置更改都將應用於每個節點。獨立版本的 k3s 中可用的配置選項可以在此處應用。

範例：

machineGlobalConfig:
    etcd-arg:
        - key1=value1
        - key2=value2

為了更容易事先將檔案放在節點上，Rancher 期望配置中包含以下值，而 K3s 期望將值輸入為檔案路徑：

  • private-registry
  • flannel-conf

Rancher 將檔案傳遞到目標節點中的路徑 /var/lib/rancher/k3s/etc/config-files/<option>，並在 K3s 伺服器中設定適當的選項。

範例：

apiVersion: provisioning.cattle.io/v1
kind: Cluster
spec:
  rkeConfig:
    machineGlobalConfig:
      private-registry: |
        mirrors:
          docker.io:
            endpoint:
              - "http://mycustomreg.com:5000"
        configs:
          "mycustomreg:5000":
            auth:
              username: xxxxxx # this is the registry username
              password: xxxxxx # this is the registry password

machineSelectorConfig​

machineSelectorConfig 與 machineGlobalConfig 相同，只是可以使用配置指定標籤選擇器。配置將僅應用於與提供的標籤選擇器匹配的節點。

允許多個 config 條目，每個條目指定自己的 machineLabelSelector。使用者可以指定 matchExpressions、matchLabels，兩者都指定，或兩者都不指定。省略此欄位的 machineLabelSelector 部分與將配置放在 machineGlobalConfig 部分中具有相同的效果。

範例：

machineSelectorConfig
  - config:
      config-key: config-value
    machineLabelSelector:
      matchExpressions:
        - key: example-key
          operator: string # Valid operators are In, NotIn, Exists and DoesNotExist.
          values:
            - example-value1
            - example-value2
      matchLabels:
        key1: value1
        key2: value2

machineSelectorFiles​

備註

此功能在 Rancher v2.7.2 及更高版本中可用。

將檔案傳遞到節點，以便在啟動 K3s 伺服器或代理程序之前可以將檔案放置到位。 檔案的內容從 secret 或 configmap 中擷取。目標節點由 machineLabelSelector 過濾。

範例 ：

machineSelectorFiles:
  - fileSources:
      - secret:
          items:
            - key: example-key
              path: path-to-put-the-file-on-nodes
              permissions: 644 (optional)
              hash: base64-encoded-hash-of-the-content (optional)
          name: example-secret-name
    machineLabelSelector:
      matchExpressions:
        - key: example-key
          operator: string # Valid operators are In, NotIn, Exists and DoesNotExist.
          values:
            - example-value1
            - example-value2
      matchLabels:
        key1: value1
        key2: value2
  - fileSources:
      - configMap:
          items:
            - key: example-key
              path: path-to-put-the-file-on-nodes
              permissions: 644 (optional)
              hash: base64-encoded-hash-of-the-content (optional)
          name: example-configmap-name
    machineLabelSelector:
      matchExpressions:
        - key: example-key
          operator: string # Valid operators are In, NotIn, Exists and DoesNotExist.
          values:
            - example-value1
            - example-value2
      matchLabels:
        key1: value1
        key2: value2

secret 或 configmap 必須滿足以下要求：

  1. 它必須在 Cluster 物件所在的 fleet-default 命名空間中。
  2. 它必須具有註解 rke.cattle.io/object-authorized-for-clusters: cluster-name1,cluster-name2，這允許目標叢集使用它。
提示

Rancher Dashboard 提供了一個易於使用的表單來建立 secret 或 configmap。

範例：

apiVersion: v1
data:
  audit-policy: >-
    IyBMb2cgYWxsIHJlcXVlc3RzIGF0IHRoZSBNZXRhZGF0YSBsZXZlbC4KYXBpVmVyc2lvbjogYXVkaXQuazhzLmlvL3YxCmtpbmQ6IFBvbGljeQpydWxlczoKLSBsZXZlbDogTWV0YWRhdGE=
kind: Secret
metadata:
  annotations:
    rke.cattle.io/object-authorized-for-clusters: cluster1
  name: name1
  namespace: fleet-default