註冊現有叢集

叢集註冊功能取代了匯入叢集的功能。

Rancher 對已註冊叢集的管理控制取決於叢集的類型。有關詳細資訊,請參閱已註冊叢集的管理功能。

前置需求

Kubernetes 節點角色

已註冊的 RKE Kubernetes 叢集必須具有所有三個節點角色 - etcd、controlplane 和 worker。僅具有 controlplane 元件的叢集無法在 Rancher 中註冊。

有關 RKE 節點角色的更多資訊,請參閱最佳實踐。

權限

要在 Rancher 中註冊叢集,您必須在該叢集中具有 cluster-admin 權限。如果沒有,請透過執行以下命令向您的使用者授予這些權限:

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin \
  --user [USER_ACCOUNT]

由於預設情況下 Google Kubernetes Engine (GKE) 不授予 cluster-admin 角色,因此在註冊 GKE 叢集之前,您必須在 GKE 叢集上執行這些命令。要了解有關 GKE 基於角色的存取控制的更多資訊,請參閱官方 Google 文件。

Elastic Kubernetes Service (EKS)、Azure Kubernetes Service (AKS) 和 Google Kubernetes Engine (GKE)

要成功從 Rancher 匯入或佈建 EKS、AKS 和 GKE 叢集,該叢集必須至少有一個受管理的節點群組。

只有在啟用本地帳戶的情況下才能匯入 AKS 叢集。如果叢集設定為使用 Microsoft Entra ID 進行身份驗證,Rancher 將無法匯入該叢集並報告錯誤。

EKS Anywhere 叢集可以使用 API 位址和憑證匯入/註冊到 Rancher 中,就像任何下游叢集一樣。EKS Anywhere 叢集被視為匯入的叢集,並且不具有來自 Rancher 的完整生命週期支援。

不支援 GKE Autopilot 叢集。有關 GKE 模式之間差異的更多資訊,請參閱比較 GKE Autopilot 和 Standard。

註冊叢集

點擊 ☰ > Cluster Management。
在 Clusters 頁面上,點擊 Import Existing。
選擇叢集的類型。
使用 Member Roles 設定叢集的使用者授權。點擊 Add Member 新增可以存取叢集的使用者。使用 Role 下拉式選單為每個使用者設定權限。
如果您要在 Rancher 中匯入通用 Kubernetes 叢集,請執行以下設定步驟:
1. 在 Cluster Options 下點擊 Agent Environment Variables 以設定 rancher cluster agent 的環境變數。環境變數可以使用鍵值對設定。如果 rancher agent 需要使用代理與 Rancher 伺服器通訊,可以使用 agent 環境變數設定 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 環境變數。
2. 啟用專案網路隔離以確保叢集支援 Kubernetes NetworkPolicy 資源。使用者可以在 Advanced Options 下拉式選單下選擇 Project Network Isolation 選項來執行此操作。
3. 為匯入的 RKE2 和 K3s 叢集設定版本管理功能。
點擊 Create。
顯示 cluster-admin 權限的前置需求(請參閱上面的 前置需求),包括滿足前置需求的範例命令。
將 kubectl 命令複製到剪貼簿,並在設定了 kubeconfig 指向您要匯入的叢集的節點上執行它。如果您不確定它是否設定正確,請在執行 Rancher 中顯示的命令之前執行 kubectl get nodes 進行驗證。
如果您使用自簽憑證,您將收到 certificate signed by unknown authority 訊息。要解決此驗證問題,請將 Rancher 中顯示的以 curl 開頭的命令複製到剪貼簿。然後在設定了 kubeconfig 指向您要匯入的叢集的節點上執行該命令。
完成在節點上執行命令後,點擊 Done。

important

NO_PROXY 環境變數沒有標準化,值的接受格式可能因應用程式而異。在 Rancher 中設定 NO_PROXY 變數時,值必須遵守 Golang 預期的格式。

具體來說,該值應該是一個逗號分隔的字串,僅包含 IP 位址、CIDR 表示法、網域名稱或特殊 DNS 標籤(例如 *)。有關預期值格式的完整描述,請參閱 上游 Golang 文件。

結果:

