快速开始

本文档指导您使用 Hosted Control Plane 架构创建一个新的 Kubernetes 集群。

前提条件

在创建 hosted control plane 集群之前，请确保满足以下要求：

管理集群准备就绪

选择一个 Alauda Container Platform 业务集群作为管理集群。管理集群必须处于就绪状态，因为 hosted control plane 组件将在其内运行。

如果选择业务集群作为管理集群，请在 global CLI 控制台运行以下命令：

kubectl label clusters -n cpaas-system {MANAGEMENT_CLUSTER_NAME} cpaas.io/capi-cluster-manager=true

环境要求

管理集群必须安装以下集群插件：

Alauda Container Platform Kubeadm Provider
Alauda Container Platform Hosted Control Plane
Alauda Container Platform SSH Infrastructure Provider

LoadBalancer 要求

管理集群必须支持 LoadBalancer 类型的服务，如 MetalLB（由 Alauda Container Platform 提供）或云端负载均衡器。

工作主机准备就绪

在创建新集群之前，工作主机必须准备好。工作主机可以是物理机或虚拟机。

有关工作主机的详细要求，请参阅工作主机要求。

Etcd 集群准备就绪

每个 HCP 集群都需要一个 etcd 集群作为 kube-apiserver 的存储后端。您需要在创建新的 HCP 集群之前部署 etcd 集群。如果尚未准备 etcd 集群，请参考文档 Deploy Etcd Cluster 获取部署说明。

流程概览

创建 hosted control plane 集群主要包括以下步骤：

声明后端存储 - 创建 DataStore 资源配置 etcd 后端
创建 Hosted Control Plane - 部署控制平面资源
添加工作节点 - 部署工作节点资源
从 Alauda Container Platform 访问 - 集成 ACP 管理控制台

以下章节将详细介绍每个步骤。

第 1 步：声明后端存储

创建一个 DataStore 资源，声明 kube-apiserver 的存储后端。单个 DataStore 资源可被多个 HCP 集群共享。

---
apiVersion: kamaji.clastix.io/v1alpha1
kind: DataStore
metadata:
  name: {DATASTORE_NAME}
spec:
  driver: etcd
  endpoints:
    - {ETCD_ENDPOINT_0}
    - {ETCD_ENDPOINT_1}
    - {ETCD_ENDPOINT_2}
  basicAuth: null
  tlsConfig:
    certificateAuthority:
      certificate:
        secretReference:
          name: {ETCD_CA_SECRET_NAME}
          namespace: {NAMESPACE}
          keyPath: "tls.crt"
      privateKey:
        secretReference:
          name: {ETCD_CA_SECRET_NAME}
          namespace: {NAMESPACE}
          keyPath: "tls.key"
    clientCertificate:
      certificate:
        secretReference:
          name: {ETCD_CLIENT_TLS_SECRET_NAME}
          namespace: {NAMESPACE}
          keyPath: "tls.crt"
      privateKey:
        secretReference:
          name: {ETCD_CLIENT_TLS_SECRET_NAME}
          namespace: {NAMESPACE}
          keyPath: "tls.key"

DataStore 参数

