#Быстрый старт

В этом документе описывается процесс создания нового кластера Kubernetes с использованием архитектуры Hosted Control Plane.

#Предварительные требования

Перед созданием кластера с hosted control plane убедитесь, что выполнены следующие условия:

#Готовность управляющего кластера

Выберите кластер нагрузки Alauda Container Platform в качестве управляющего кластера. Управляющий кластер должен быть готов до создания нового HCP-кластера, так как компоненты hosted control plane будут запускаться внутри него.

Если вы выбираете кластер нагрузки в качестве управляющего, выполните следующую команду в глобальной консоли 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. Необходимо развернуть etcd кластер до создания нового HCP-кластера. Если etcd кластер ещё не подготовлен, обратитесь к документу Deploy Etcd Cluster для инструкций по развертыванию etcd.

#Обзор процесса

Создание кластера с hosted control plane включает следующие основные шаги:

1. Объявление backend-хранилища — создание ресурса DataStore для настройки etcd backend
2. Создание Hosted Control Plane — развертывание ресурсов control plane
3. Добавление рабочих узлов — развертывание ресурсов рабочих узлов
4. Доступ из Alauda Container Platform — интеграция с консолью управления ACP

Ниже приведены подробные инструкции для каждого шага.

#Шаг 1: Объявление backend-хранилища

Создайте ресурс DataStore, который объявляет backend-хранилище для 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

Важные замечания:

• Все файлы сертификатов и ключей должны быть сохранены в Kubernetes Secrets до создания ресурса DataStore.
• etcd кластер должен быть доступен из управляющего кластера, в котором запускаются hosted control plane.
• Для производственных сред настоятельно рекомендуется использовать аутентификацию TLS.
• Один DataStore может обслуживать несколько HCP-кластеров, что позволяет эффективно использовать ресурсы.

#Шаг 2: Создание Hosted Control Plane

Для развертывания control plane необходимо последовательно создать следующие ресурсы Kubernetes.

#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}: Namespace для ресурсов кластера (обычно cpaas-system)
• {POD_CIDR}: CIDR сети для подов (например, 10.7.0.0/16)
• {SERVICE_CIDR}: CIDR сети для сервисов (например, 10.8.0.0/16)

#2.2 Создание секрета с учётными данными реестра (опционально)

Создайте 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}: Имя секрета с учётными данными реестра (например, 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}: Имя секрета с учётными данными реестра (если аутентификация не нужна, блок 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}: Имя ресурса DataStore, созданного на Шаге 1
• {REGISTRY_ADDRESS}: Адрес контейнерного реестра
• {COREDNS_IMAGE_TAG}: Тег образа CoreDNS (полученный выше)
• {KUBE_PROXY_IMAGE_TAG}: Тег образа kube-proxy (обычно совпадает с версией Kubernetes)
• {CONTROL_PLANE_REPLICAS}: Количество реплик control plane (рекомендуется 3 для высокой доступности)
• {KUBERNETES_VERSION}: Версия Kubernetes (например, v1.32.7, проверьте поддерживаемые версии в глобальном кластере)

#2.5 Проверка статуса control plane

После развертывания ресурсов control plane проверьте, что все компоненты работают корректно:

#Проверка статуса 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

#Проверка подов control plane

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

Ожидаемый вывод (все поды должны быть в состоянии 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

Если все три проверки показывают здоровый статус, развертывание control plane прошло успешно.

#Шаг 3: Добавление рабочих узлов

После запуска control plane добавьте рабочие узлы в кластер.

#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-учётными данными (например, worker-node-credentials)
• {BASE64_ENCODED_SSH_USERNAME}: SSH имя пользователя в base64
• {BASE64_ENCODED_SSH_PASSWORD}: SSH пароль в base64
• {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}: Имя MachineDeployment (например, worker-deployment)
• {CLUSTER_NAME}: Имя вашего кластера (должно совпадать с именем ресурса Cluster)
• {WORKER_NODE_REPLICAS}: Количество реплик рабочих узлов (не должно превышать количество доступных SSHHost)
• {CONFIG_TEMPLATE_NAME}: Имя созданного выше KubeadmConfigTemplate
• {MACHINE_TEMPLATE_NAME}: Имя созданного выше SSHMachineTemplate
• {KUBERNETES_VERSION}: Версия Kubernetes (например, v1.32.7, должна совпадать с версией control plane)

#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 для импорта кластера в Alauda Container Platform через интерфейс консоли ACP.

#Устранение неполадок

Если при развертывании возникают проблемы, проверьте следующее:

1. Проблемы с control plane:

   • Проверьте доступность DataStore к etcd кластеру
   • Просмотрите логи подов control plane: kubectl logs -n {NAMESPACE} {POD_NAME}
   • Убедитесь, что сервис LoadBalancer получил внешний IP

2. Проблемы с рабочими узлами:

   • Проверьте SSH-соединение с рабочими хостами
   • Проверьте статус SSHHost: kubectl get sshhost -n {NAMESPACE}
   • Просмотрите логи создания машин: kubectl describe machine -n {NAMESPACE}

3. Проблемы с сетью:

   • Убедитесь, что Pod CIDR и Service CIDR не конфликтуют с управляющим кластером
   • Проверьте корректную работу сетевого плагина (Calico)
   • Проверьте соединение агента konnectivity

Для дополнительной поддержки обратитесь к документации Alauda Container Platform или в службу поддержки.