您的叢集已註冊並被分配 Pending 狀態。Rancher 正在部署資源以管理您的叢集。
您可以在叢集狀態更新為 Active 後存取您的叢集。
Active 叢集被分配兩個專案:Default(包含命名空間 default)和 System(包含命名空間 cattle-system、ingress-nginx、kube-public 和 kube-system(如果存在))。

備註

您無法重新註冊目前在 Rancher 設定中處於 active 狀態的叢集。

使用 Terraform 設定匯入的 EKS、AKS 或 GKE 叢集

使用 Terraform 匯入 EKS、AKS 或 GKE 叢集時,您應該僅定義 Rancher 需要的最小欄位。這很重要,因為 Rancher 會用使用者提供的任何設定覆寫叢集設定中的內容。

警告

即使當前叢集和使用者提供的設定之間存在微小差異,也可能產生意外結果。

Rancher 使用 Terraform 和 eks_config_v2 匯入 EKS 叢集所需的最小設定欄位如下:

cloud_credential_id
name
region
imported(對於匯入的叢集,此欄位應始終設定為 true)

匯入的 EKS 叢集的範例 YAML 設定:

resource "rancher2_cluster" "my-eks-to-import" {
  name        = "my-eks-to-import"
  description = "Terraform EKS Cluster"
  eks_config_v2 {
    cloud_credential_id = rancher2_cloud_credential.aws.id
    name                = var.aws_eks_name
    region              = var.aws_region
    imported            = true
  }
}

您可以在 Rancher2 Terraform Provider 文件中找到其他雲端提供者的其他範例。

已註冊叢集的管理功能

Rancher 對已註冊叢集的管理控制取決於叢集的類型。

所有已註冊叢集的功能
已註冊 RKE2 和 K3s 叢集的其他功能
已註冊 EKS、AKS 和 GKE 叢集的其他功能

所有已註冊叢集的功能

註冊叢集後,叢集擁有者可以:

透過基於角色的存取控制管理叢集存取
啟用監控、告警和通知器
啟用日誌記錄
啟用 Istio
管理專案和工作負載

已註冊 RKE2 和 K3s 叢集的其他功能

K3s 是一個輕量級、完全相容的 Kubernetes 發行版,適用於邊緣安裝。

RKE2 是 Rancher 的下一代 Kubernetes 發行版,適用於資料中心和雲端安裝。

當在 Rancher 中註冊 RKE2 或 K3s 叢集時,Rancher 會識別它。 Rancher UI 將公開所有已註冊叢集可用的功能,以及以下用於編輯和升級叢集的選項:

啟用或停用版本管理
當啟用版本管理時升級 Kubernetes 版本
當啟用版本管理時設定升級策略
檢視用於啟動每個節點的叢集設定參數和環境變數的唯讀版本

已註冊 EKS、AKS 和 GKE 叢集的其他功能

Rancher 處理已註冊的 EKS、AKS 或 GKE 叢集的方式與在 Rancher 中建立的叢集類似。但是,當您透過 Rancher UI 刪除已註冊的叢集時,Rancher 不會銷毀它們。

當您在 Rancher 中建立 EKS、AKS 或 GKE 叢集,然後將其刪除時,Rancher 會銷毀該叢集。當您透過 Rancher 刪除已註冊的叢集時,Rancher 伺服器會從該叢集_斷開連線_。該叢集仍然保持活躍,儘管它不再在 Rancher 中。您仍然可以像在註冊之前一樣存取已取消註冊的叢集。

有關可用於管理已註冊叢集的功能的更多資訊,請參閱依叢集類型的叢集管理功能。

為 RKE2 和 K3s 叢集設定版本管理

危險

當為匯入的叢集啟用版本管理時,在 Rancher 外部升級它可能會導致意外後果。

可以使用以下選項之一為匯入的 RKE2 和 K3s 叢集設定版本管理功能:

Global default(預設):從全域 imported-cluster-version-management 設定繼承行為。
True: 啟用版本管理,允許使用者透過 Rancher 控制叢集的 Kubernetes 版本和升級策略。
False: 停用版本管理,使使用者能夠在 Rancher 外部獨立管理叢集的 Kubernetes 版本。

