Связаться с намиПодключиться

Создание управляемого пользователем (self-managed) кластера Kubernetes с помощью провайдера Yandex Cloud для Kubernetes Cluster API

Статья создана
Обновлена 21 мая 2025 г.

Сluster-api-provider-yandex — провайдер для развертывания управляемого пользователем (self-managed) кластера Kubernetes в облачной инфраструктуре Yandex Cloud с помощью Kubernetes Cluster API.

Кластер разворачивается на базе виртуальных машин Yandex Compute Cloud и L7-балансировщика Yandex Application Load Balancer.

Преимущества использования провайдера Yandex Cloud для создания кластера:

  • Интеграция с API Yandex Cloud.
  • Декларативный подход к созданию кластера и управлению им.
  • Возможность описать кластер как пользовательский ресурс — CustomResourceDefinition.
  • Широкий спектр параметров для конфигурации вычислительных ресурсов кластера.
  • Пользовательские образы операционных систем для мастера и узлов.
  • Пользовательский Control Plane.
  • Альтернатива Terraform в CI-процессах.

Совместимость провайдера с Kubernetes Cluster API

Версия провайдера Версия Cluster API
v1alpha1 v1beta1 (v1.x)

Чтобы развернуть кластер Kubernetes в Yandex Cloud с помощью Cluster API:

  1. Подготовьте облако к работе.
  2. Настройте окружение.
  3. Подготовьте образ операционной системы для узлов кластера.
  4. Получите Docker-образ с провайдером Yandex Cloud.
  5. Установите провайдер Yandex Cloud и провайдер Kubernetes Cluster API.
  6. Сформируйте манифесты кластера.
  7. Разверните кластер.
  8. Подключитесь к кластеру.
  9. Установите CCM.
  10. Установите CNI.
  11. Проверьте связь управляющего кластера с созданным.

Если созданные ресурсы вам больше не нужны, удалите их.

Подготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

В стоимость поддержки инфраструктуры входят:

Опциональные траты

  • Если для узлов создаваемого кластера Kubernetes вы будете использовать собственный образ:
  • Если для развертывания провайдера Yandex Cloud в управляющем кластере вы будете использовать собственный Docker-образ — плата за хранение Docker-образа в реестре и исходящий трафик (см. тарифы Yandex Container Registry).

Подготовьте инфраструктуру

  1. Подготовьте сервисный аккаунт Yandex Cloud:

    1. Создайте сервисный аккаунт, от имени которого будут создаваться ресурсы кластера.
    2. Назначьте сервисному аккаунту роли compute.editor и alb.editor на каталог.
    3. Создайте авторизованный ключ для сервисного аккаунта в формате JSON.

  2. Если в вашем каталоге еще нет облачной сети Virtual Private Cloud, создайте ее. Также создайте и подсеть.

  3. Инфраструктуре создаваемого кластера будет автоматически назначена группа безопасности по умолчанию, которая создается вместе с сетью. Добавьте в эту группу следующие правила для входящего трафика:

    Протокол Диапазон портов Тип источника Источник Описание
    TCP 0-65535 Группа безопасности Balancer Проверки состояния L7-балансировщиком
    Any 8443 CIDR 0.0.0.0/0 Доступ к Kubernetes API

  4. Создаваемый кластер будет доступен в облачной сети по внутреннему IP-адресу. Чтобы обеспечить удаленный доступ к кластеру:

    1. Создайте в той же сети, в которой будет развернут кластер, вспомогательную ВМ с публичным IP-адресом и с группой безопасности по умолчанию.
    2. Установите на вспомогательную ВМ утилиту kubectl.

  5. Создайте управляющий кластер Managed Service for Kubernetes с публичным IP-адресом и группу узлов. Кластер потребуется для развертывания нового кластера с помощью Cluster API и управления кластерной инфраструктурой.

    Совет

    Управляющий кластер также можно развернуть локально, например, с помощью утилиты kind.

  6. Чтобы создаваемый кластер имел доступ в интернет и мог загружать Docker-образы, настройте NAT-шлюз для подсети, в которой будет расположен новый кластер.

Настройте окружение

Окружение настраивается на локальном компьютере.

  1. Установите инструменты:

    • Go версии 1.22.0 или выше.
    • Docker версии 17.03 или выше.
    • kubectl версии 1.11.3 или выше.
    • clusterctl версии 1.5.0 или выше.

  2. Настройте для kubectl доступ к управляющему кластеру Managed Service for Kubernetes.

    Если вы разворачивали управляющий кластер локально с помощью утилиты kind, настройте к нему доступ по инструкции.

  3. Склонируйте репозиторий cluster-api-provider-yandex и перейдите в директорию с проектом:

    git clone https://github.com/yandex-cloud/cluster-api-provider-yandex.git
cd cluster-api-provider-yandex

Подготовьте образ операционной системы для узлов кластера

