注册下游集群

概述

注册集群有两种特定的样式。这些样式将被称为*Fleet agent 发起*和*Fleet Manager 发起*注册。通常情况下，人们会选择 Fleet agent 发起注册，但在某些特定用例中，Fleet Manager 发起的工作流程更为合适。

Fleet agent 发起注册

Fleet agent 发起是指下游集群安装一个带有集群注册词元和可选客户端ID的 Fleet agent 的模式。然后，集群 Fleet agent 将向SUSE® Rancher Prime Continuous DeliveryFleet Manager 发出 API 请求，并启动注册过程。通过这个过程，Fleet Manager 将不会向下游集群发出外部 API 请求，因此不需要直接的网络访问。

在 Rancher 中不常用。Rancher 不需要向下游集群发出外部 API 请求，因为它使用隧道提供连接。

Fleet Manager 发起注册

Fleet Manager 发起注册是一个过程，在该过程中，您将现有的 Kubernetes 集群注册到SUSE® Rancher Prime Continuous DeliveryFleet Manager，SUSE® Rancher Prime Continuous DeliveryFleet Manager 将向下游集群发出 API 调用以部署 Fleet agent。这种样式可能会增加额外的网络访问要求，因为 Fleet Manager 必须能够与下游集群 API 服务器进行通信以完成注册过程。集群注册后，Fleet Manager 无需再联系下游集群 API。如果您希望通过 GitOps 管理所有 Kubernetes 集群的创建，使用类似 cluster-api 或 Rancher 的工具，这种样式更为兼容。

功能 Fleet agent 发起注册 Fleet Manager 发起注册（Rancher 模式）

功能	Fleet agent 发起注册	Fleet Manager 发起注册（Rancher 模式）
注册发起者	下游集群通过部署 Fleet agent 来启动注册过程。	Fleet Manager（上游集群）启动注册过程。
前提条件：上游管理员操作	需要手动管理员操作以在上游创建`ClusterRegistrationToken`资源。此词元是 Fleet agent 授权所必需的。	需要在 Fleet Manager 中创建一个`Cluster`资源，该资源引用下游集群的 Kubernetes 包含有效 kubeconfig 的 Secret。
主要机制	通过 Helm 在下游集群上安装 Fleet agent，使用手动生成的集群注册词元。	Fleet Controller 使用提供的kubeconfig向下游集群的 API 服务器发出 API 调用并部署 Fleet agent。
注册网络方向	通信流从受管集群到Fleet Controller（上游）。这是用于注册凭据的拉取机制。	Fleet Manager 发起与下游集群 API 服务器的连接（推送）以部署 Fleet agent。
网络要求（Fleet Manager）	Fleet Manager 不需要直接的入站网络访问下游集群 API。集群可以在私有网络中运行/在NAT后面。	Fleet Manager 必须能够直接与下游集群 API 服务器通信，在注册阶段。
网络要求（Fleet agent）	下游集群必须能够向 Fleet Manager 发起出站 HTTPS 调用。	下游集群必须能够向 Fleet Manager 发起出站 HTTPS 调用（部署后，用于通信和数据同步）。
数据同步（拉取）	Fleet agent 从 Fleet Controller 拉取配置包和 Fleet agent 更新（属于两阶段拉取模型的一部分）。	Fleet agent 从 Fleet Controller 拉取配置包和 Fleet agent 更新。
Fleet agent 管理（推送/重新部署）	上游控制器通常缺乏对 Fleet agent 部署进行主动管理操作（推送）所需的直接网络访问/凭据。	初始部署机制授予 Fleet Manager 明确的访问权限。该基础设施可用于管理操作（例如，使用 kubeconfig 触发部署）。
Fleet agent 重新部署控制字段	`redeployAgentGeneration` 字段（在 `ClusterSpec` 上）未被上游控制器使用来触发重新部署，因为 Fleet Manager 缺乏直接操作下游 Fleet agent 部署所需的 API 访问权限。	`redeployAgentGeneration` 字段在 `ClusterSpec` 上可以递增以强制重新部署 Fleet agent。
Fleet agent 采用后注册	在使用词元进行初始注册后，Fleet agent 通过 `manageagent` 控制器创建的包被纳入标准管理生命周期。
Rancher 上下文	在通过 Rancher 仪表板注册集群时，这种方法不常用。	在通过 Rancher 仪表板添加集群时，这种方法被使用（通常通过 Rancher 代理下游 kubeconfig 上游）。
注册后 token 状态	Fleet agent 在成功后会忘记注册词元；必须生成新的词元以进行重新注册。	不适用；注册词元/kubeconfig 管理由 Fleet Manager 内部处理。