您可以透過修改 imported-cluster-version-management 設定來定義新建立的叢集或設定為「Global default」的現有叢集的預設行為。

對全域 imported-cluster-version-management 設定的更改在叢集的下一個調解週期期間生效。

備註

如果為叢集啟用了版本管理,Rancher 將部署 system-upgrade-controller 應用程式以及相關的 Plans 和其他所需的 Kubernetes 資源到叢集中。如果停用版本管理,Rancher 將從叢集中移除這些元件。

設定 RKE2 和 K3s 叢集升級

提示

在升級之前備份叢集是 Kubernetes 的最佳實踐。當升級具有外部資料庫的高可用性 K3s 叢集時,請以關聯式資料庫提供者建議的方式備份資料庫。

concurrency 是在升級期間允許不可用的最大節點數。如果不可用節點的數量大於 concurrency,升級將失敗。如果升級失敗,您可能需要修復或移除失敗的節點,然後升級才能成功。

Controlplane concurrency: 一次升級的最大伺服器節點數;也是最大不可用伺服器節點數
Worker concurrency: 同時升級的最大 worker 節點數;也是最大不可用 worker 節點數

在 RKE2 和 K3s 文件中,controlplane 節點稱為伺服器節點。這些節點執行 Kubernetes master,它維護叢集的所需狀態。預設情況下,這些 controlplane 節點具有將工作負載排程到它們的能力。

同樣在 RKE2 和 K3s 文件中,具有 worker 角色的節點稱為 agent 節點。預設情況下,在叢集中部署的任何工作負載或 pod 都可以排程到這些節點。

已註冊 RKE2 和 K3s 叢集的除錯日誌記錄和疑難排解

節點由在下游叢集中執行的系統升級控制器升級。根據叢集設定,Rancher 部署兩個計畫來升級節點:一個用於 controlplane 節點,一個用於 worker。系統升級控制器遵循計畫並升級節點。

要在系統升級控制器部署上啟用除錯日誌記錄,請編輯 configmap 將除錯環境變數設定為 true。然後重新啟動 system-upgrade-controller pod。

可以透過執行以下命令檢視 system-upgrade-controller 建立的日誌:

kubectl logs -n cattle-system system-upgrade-controller

可以使用以下命令檢視計畫的當前狀態:

kubectl get plans -A -o yaml

提示

如果叢集在升級時卡住,請重新啟動 system-upgrade-controller。

為了防止升級時出現問題,應遵循 Kubernetes 升級最佳實踐。

對 RKE2 和 K3s 叢集的授權叢集端點支援

Rancher 支援已註冊的 RKE2 和 K3s 叢集的授權叢集端點(ACE)。此支援包括您將在下游叢集上執行的手動步驟以啟用 ACE。有關授權叢集端點的其他資訊,請點擊這裡。

注意事項:

這些步驟只需要在下游叢集的控制平面節點上執行。您必須單獨設定每個控制平面節點。
以下步驟適用於在 v2.6.x 中註冊的 RKE2 和 K3s 叢集,以及從先前版本的 Rancher 註冊(或匯入)並升級到 v2.6.x 的叢集。
這些步驟將更改下游 RKE2 和 K3s 叢集的設定並部署 kube-api-authn-webhook。如果 ACE 的未來實作需要更新 kube-api-authn-webhook,那麼這也必須手動完成。有關此 webhook 的更多資訊,請點擊這裡。

在每個下游叢集的控制平面上執行的手動步驟以啟用 ACE:

在 /var/lib/rancher/\{rke2,k3s\}/kube-api-authn-webhook.yaml 建立一個檔案,包含以下內容:

apiVersion: v1
kind: Config
clusters:
- name: Default
  cluster:
    insecure-skip-tls-verify: true
    server: http://127.0.0.1:6440/v1/authenticate
users:
- name: Default
  user:
    insecure-skip-tls-verify: true
current-context: webhook
contexts:
- name: webhook
  context:
    user: Default
    cluster: Default

將以下內容新增到設定檔(如果不存在則建立一個);請注意,預設位置是 /etc/rancher/\{rke2,k3s\}/config.yaml:
```
kube-apiserver-arg:
    - authentication-token-webhook-config-file=/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml
```

執行以下命令:

