本文档采用自动化机器翻译技术翻译。尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。若出现任何内容不一致情况，请以原始英文版本为准，且原始英文版本为权威文本。

注册现有集群

集群注册功能取代了导入集群的功能。

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 的基于角色的访问控制的更多信息，请参见官方 Google 文档。

弹性 Kubernetes 服务 (EKS)、Azure Kubernetes 服务 (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 和标准。

注册集群

单击 ☰ > 集群管理。
在*集群*页面，导入现有。
选择集群类型。
使用 成员角色 配置集群的用户授权。点击 添加成员 以添加可以访问集群的用户。使用角色下拉菜单为每个用户设置权限。
如果您在 Rancher 中导入一个通用 Kubernetes 集群，请执行以下步骤进行设置：
1. 在集群选项下点击代理环境变量以设置Rancher 集群代理的环境变量。环境变量可以使用键值对设置。如果 Rancher 代理需要使用代理与 Rancher 服务器通信，可以使用代理环境变量设置 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。
2. 启用项目网络隔离以确保集群支持 Kubernetes NetworkPolicy 资源。用户可以在高级选项下的项目网络隔离选项中进行选择。
3. 为导入的RKE2和K3s集群配置版本管理功能。
单击*创建*。
`cluster-admin`权限的先决条件已显示（请参见上面的*先决条件*），包括满足先决条件的示例命令。
将`kubectl`命令复制到剪贴板，并在 kubeconfig 配置指向您要导入的集群的节点上运行该命令。如果您不确定配置是否正确，请在运行Rancher中显示的命令之前运行`kubectl get nodes`进行验证。
如果您使用自签名证书，您将收到消息`certificate signed by unknown authority`。要绕过此验证，请将Rancher中显示的以`curl`开头的命令复制到剪贴板。然后在kubeconfig配置指向您要导入的集群的节点上运行该命令。
在您的节点上运行命令完成后，点击*完成*。

`NO_PROXY`环境变量不是标准化的，值的接受格式在不同应用之间可能有所不同。在为Rancher配置`NO_PROXY`变量时，值必须遵循Golang期望的格式。

具体来说，值应为仅包含IP地址、CIDR表示法、域名或特殊DNS标签（例如`*`）的逗号分隔字符串。有关预期值格式的完整描述，请参阅 上游Golang文档。

结果：

您的集群已注册并被分配为*待处理*状态。Rancher正在部署资源以管理您的集群。
在集群状态更新为*活动*后，您可以访问您的集群。
*活动*集群被分配了两个项目：Default（包含命名空间`default`）和`System`（包含命名空间`cattle-system`、traefik、kube-public`和`kube-system，如果存在的话）。

您不能重新注册当前在Rancher设置中处于活动状态的集群。

使用Terraform配置导入的EKS、AKS或GKE集群

在使用Terraform导入EKS、AKS或GKE集群时，您应*仅*定义Rancher所需的最小字段。这很重要，因为Rancher将用用户提供的任何配置覆盖集群配置中的内容。

当前集群与用户提供的配置之间即使有小的差异也可能导致意想不到的结果。

Rancher使用`eks_config_v2`导入EKS集群所需的最小配置字段如下：

cloud_credential_id
name
region
导入的（此字段对于导入的集群应始终设置为`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提供程序文档中找到其他云提供商的附加示例。

已注册集群的管理能力

Rancher 对注册集群的管理方式取决于集群的类型。

所有已注册集群的功能
已注册的 RKE2 和 K3s 集群的附加功能
已注册的 EKS、AKS 和 GKE 集群的附加功能

所有已注册集群的功能

注册集群后，集群所有者可以：

注册的SUSE® Rancher Prime: RKE2和SUSE® Rancher Prime: K3s集群的附加功能

K3s是一个轻量级、完全合规的Kubernetes发行版，适用于边缘安装。

RKE2是Rancher的下一代Kubernetes发行版，适用于数据中心和云安装。

当RKE2或K3s集群在Rancher中注册时，Rancher将识别它。 Rancher UI 将展示可用于所有已注册集群的功能，以及以下编辑和升级集群的选项：

启用或禁用版本管理
当启用版本管理时，升级Kubernetes版本
当启用版本管理时配置升级策略
查看集群的配置和用于启动每个节点的环境变量的只读版本。

已注册的 EKS、AKS 和 GKE 集群的附加功能

Rancher处理注册的EKS、AKS或GKE集群的方式与在Rancher中创建的集群类似。然而，当您通过 Rancher UI 删除已注册的集群时，Rancher 不会销毁它们。

当您在Rancher中创建EKS、AKS或GKE集群后再删除它时，Rancher会销毁该集群。当您通过 Rancher 删除已注册的集群时，Rancher 服务器 断开连接 与该集群的连接。该集群仍然处于活动状态，尽管它不再在 Rancher 中。您仍然可以以与注册之前相同的方式访问已注销的集群。

有关管理已注册集群的可用功能的更多信息，请参见按集群类型的集群管理能力。

为 SUSE® Rancher Prime: RKE2 和 SUSE® Rancher Prime: K3s 集群配置版本管理

当为导入的集群启用版本管理时，在 Rancher 之外升级它可能会导致意想不到的后果。

导入的 RKE2 和 K3s 集群的版本管理功能可以使用以下选项之一进行配置：

全局默认（默认）：继承全局 导入集群版本管理 设置的行为。
真：启用版本管理，允许用户通过 Rancher 控制集群的 Kubernetes 版本和升级策略。
假：禁用版本管理，使用户能够独立于 Rancher 管理集群的 Kubernetes 版本。

您可以通过修改 导入集群版本管理 设置来定义新创建的集群或设置为 "全局默认" 的现有集群的默认行为。

对全局 导入集群版本管理 设置的更改将在集群的下一个协调周期中生效。

如果为集群启用版本管理，Rancher 将向集群部署 system-upgrade-controller APP，以及相关的计划和其他所需的 Kubernetes 资源。如果禁用版本管理，Rancher 将从集群中去除这些组件。

配置SUSE® Rancher Prime: RKE2和SUSE® Rancher Prime: K3s集群升级

在升级之前备份集群是Kubernetes的最佳实践。在使用外部数据库升级高可用性K3s集群时，请按照关系数据库提供商的建议备份数据库。

并发性*是允许在升级期间不可用的最大节点数。如果不可用节点的数量大于*并发性,，则升级将失败。如果升级失败，您可能需要在升级成功之前修复或去除失败的节点。

*控制平面并发性:*一次升级的最大服务器节点数；也是最大不可用的服务器节点数
*工作器并发性:*同时升级的最大工作器节点数；也是最大不可用的工作器节点数

在RKE2和K3s文档中，控制平面节点被称为服务器节点。这些节点运行Kubernetes主控，维护集群的期望状态。默认情况下，这些控制平面节点可以调度工作负载。

在RKE2和K3s文档中，具备工作器角色的节点被称为代理节点。在集群中部署的任何工作负载或Pod默认可以调度到这些节点。

注册的SUSE® Rancher Prime: RKE2和SUSE® Rancher Prime: K3s集群的调试日志记录和故障排除

节点由在下游集群中运行的系统升级控制器进行升级。根据集群配置，Rancher部署两个计划来升级节点：一个用于控制平面节点，一个用于工作器节点。系统升级控制器遵循这些计划并升级节点。

要在系统升级控制器部署上启用调试日志记录，请编辑 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 升级最佳实践。

对SUSE® Rancher Prime: RKE2和SUSE® Rancher Prime: 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启用。点击*⋮ > 编辑配置*，然后在集群配置下点击*网络*选项卡。最后，点击启用按钮以 授权端点。一旦启用 ACE，您可以选择输入完全限定的域名 (FQDN) 和证书信息。

FQDN 字段是可选的，如果填写了该字段，它应指向下游集群。只有在下游集群前面有使用不受信任证书的负载均衡器时，才需要证书信息。如果您有有效的证书，则无需在 CA 证书 字段中添加任何内容。

注释注册集群

对于除 RKE2 和 K3s Kubernetes 集群之外的所有类型的注册 Kubernetes 集群，Rancher 对集群的配置或部署没有任何信息。

因此，当 Rancher 注册一个集群时，它假设默认情况下禁用了一些功能。Rancher 这样假设，是为了避免即使注册集群未启用相关功能，也向用户暴露 UI 选项。

然而，如果集群具有某种功能，该集群的用户可能仍希望在 Rancher UI 中为集群选择该功能。为此，用户需要手动向 Rancher 指示某些功能已为集群启用。

通过注释注册集群，可以向 Rancher 指示该集群在 Rancher 之外获得了额外的功能。

以下注释表示 Ingress 功能。请注意，非原始对象的值需要进行 JSON 编码，并转义引号。

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

这些功能可以为集群注释：

ingressCapabilities
loadBalancerCapabilities
nodePoolScalingSupported
nodePortRange
taintSupport

所有功能及其类型定义可以在 Rancher API 视图中查看，地址为 [Rancher Server URL]/v3/schemas/capabilities。

要注释注册集群，

单击 ☰ > 集群管理。
在集群页面，转到您想要注释的自定义集群并点击 ⋮ > 编辑配置。
展开 标签和注释 部分。
点击 添加注释。
向集群添加注释，格式为`capabilities/<capability>: <value>`，其中`value`是该注释将覆盖的集群能力。在这种情况下，Rancher 在您添加注释之前并不知道集群的任何能力。
单击保存。

*结果：*注释并不会赋予集群能力，但它确实向 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