参数	类型	必填	描述
`metadata.name`	string	是	DataStore 资源名称。请使用描述性名称以便识别该存储后端。
`spec.driver`	string	是	存储驱动类型。目前仅支持 `etcd`。
`spec.endpoints`	[]string	是	etcd 集群的端点列表。提供多个端点以保证高可用。格式：`hostname:port` 或 `service-name.namespace.svc.cluster.local:port`
`spec.basicAuth`	object	否	etcd 的基本认证配置。使用 TLS 证书认证时设置为 `null`。
`spec.tlsConfig`	object	是	与 etcd 集群安全通信的 TLS 配置。
`spec.tlsConfig.certificateAuthority`	object	是	用于验证 etcd 服务器证书的 CA 证书配置。
`spec.tlsConfig.certificateAuthority.certificate.secretReference.name`	string	是	存放 etcd CA 证书的 Secret 名称。
`spec.tlsConfig.certificateAuthority.certificate.secretReference.namespace`	string	是	CA 证书 Secret 所在的命名空间。
`spec.tlsConfig.certificateAuthority.certificate.secretReference.keyPath`	string	是	Secret 中证书文件的键路径。默认值：`tls.crt`。
`spec.tlsConfig.certificateAuthority.privateKey.secretReference.name`	string	是	存放 etcd CA 私钥的 Secret 名称。
`spec.tlsConfig.certificateAuthority.privateKey.secretReference.namespace`	string	是	CA 私钥 Secret 所在的命名空间。
`spec.tlsConfig.certificateAuthority.privateKey.secretReference.keyPath`	string	是	Secret 中私钥文件的键路径。默认值：`tls.key`。
`spec.tlsConfig.clientCertificate.certificate.secretReference.name`	string	是	存放 etcd 客户端证书的 Secret 名称。
`spec.tlsConfig.clientCertificate.certificate.secretReference.namespace`	string	是	客户端证书 Secret 所在的命名空间。
`spec.tlsConfig.clientCertificate.certificate.secretReference.keyPath`	string	是	Secret 中证书文件的键路径。默认值：`tls.crt`。
`spec.tlsConfig.clientCertificate.privateKey.secretReference.name`	string	是	存放 etcd 客户端私钥的 Secret 名称。
`spec.tlsConfig.clientCertificate.privateKey.secretReference.namespace`	string	是	客户端私钥 Secret 所在的命名空间。
`spec.tlsConfig.clientCertificate.privateKey.secretReference.keyPath`	string	是	Secret 中私钥文件的键路径。默认值：`tls.key`。

重要说明：

所有证书和密钥文件必须先存储在 Kubernetes Secret 中，才能创建 DataStore 资源。
etcd 集群必须能被管理集群访问，管理集群是 hosted control plane 运行所在。
生产环境强烈建议使用 TLS 认证。
单个 DataStore 可服务多个 HCP 集群，实现资源共享。

第 2 步：创建 Hosted Control Plane

控制平面部署需要按顺序创建以下 Kubernetes 资源。

INFO

最佳实践： 为实现集中管理和运维一致性，建议将所有 hosted control plane 资源部署在 cpaas-system 命名空间内。

2.1 创建 Cluster 资源

创建 Cluster API 的 Cluster 资源，声明集群并配置网络 CIDR。

重要： podCIDR 和 serviceCIDR 不得与管理集群的网络范围重叠。

---
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: {CLUSTER_NAME}
  namespace: {NAMESPACE}
  annotations:
    capi.cpaas.io/resource-group-version: infrastructure.cluster.x-k8s.io/v1beta1
    capi.cpaas.io/resource-kind: SSHCluster
  labels:
    cluster-type: HCP
spec:
  clusterNetwork:
    pods:
      cidrBlocks:
        - {POD_CIDR}
    services:
      cidrBlocks:
        - {SERVICE_CIDR}
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KamajiControlPlane
    name: {CLUSTER_NAME}
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: SSHCluster
    name: {CLUSTER_NAME}

参数说明：

{CLUSTER_NAME}：集群名称（例如 my-hcp-cluster）
{NAMESPACE}：集群资源所在命名空间（通常为 cpaas-system）
{POD_CIDR}：Pod 网络 CIDR（例如 10.7.0.0/16）
{SERVICE_CIDR}：Service 网络 CIDR（例如 10.8.0.0/16）

2.2 创建 Registry 凭证 Secret（可选）

创建用于容器镜像仓库认证的 Secret。如果仓库不需要认证，可跳过此步骤。

---
apiVersion: v1
kind: Secret
metadata:
  name: {REGISTRY_CREDENTIAL_NAME}
  namespace: {NAMESPACE}
data:
  username: {BASE64_ENCODED_USERNAME}
  password: {BASE64_ENCODED_PASSWORD}
type: Opaque

参数说明：

{REGISTRY_CREDENTIAL_NAME}：仓库凭证 Secret 名称（例如 registry-credentials）
{BASE64_ENCODED_USERNAME}：Base64 编码的仓库用户名
{BASE64_ENCODED_PASSWORD}：Base64 编码的仓库密码