Образ ОС, который будет развернут на узлах создаваемого кластера, должен быть подготовлен для работы с Kubernetes Cluster API и совместим с Compute Cloud.

Вы можете использовать готовый тестовый образ или собрать собственный:

Чтобы использовать тестовый образ ОС на основе Ubuntu 24.04, подготовленный для работы с Kubernetes версии 1.31.4, при формировании манифеста кластера в переменной YANDEX_CONTROL_PLANE_MACHINE_IMAGE_ID укажите идентификатор образа fd8a3kknu25826s8hbq3.

Важно

Образ создан в ознакомительных целях, не используйте его в промышленной эксплуатации.

  1. Соберите образ ОС с помощью утилиты Image Builder.

    См. также Подготовить образ диска для Compute Cloud.

  2. Загрузите образ в Compute Cloud и сохраните его идентификатор.

Получите Docker-образ с провайдером Yandex Cloud

Вы можете использовать готовый Docker-образ с провайдером Yandex Cloud из публичного реестра Yandex Container Registry или собрать его самостоятельно из исходного кода.

  1. Аутентифицируйтесь в реестре Container Registry с помощью Docker Credential helper.

  2. Добавьте в переменную окружения IMG путь к Docker-образу с провайдером Yandex Cloud в публичном реестре:

    export IMG=cr.yandex/crpsjg1coh47p81vh2lc/capy/cluster-api-provider-yandex:latest

  1. Создайте реестр Container Registry и сохраните его идентификатор.

  2. Аутентифицируйтесь в реестре Container Registry с помощью Docker Credential helper.

  3. Добавьте в переменную окружения IMG путь, по которому собранный Docker-образ будет сохранен в реестре:

    export IMG=cr.yandex/<идентификатор_реестра>/cluster-api-provider-yandex:<тег>

  4. Если вы собираете Docker-образ на компьютере с архитектурой, отличной от AMD64, отредактируйте в Makefile блок docker-build:

    docker build --platform linux/amd64 -t ${IMG} .

  5. Запустите Docker daemon.

  6. Соберите Docker-образ и загрузите его в реестр:

    make docker-build docker-push

Установите провайдер Yandex Cloud и провайдер Kubernetes Cluster API

  1. Инициализируйте управляющий кластер:

    clusterctl init

    В управляющий кластер будут установлены основные компоненты Kubernetes Cluster API и cert-manager.

  2. Создайте в управляющем кластере описание пользовательского ресурса — CustomResourceDefinitions (CRD) для создаваемого кластера:

    make install

  3. Получите список установленных CRD:

    kubectl get crd | grep cluster.x-k8s.io

    Чтобы получить манифест конкретного CRD, выполните команду:

    kubectl get crd <имя_CRD> \
  --output yaml

  4. Создайте пространство имен для провайдера Yandex Cloud:

    kubectl create namespace capy-system

  5. Создайте секрет с авторизованным ключом сервисного аккаунта Yandex Cloud:

    kubectl create secret generic yc-sa-key \
  --from-file=key=<путь_к_файлу_с_авторизованным_ключом> \
  --namespace capy-system

  6. Установите провайдер Yandex Cloud:

    make deploy

Сформируйте манифесты кластера

  1. Получите идентификаторы ресурсов Yandex Cloud для развертывания кластера:

  2. Передайте идентификаторы ресурсов в переменные окружения:

    export YANDEX_CONTROL_PLANE_MACHINE_IMAGE_ID=<идентификатор_образа>
export YANDEX_FOLDER_ID=<идентификатор_каталога>
export YANDEX_NETWORK_ID=<идентификатор_сети>
export YANDEX_SUBNET_ID=<идентификатор_подсети>
export YANDEX_ZONE_ID=<идентификатор_зоны_доступности>

    Если вы не собирали свой образ ОС, в переменной YANDEX_CONTROL_PLANE_MACHINE_IMAGE_ID укажите значение fd8a3kknu25826s8hbq3. Это идентификатор тестового образа на основе Ubuntu 24.04, подходящего для работы с Kubernetes версии 1.31.4.

  3. Сформируйте манифесты кластера:

    clusterctl generate cluster <имя_создаваемого_кластера> \
  --from templates/cluster-template.yaml > /tmp/capy-cluster.yaml

    В манифесте capy-cluster.yaml будут описаны:

    • L7-балансировщик Application Load Balancer с динамическим внутренним IP-адресом. Ему можно присвоить фиксированный IP-адрес.

      Важно

      После создания кластера присвоить L7-балансировщику фиксированный IP-адрес будет нельзя.

    • Три узла с Control Plane кластера.

  4. (Опционально) Чтобы сразу развернуть узлы кластера для рабочей нагрузки, добавьте в манифест их описание:

    clusterctl generate cluster <имя_создаваемого_кластера> \
    --worker-machine-count <количество_узлов_для_рабочей_нагрузки> \
    --from templates/cluster-template.yaml > /tmp/capy-cluster.yaml