注册发起者

下游集群通过部署 Fleet agent 来启动注册过程。

Fleet Manager（上游集群）启动注册过程。

前提条件：上游管理员操作

需要手动管理员操作以在上游创建`ClusterRegistrationToken`资源。此词元是 Fleet agent 授权所必需的。

需要在 Fleet Manager 中创建一个`Cluster`资源，该资源引用下游集群的 Kubernetes 包含有效 kubeconfig 的 Secret。

主要机制

通过 Helm 在下游集群上安装 Fleet agent，使用手动生成的集群注册词元。

Fleet Controller 使用提供的kubeconfig向下游集群的 API 服务器发出 API 调用并部署 Fleet agent。

注册网络方向

通信流从受管集群到Fleet Controller（上游）。这是用于注册凭据的拉取机制。

Fleet Manager 发起与下游集群 API 服务器的连接（推送）以部署 Fleet agent。

网络要求（Fleet Manager）

Fleet Manager 不需要直接的入站网络访问下游集群 API。集群可以在私有网络中运行/在NAT后面。

Fleet Manager 必须能够直接与下游集群 API 服务器通信，在注册阶段。

网络要求（Fleet agent）

下游集群必须能够向 Fleet Manager 发起出站 HTTPS 调用。

下游集群必须能够向 Fleet Manager 发起出站 HTTPS 调用（部署后，用于通信和数据同步）。

数据同步（拉取）

Fleet agent 从 Fleet Controller 拉取配置包和 Fleet agent 更新（属于两阶段拉取模型的一部分）。

Fleet agent 从 Fleet Controller 拉取配置包和 Fleet agent 更新。

Fleet agent 管理（推送/重新部署）

上游控制器通常缺乏对 Fleet agent 部署进行主动管理操作（推送）所需的直接网络访问/凭据。

初始部署机制授予 Fleet Manager 明确的访问权限。该基础设施可用于管理操作（例如，使用 kubeconfig 触发部署）。

Fleet agent 重新部署控制字段

redeployAgentGeneration 字段（在 ClusterSpec 上）未被上游控制器使用来触发重新部署，因为 Fleet Manager 缺乏直接操作下游 Fleet agent 部署所需的 API 访问权限。

redeployAgentGeneration 字段在 ClusterSpec 上可以递增以强制重新部署 Fleet agent。

Fleet agent 采用后注册

在使用词元进行初始注册后，Fleet agent 通过 manageagent 控制器创建的包被纳入标准管理生命周期。

Rancher 上下文

在通过 Rancher 仪表板注册集群时，这种方法不常用。

在通过 Rancher 仪表板添加集群时，这种方法被使用（通常通过 Rancher 代理下游 kubeconfig 上游）。

注册后 token 状态

Fleet agent 在成功后会忘记注册词元；必须生成新的词元以进行重新注册。

不适用；注册词元/kubeconfig 管理由 Fleet Manager 内部处理。

Fleet agent 发起

通过安装 Fleet agent 并使用 集群注册词元 和可选的 client ID 或 集群标签 来注册下游集群。

上游的集群资源没有 kubecConfigSecret 字段，因为 Fleet Manager 不需要与下游集群 API 服务器通信。然而，会为 Fleet agent 创建一个包，Fleet agent 将会从该包中自动更新自身。该捆绑包使用不同的命名规则，因此下游集群最终会有两个 Helm 图表。