2.3 创建 SSHCluster 资源

配置基于 SSH 的基础设施集群。

---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: SSHCluster
metadata:
  name: {CLUSTER_NAME}
  namespace: {NAMESPACE}
spec:
  bootstrapImage:
    registry: {REGISTRY_ADDRESS}
    auth:  # 如果仓库不需要认证，请省略此部分
      name: {REGISTRY_CREDENTIAL_NAME}
  containerNetwork:
    type: calico
  controlPlaneLoadBalancers:
    type: none

参数说明：

{REGISTRY_ADDRESS}：容器镜像仓库地址（例如 harbor.example.com）
{REGISTRY_CREDENTIAL_NAME}：仓库凭证 Secret 名称（无认证时省略 auth 部分）

2.4 创建 KamajiControlPlane 资源

在创建 KamajiControlPlane 资源之前，请从管理集群获取 CoreDNS 和 kube-proxy 镜像标签：

# 获取 CoreDNS 镜像标签
kubectl get pods -n kube-system -l k8s-app=kube-dns -o jsonpath='{.items[0].spec.containers[0].image}'

# 获取 kube-proxy 镜像标签
kubectl get pods -n kube-system -l k8s-app=kube-proxy -o jsonpath='{.items[0].spec.containers[0].image}'

创建 KamajiControlPlane 资源：

---
apiVersion: controlplane.cluster.x-k8s.io/v1alpha1
kind: KamajiControlPlane
metadata:
  name: {CLUSTER_NAME}
  namespace: {NAMESPACE}
spec:
  dataStoreName: {DATASTORE_NAME}
  addons:
    coreDNS:
      imageRepository: {REGISTRY_ADDRESS}/tkestack
      imageTag: {COREDNS_IMAGE_TAG}
    konnectivity:
      server:
        port: 8131
      agent:
        image: {REGISTRY_ADDRESS}/ait/apiserver-network-proxy-agent
        tolerations:
          - key: node-role.kubernetes.io/unschedulable
            operator: Exists
    kubeProxy:
      imageRepository: {REGISTRY_ADDRESS}/tkestack
      imageTag: {KUBE_PROXY_IMAGE_TAG}
  kubelet:
    cgroupfs: systemd
    preferredAddressTypes:
      - InternalIP
      - Hostname
  network:
    serviceType: LoadBalancer
  deployment:
    replicas: {CONTROL_PLANE_REPLICAS}
  version: {KUBERNETES_VERSION}

参数说明：

{DATASTORE_NAME}：第 1 步创建的 DataStore 资源名称
{REGISTRY_ADDRESS}：容器镜像仓库地址
{COREDNS_IMAGE_TAG}：CoreDNS 镜像标签（由上述命令获取）
{KUBE_PROXY_IMAGE_TAG}：kube-proxy 镜像标签（通常与 Kubernetes 版本一致）
{CONTROL_PLANE_REPLICAS}：控制平面副本数（推荐 3 以保证高可用）
{KUBERNETES_VERSION}：Kubernetes 版本（例如 v1.32.7，请参考 global 集群支持的版本）

2.5 验证控制平面状态

部署控制平面资源后，验证所有组件是否正常运行：

检查 KamajiControlPlane 状态

kubectl get kamajicontrolplane -n {NAMESPACE}

预期输出：

NAME            VERSION   INITIALIZED   READY   AGE
{CLUSTER_NAME}  v1.32.7   true          true    2m24s

检查 TenantControlPlane 状态

kubectl get tenantcontrolplane -n {NAMESPACE}

预期输出：

NAME            VERSION   STATUS   CONTROL-PLANE ENDPOINT      KUBECONFIG                        DATASTORE           AGE
{CLUSTER_NAME}  v1.32.7   Ready    192.168.142.243:6443        {CLUSTER_NAME}-admin-kubeconfig   {DATASTORE_NAME}    2m

检查控制平面 Pod

kubectl get pods -n {NAMESPACE} | grep {CLUSTER_NAME}

预期输出（所有 Pod 状态应为 Running）：