(Опционально) Настройте эндпоинт API-сервера

Задайте в манифесте capy-cluster.yaml параметры для L7-балансировщика:

  loadBalancer:
    listener:
      address: <фиксированный_IP-адрес_из_диапазона_подсети>
      subnet:
        id: <идентификатор_подсети>

Разверните кластер

Выполните команду:

kubectl apply -f /tmp/capy-cluster.yaml

За созданием кластера можно следить в консоли управления Yandex Cloud и в логах пода capy-controller-manager:

kubectl logs <имя_пода_с_capy-controller-manager> \
  --namespace capy-system \
  --follow

Подключитесь к кластеру

Реквизиты для подключения к новому кластеру будут сохранены в управляющем кластере в секрете <имя_создаваемого_кластера>-kubeconfig.

  1. Получите данные из секрета:

    kubectl get secret <имя_создаваемого_кластера>-kubeconfig \
  --output yaml | yq -r '.data.value' | base64 \
  --decode > capy-cluster-config

  2. Передайте на вспомогательную ВМ файл с конфигурацией для kubectl:

    scp <путь_к_файлу_capy-cluster-config_на_локальном_компьютере> \
<имя_пользователя>@<публичный_IP-адрес_ВМ>:/home/<имя_пользователя>/.kube/config

  3. Подключитесь к вспомогательной ВМ по SSH.

  4. Убедитесь, что созданный кластер доступен:

    kubectl cluster-info

Установите CCM в созданный кластер

Чтобы обеспечить связь между ресурсами кластера и ресурсами Yandex Cloud, установите в созданный кластер Cloud Controller Manager, например Kubernetes Cloud Controller Manager for Yandex Cloud.

Примечание

Если вы хотите использовать Kubernetes Cloud Controller Manager for Yandex Cloud, добавьте в пример манифеста yandex-cloud-controller-manager.yaml для DaemonSet актуальную версию Docker-образа и переменную окружения YANDEX_CLUSTER_NAME с именем созданного кластера.

Установите CNI в созданный кластер

Чтобы обеспечить сетевую функциональность для подов в новом кластере, установите в него Container Network Interface, например, Cilium или Calico.

Подробнее в документации:

Проверьте связь управляющего кластера с созданным

  1. Подключитесь к вспомогательной ВМ и убедитесь, что в кластере развернуты все поды с необходимыми системными компонентами:

    kubectl get pods --all-namespaces

    Пример вывода:

    NAMESPACE     NAME                                                       READY   STATUS    RESTARTS   AGE
kube-system   calico-kube-controllers-695bcfd99c-rcc42                   1/1     Running   0          3h55m
kube-system   calico-node-9qhxj                                          1/1     Running   0          3h55m
kube-system   coredns-7c65d6cfc9-52tvn                                   1/1     Running   0          4h50m
kube-system   coredns-7c65d6cfc9-dpgvg                                   1/1     Running   0          4h50m
kube-system   etcd-capy-cluster-control-plane-p646q                      1/1     Running   0          4h50m
kube-system   kube-apiserver-capy-cluster-control-plane-p646q            1/1     Running   0          4h50m
kube-system   kube-controller-manager-capy-cluster-control-plane-p646q   1/1     Running   0          4h50m
kube-system   kube-proxy-wb7jr                                           1/1     Running   0          4h50m
kube-system   kube-scheduler-capy-cluster-control-plane-p646q            1/1     Running   0          4h50m
kube-system   yandex-cloud-controller-manager-nwhwv                      1/1     Running   0          26s

  2. С локального компьютера проверьте связь управляющего кластера с созданным кластером:

    clusterctl describe cluster <имя_созданного_кластера>

    Результат:

    NAME                                                             READY  SEVERITY  REASON  SINCE  MESSAGE                                  
Cluster/capy-cluster                                             True                     10s
├─ClusterInfrastructure - YandexCluster/capy-cluster                                   
└─ControlPlane - KubeadmControlPlane/capy-cluster-control-plane  True                     10s                                                                                       
  └─3 Machines...                                                True                     3m9s   See capy-cluster-control-plane-cf72l, capy-cluster-control-plane-g9jw7, ...

Удалите созданные ресурсы

Некоторые ресурсы платные. Чтобы за них не списывалась плата, удалите ресурсы, которые вы больше не будете использовать:

  1. Удалите кластер Kubernetes, созданный с помощью Cluster API:

    kubectl delete -f /tmp/capy-cluster.yaml

  2. Удалите CRD из управляющего кластера Managed Service for Kubernetes:

    make uninstall

  3. Удалите контроллер провайдера Yandex Cloud из управляющего кластера:

    make undeploy

  4. Удалите вспомогательные ресурсы Yandex Cloud, если вы их создавали:

Предыдущая
Создание кластера Kubernetes без доступа в интернет
Следующая
Запуск рабочих нагрузок с GPU