不需要为多集群配置 Fleet Manager，因为我们通过 Helm 安装的下游 Fleet agent 将直接连接到上游集群的 Kubernetes API。

Fleet agent 发起的注册通常不与 Rancher 一起使用。

集群注册词元和客户端 ID

集群注册词元 是一种凭证，将授权下游的 Fleet agent 启动注册过程。此项是必需的。集群注册词元以 values.yaml 文件的形式体现，该文件将传递给 helm install 处理。或者，可以通过 --set token="$token" 将词元直接传递给 Helm 安装命令。

注册 Fleet agent 有两种方式。您可以动态创建此 Fleet agent 的集群，在这种情况下，您可能希望在注册时指定 集群标签。或者，您可以让 Fleet agent 注册到 SUSE® Rancher Prime Continuous Delivery 中预定义的集群，在这种情况下，您需要一个 客户端 ID。前一种方法通常是最简单的。

为新集群安装 Fleet agent

SUSE® Rancher Prime Continuous Delivery Fleet agent 作为 Helm 图表安装。以下是如何确定和设置其参数的说明。

首先，按照集群注册词元说明获取 values.yaml，该文件包含用于对 SUSE® Rancher Prime Continuous Delivery 集群进行身份验证的注册词元。

其次，您可以选择性地定义将在注册时分配给新创建集群的标签。注册完成后，Fleet agent 无法更改集群的标签。要添加集群标签，请在下面的 Helm 命令中添加 --set-string labels.KEY=VALUE。要添加标签 foo=bar 和 bar=baz，您需要在命令行中添加 --set-string labels.foo=bar --set-string labels.bar=baz。

# Leave blank if you do not want any labels
CLUSTER_LABELS="--set-string labels.example=true --set-string labels.env=dev"

第三，设置变量，使用 SUSE® Rancher Prime Continuous Delivery 集群的 API 服务器 URL 和 CA，以便下游集群用于连接。

API_SERVER_URL=https://<API_URL>:6443
API_SERVER_CA_DATA=...

如果API服务器未在https端口（443）上监听，则`API_SERVER_URL`应包括端口，例如`https://<API_URL>:6443`。URL可以在`.kube/config`文件中找到。

在`API_SERVER_CA_DATA`中的值可以从包含有效数据以连接到上游集群的`.kube/config`文件中获得（在`certificate-authority-data`键下）。或者，它可以从上游集群内部获得，通过查找默认的ServiceAccount密钥名称（通常以`default-token-`为前缀，在默认命名空间中），在`ca.crt`键下。

使用正确的命名空间和发布名称：对于 Fleet agent 图表，命名空间必须是`cattle-fleet-system`，发布名称是`fleet-agent`。

Kubectl上下文

确保您正在安装到正确的集群： Helm 将使用 `${HOME}/.kube/config` 中的默认上下文来部署 Fleet agent。使用`--kubeconfig`和`--kube-context`来更改Helm安装的集群。

在Rancher中的SUSE® Rancher Prime Continuous Delivery

Rancher 为 SUSE® Rancher Prime Continuous Delivery 提供了单独的 Helm 图表，并使用不同的储存库。

添加Fleet的Helm储存库。

helm repo add fleet https://rancher.github.io/fleet-helm-charts/

最后，使用Helm安装代理。

安装
验证

helm -n cattle-fleet-system install --create-namespace --wait \
    --set clientID="$CLUSTER_CLIENT_ID" \
    --values values.yaml \
    fleet-agent fleet/fleet-agent

您可以通过运行以下命令检查 Fleet pod 的状态：

# Ensure kubectl is pointing to the right cluster kubectl -n cattle-fleet-system logs -l app=fleet-agent kubectl -n cattle-fleet-system get pods -l app=fleet-agent

代理现在应该已部署。

此外，您应该在SUSE® Rancher Prime Continuous Delivery管理器中看到一个新注册的集群。以下是检查新集群是否在`clusters` 名称空间中注册的示例。请确保您的`${HOME}/.kube/config`指向Fleet Manager以运行此命令。