sudo systemctl stop {rke2,k3s}-server
sudo systemctl start {rke2,k3s}-server

最後,您必須返回 Rancher UI 並在那裡編輯匯入的叢集以完成 ACE 啟用。點擊 ⋮ > Edit Config,然後點擊 Cluster Configuration 下的 Networking 分頁。最後,點擊 Authorized Endpoint 的 Enabled 按鈕。啟用 ACE 後,您可以選擇輸入完全限定網域名稱(FQDN)和憑證資訊。

備註

FQDN 欄位是選用的,如果輸入了一個,它應該指向下游叢集。只有在下游叢集前面有使用不受信任憑證的負載平衡器時才需要憑證資訊。如果您有有效的憑證,則無需向 CA Certificates 欄位新增任何內容。

為已註冊叢集新增註解

對於除 RKE2 和 K3s Kubernetes 叢集之外的所有類型的已註冊 Kubernetes 叢集,Rancher 沒有關於叢集如何佈建或設定的任何資訊。

因此,當 Rancher 註冊叢集時,它假設預設情況下停用了幾個功能。Rancher 這樣假設是為了避免向使用者公開 UI 選項,即使已註冊叢集中未啟用這些功能。

但是,如果叢集具有某種功能,例如使用 pod 安全策略的能力,該叢集的使用者可能仍然希望在 Rancher UI 中為叢集選擇 pod 安全策略。為了做到這一點,使用者需要手動向 Rancher 指示已為叢集啟用 pod 安全策略。

透過為已註冊的叢集新增註解,可以向 Rancher 指示叢集在 Rancher 外部被賦予了 Ingress 功能或其他功能。以下註解指示 Ingress 功能。請注意,非原始物件的值需要進行 JSON 編碼,並轉義引號。

"capabilities.cattle.io/ingressCapabilities": "[
  {
    "customDefaultBackend":true,
    "ingressProvider":"asdf"
  }
]"

可以為叢集註解這些功能:

ingressCapabilities
loadBalancerCapabilities
nodePoolScalingSupported
nodePortRange
taintSupport

所有功能及其類型定義可以在 Rancher API 檢視中檢視,位於 [Rancher Server URL]/v3/schemas/capabilities。

要為已註冊的叢集新增註解:

點擊 ☰ > Cluster Management。
在 Clusters 頁面上,前往您要新增註解的自訂叢集並點擊 ⋮ > Edit Config。
展開 Labels & Annotations 部分。
點擊 Add Annotation。
使用格式 capabilities/<capability>: <value> 向叢集新增註解,其中 value 是將被註解覆寫的叢集功能。在這種情況下,Rancher 不知道叢集的任何功能,直到您新增註解。
點擊 Save。

結果: 註解不會賦予叢集功能,但它確實向 Rancher 指示叢集具有這些功能。

疑難排解

本節列出了匯入叢集時可能發生的一些最常見的錯誤,並提供了排除故障的步驟。

AKS

如果您的叢集中停用了本地帳戶,可能會發生以下錯誤。

Error: Getting static credential is not allowed because this cluster is set to disable local accounts.

要解決此問題,請在再次嘗試匯入叢集之前啟用本地帳戶。

az aks update --resource-group <resource-group> --name <cluster-name> --enable-local-accounts

前置需求​

Kubernetes 節點角色​

權限​

Elastic Kubernetes Service (EKS)、Azure Kubernetes Service (AKS) 和 Google Kubernetes Engine (GKE)​

註冊叢集​

使用 Terraform 設定匯入的 EKS、AKS 或 GKE 叢集​

已註冊叢集的管理功能​

所有已註冊叢集的功能​

已註冊 RKE2 和 K3s 叢集的其他功能​

已註冊 EKS、AKS 和 GKE 叢集的其他功能​

為 RKE2 和 K3s 叢集設定版本管理​

設定 RKE2 和 K3s 叢集升級​

已註冊 RKE2 和 K3s 叢集的除錯日誌記錄和疑難排解​

對 RKE2 和 K3s 叢集的授權叢集端點支援​

在每個下游叢集的控制平面上執行的手動步驟以啟用 ACE:​

為已註冊叢集新增註解​

疑難排解​

AKS​