{CLUSTER_NAME}-7c94d64d6c-gcn6q   4/4   Running   0   3m37s
{CLUSTER_NAME}-7c94d64d6c-kktn4   4/4   Running   0   3m37s
{CLUSTER_NAME}-7c94d64d6c-thhfk   4/4   Running   0   3m37s

如果以上三项检查均显示健康状态，则控制平面部署成功。

第 3 步：添加工作节点

控制平面运行后，添加工作节点到集群。

3.1 创建 SSHHost 和凭证

为每个工作节点创建 SSH 凭证和主机定义：

---
apiVersion: v1
kind: Secret
metadata:
  name: {HOST_CREDENTIAL_NAME}
  namespace: {NAMESPACE}
data:
  username: {BASE64_ENCODED_SSH_USERNAME}
  password: {BASE64_ENCODED_SSH_PASSWORD}
type: Opaque
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: SSHHost
metadata:
  name: {HOST_NAME}
  namespace: {NAMESPACE}
spec:
  authCredential:
    name: {HOST_CREDENTIAL_NAME}
  ip: {HOST_IP_ADDRESS}
  port: {SSH_PORT}
  reUse: {REUSE_HOST}

参数说明：

{HOST_CREDENTIAL_NAME}：SSH 凭证 Secret 名称（例如 worker-node-credentials）
{BASE64_ENCODED_SSH_USERNAME}：Base64 编码的 SSH 用户名
{BASE64_ENCODED_SSH_PASSWORD}：Base64 编码的 SSH 密码
{HOST_NAME}：工作主机名称（例如 worker-node-1）
{HOST_IP_ADDRESS}：工作主机 IP 地址（例如 192.168.143.64）
{SSH_PORT}：SSH 端口（默认 22）
{REUSE_HOST}：Machine 删除后是否重用主机（true 或 false）。若为 true，对应 Machine 资源删除时主机会被清理并重用。

3.2 创建 SSHMachineTemplate

定义机器模板，指定容器运行时配置。

注意： 当前仅支持 containerd。插件默认包含 containerd 版本 1.7.27-4。如使用其他版本，请确保对应镜像已存在于您的仓库。

---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: SSHMachineTemplate
metadata:
  name: {MACHINE_TEMPLATE_NAME}
  namespace: {NAMESPACE}
spec:
  template:
    spec:
      containerRuntime:
        type: containerd
        version: {CONTAINERD_VERSION}

参数说明：

{MACHINE_TEMPLATE_NAME}：机器模板名称（例如 worker-template）
{CONTAINERD_VERSION}：容器运行时版本（例如 1.7.27-4）

3.3 创建 KubeadmConfigTemplate

配置 kubelet 设置。如无特殊需求，可使用默认配置。

---
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
kind: KubeadmConfigTemplate
metadata:
  name: {CONFIG_TEMPLATE_NAME}
  namespace: {NAMESPACE}
spec:
  template:
    spec:
      joinConfiguration:
        nodeRegistration: {}

参数说明：

{CONFIG_TEMPLATE_NAME}：配置模板名称（例如 worker-config-template）

3.4 创建 MachineDeployment

通过 MachineDeployment 部署工作节点：

---
apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
  name: {MACHINE_DEPLOYMENT_NAME}
  namespace: {NAMESPACE}
spec:
  clusterName: {CLUSTER_NAME}
  replicas: {WORKER_NODE_REPLICAS}
  selector:
    matchLabels: null
  template:
    spec:
      bootstrap:
        configRef:
          apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
          kind: KubeadmConfigTemplate
          name: {CONFIG_TEMPLATE_NAME}
      clusterName: {CLUSTER_NAME}
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: SSHMachineTemplate
        name: {MACHINE_TEMPLATE_NAME}
      version: {KUBERNETES_VERSION}

参数说明：