kubectl -n clusters get clusters.fleet.cattle.io

NAME                   BUNDLES-READY   NODES-READY   SAMPLE-NODE             LAST-SEEN              STATUS
cluster-ab13e54400f1   1/1             1/1           k3d-cluster2-server-0   2020-08-31T19:23:10Z

为预定义集群安装代理

客户端 ID 用于在 SUSE® Rancher Prime Continuous Delivery 管理器中预定义具有现有标签和目标存储库的集群。客户端 ID 不是必需的，只是一种管理集群的方法。 客户端 ID 是一个唯一字符串，用于标识集群。该字符串由用户生成，对SUSE® Rancher Prime Continuous Delivery 管理器和代理来说是不可解读的。假设它足够唯一。出于安全原因，应该无法轻易猜测此值，因为一个集群可能会冒充另一个集群。客户端 ID 是可选的，如果未指定，将使用`kube-system` 名称空间资源的 UID 字段作为客户端 ID。在注册时，如果在 SUSE® Rancher Prime Continuous Delivery 管理器的 Cluster 资源中找到客户端 ID，将会将代理与该 Cluster 关联。如果未找到具有该客户端 ID 的 Cluster 资源，将创建一个具有特定客户端 ID 的新 Cluster 资源。

SUSE® Rancher Prime Continuous Delivery 代理作为 Helm 图表安装。Helm 图表安装的唯一参数应为集群注册令牌，由`values.yaml` 文件表示和客户端 ID。客户端 ID 是可选的。

首先，在SUSE® Rancher Prime Continuous Delivery Manager 中创建一个具有您选择的随机客户端 ID 的`Cluster`。

kind: Cluster
apiVersion: fleet.cattle.io/v1alpha1
metadata:
  name: my-cluster
  namespace: clusters
spec:
  clientID: "really-random"

其次，按照 [集群注册令牌说明]((#create-cluster-registration-tokens) 获取要使用的 values.yaml 文件。

第三，设置您的环境以使用客户端 ID。

CLUSTER_CLIENT_ID="really-random"

使用正确的名称空间和发布名称：对于代理图表，名称空间必须是`cattle-fleet-system`，发布名称是`fleet-agent`。

确保您正在安装到正确的集群： Helm将使用`${HOME}/.kube/config`中的默认上下文来部署代理。使用`--kubeconfig`和`--kube-context`来更改Helm安装的集群。

添加Fleet的Helm储存库。

helm repo add fleet https://rancher.github.io/fleet-helm-charts/

最后，使用Helm安装代理。

安装
验证

helm -n cattle-fleet-system install --create-namespace --wait \
    --set clientID="$CLUSTER_CLIENT_ID" \
    --values values.yaml \
    fleet-agent fleet/fleet-agent

您可以通过运行以下命令检查 Fleet pod 的状态：

# Ensure kubectl is pointing to the right cluster kubectl -n cattle-fleet-system logs -l app=fleet-agent kubectl -n cattle-fleet-system get pods -l app=fleet-agent

代理现在应该已部署。

kubectl -n clusters get clusters.fleet.cattle.io

NAME                   BUNDLES-READY   NODES-READY   SAMPLE-NODE             LAST-SEEN              STATUS
my-cluster             1/1             1/1           k3d-cluster2-server-0   2020-08-31T19:23:10Z

创建集群注册令牌

不需要管理器发起的注册：对于管理器发起的注册，令牌由 SUSE® Rancher Prime Continuous Delivery 管理器管理，无需手动创建和获取。

对于代理发起的注册，下游集群必须具有集群注册令牌。集群注册令牌用于为集群建立新的身份。在内部，集群注册令牌通过创建具有在特定名称空间中创建`ClusterRegistrationRequests` 权限的 Kubernetes 服务帐户来管理。一旦集群注册，便会为该集群创建一个新的`ServiceAccount`，作为集群的唯一标识。代理设计为在注册后忘记集群注册令牌。虽然代理在成功注册后不会保留对集群注册令牌的引用，但请注意，通常其他系统启动脚本会保留。

由于集群注册令牌会被遗忘，如果需要重新注册集群，必须为集群提供一个新的注册令牌。

令牌TTL

集群注册令牌可以被名称空间中的任何集群重用。令牌可以设置TTL，以便在特定时间后过期。

创建一个新令牌

`ClusterRegistationToken`是一个名称空间类型，应在您将创建`GitRepo`和`ClusterGroup`资源的同一名称空间中创建。有关SUSE® Rancher Prime Continuous Delivery中名称空间使用的详细信息，请参阅namespaces的文档。使用以下YAML创建一个新令牌。

kind: ClusterRegistrationToken
apiVersion: "fleet.cattle.io/v1alpha1"
metadata:
    name: new-token
    namespace: clusters
spec:
    # A duration string for how long this token is valid for. A value <= 0 or null means infinite time.
    ttl: 240h

在创建`ClusterRegistrationToken`后，SUSE® Rancher Prime Continuous Delivery将创建一个具有相同名称的相应`Secret`。由于`Secret`的创建是异步进行的，您需要等到它可用后才能使用。

一种方法是通过以下单行命令：

while ! kubectl --namespace=clusters  get secret new-token; do sleep 5; done

获取令牌值（代理values.yaml）

令牌值包含一个`values.yaml`文件的YAML内容，预计将传递给`helm install`以在下游集群上安装SUSE® Rancher Prime Continuous Delivery代理。

该值包含在上述`Secret`的`values`字段中。要获取上述示例的YAML内容，可以运行以下单行命令：

kubectl --namespace clusters get secret new-token -o 'jsonpath={.data.values}' | base64 --decode > values.yaml

一旦`values.yaml`准备就绪，集群可以重复使用它进行注册，直到TTL过期。

管理器发起

管理器发起的注册流程通过在SUSE® Rancher Prime Continuous Delivery Manager 中创建一个`Cluster`资源来完成，该资源引用了一个包含有效 kubeconfig 文件的 Kubernetes Secret，该文件位于名为`value`的数据字段中。

如果您使用的是SUSE® Rancher Prime Continuous Delivery独立的_不带Rancher_，则必须按照安装细节中的说明进行安装。

当您从Rancher仪表板添加集群时，使用管理器发起的注册。

创建 Kubeconfig 密钥

此密钥的格式旨在与 kubeconfig 密钥在 cluster-api中使用的格式相匹配。这意味着您可以使用`cluster-api`创建一个通过SUSE® Rancher Prime Continuous Delivery动态注册的集群。

title="Kubeconfig Secret Example"
kind: Secret
apiVersion: v1
metadata:
  name: my-cluster-kubeconfig
  namespace: clusters
data:
  value: YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6Ci0gY2x1c3RlcjoKICAgIHNlcnZlcjogaHR0cHM6Ly9leGFtcGxlLmNvbTo2NDQzCiAgbmFtZTogY2x1c3Rlcgpjb250ZXh0czoKLSBjb250ZXh0OgogICAgY2x1c3RlcjogY2x1c3RlcgogICAgdXNlcjogdXNlcgogIG5hbWU6IGRlZmF1bHQKY3VycmVudC1jb250ZXh0OiBkZWZhdWx0CmtpbmQ6IENvbmZpZwpwcmVmZXJlbmNlczoge30KdXNlcnM6Ci0gbmFtZTogdXNlcgogIHVzZXI6CiAgICB0b2tlbjogc29tZXRoaW5nCg==

创建集群资源

集群资源需要引用 Kubeconfig 密钥。

title="Cluster Resource Example"
apiVersion: fleet.cattle.io/v1alpha1
kind: Cluster
metadata:
  name: my-cluster
  namespace: clusters
  labels:
    demo: "true"
    env: dev
spec:
  kubeConfigSecret: my-cluster-kubeconfig