{MACHINE_DEPLOYMENT_NAME}：机器部署名称（例如 worker-deployment）
{CLUSTER_NAME}：集群名称（必须与 Cluster 资源名称一致）
{WORKER_NODE_REPLICAS}：工作节点副本数（不得超过可用的 SSHHost 资源数量）
{CONFIG_TEMPLATE_NAME}：上述创建的 KubeadmConfigTemplate 名称
{MACHINE_TEMPLATE_NAME}：上述创建的 SSHMachineTemplate 名称
{KUBERNETES_VERSION}：Kubernetes 版本（例如 v1.32.7，必须与控制平面版本一致）

3.5 验证工作节点状态

部署后，检查 MachineDeployment 状态：

kubectl get machinedeployment -n {NAMESPACE}

预期输出：

NAME                        CLUSTER         REPLICAS   READY   UPDATED   UNAVAILABLE   PHASE     AGE
{MACHINE_DEPLOYMENT_NAME}   {CLUSTER_NAME}  1          1       1         0             Running   5m

若状态显示正常，则工作节点已成功添加到集群。

第 4 步：从 Alauda Container Platform 访问

集群部署完成后，将其集成到 Alauda Container Platform。

获取集群 Kubeconfig

在管理集群上运行以下命令获取集群的 kubeconfig：

kubectl get secret -n {NAMESPACE} {CLUSTER_NAME}-admin-kubeconfig -o jsonpath='{.data.value}' | base64 -d

导入 ACP

使用获取的 kubeconfig，通过 ACP 控制台界面将集群导入 Alauda Container Platform。

故障排查

部署过程中遇到问题时，请检查以下内容：

控制平面问题：
- 验证 DataStore 与 etcd 集群的连通性
- 查看控制平面 Pod 日志：kubectl logs -n {NAMESPACE} {POD_NAME}
- 确认 LoadBalancer 服务是否获得外部 IP
工作节点问题：
- 验证与工作主机的 SSH 连接
- 检查 SSHHost 状态：kubectl get sshhost -n {NAMESPACE}
- 查看 Machine 资源的调试日志：kubectl describe machine -n {NAMESPACE}
网络问题：
- 确保 Pod CIDR 和 Service CIDR 不与管理集群冲突
- 验证网络插件（Calico）是否正常运行
- 检查 konnectivity agent 的连通性

如需更多支持，请查阅 Alauda Container Platform 文档或联系技术支持。

#快速开始

#目录

#前提条件

#管理集群准备就绪

#环境要求

#LoadBalancer 要求

#工作主机准备就绪

#Etcd 集群准备就绪

#流程概览

#第 1 步：声明后端存储

#DataStore 参数

#第 2 步：创建 Hosted Control Plane

#2.1 创建 Cluster 资源

#2.2 创建 Registry 凭证 Secret（可选）

#2.3 创建 SSHCluster 资源

#2.4 创建 KamajiControlPlane 资源

#2.5 验证控制平面状态

#检查 KamajiControlPlane 状态

#检查 TenantControlPlane 状态

#检查控制平面 Pod

#第 3 步：添加工作节点

#3.1 创建 SSHHost 和凭证

#3.2 创建 SSHMachineTemplate

#3.3 创建 KubeadmConfigTemplate

#3.4 创建 MachineDeployment

#3.5 验证工作节点状态

#第 4 步：从 Alauda Container Platform 访问

#获取集群 Kubeconfig

#导入 ACP

#故障排查

快速开始

目录

前提条件

管理集群准备就绪

环境要求

LoadBalancer 要求

工作主机准备就绪

Etcd 集群准备就绪

流程概览

第 1 步：声明后端存储

DataStore 参数

第 2 步：创建 Hosted Control Plane

2.1 创建 Cluster 资源

2.2 创建 Registry 凭证 Secret（可选）

2.3 创建 SSHCluster 资源

2.4 创建 KamajiControlPlane 资源

2.5 验证控制平面状态

检查 KamajiControlPlane 状态

检查 TenantControlPlane 状态

检查控制平面 Pod

第 3 步：添加工作节点

3.1 创建 SSHHost 和凭证

3.2 创建 SSHMachineTemplate

3.3 创建 KubeadmConfigTemplate

3.4 创建 MachineDeployment

3.5 验证工作节点状态

第 4 步：从 Alauda Container Platform 访问

获取集群 Kubeconfig

导入 ACP

故障排查