cluster-api-provider-yandex

Провайдер Yandex Cloud для Kubernetes® Cluster API

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

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

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

• интеграция с API Yandex Cloud;
• декларативный подход к созданию и управлению кластером;
• кластер как CustomResourceDefinition;
• широкий спектр параметров для конфигурации вычислительных ресурсов кластера;
• пользовательские образы операционных систем для мастера и узлов;
• пользовательский Control Plane;
• альтернатива Terraform в CI-процессах.

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

Чтобы развернуть кластер 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. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

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

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

Платные ресурсы

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

• плата за вычислительные ресурсы ВМ, диски и образы (см. тарифы Yandex Compute Cloud);
• плата за хранение образа в бакете и операции с данными (см. тарифы Yandex Object Storage);
• плата за использование вычислительных ресурсов L7-балансировщика (см. тарифы Yandex Application Load Balancer);
• (опционально) плата за использование динамического внешнего IP-адреса для вспомогательной ВМ (см. тарифы Yandex Virtual Private Cloud);
• (опционально) плата за использование управляющего кластера (см. тарифы Yandex Managed Service for Kubernetes).

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

1. Настройте сервисный аккаунт Yandex Cloud:

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

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

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

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

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

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

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

[!IMPORTANT] Чтобы иметь возможность загружать Docker-образы c компонентами, которые будут развернуты внутри управляющего и создаваемого кластеров, у этих кластеров должен быть доступ в интернет. Например, вы можете настроить NAT-шлюз в подсетях кластеров.

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

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

   • Go версии 1.22.0 и выше;
   • gomock версии 1.6.0;
   • docker версии 17.03 и выше;
   • kubectl версии 1.11.3 и выше;
   • clusterctl версии 1.5.0 и выше.

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

   • 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.

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

Вы можете подготовить собственный образ ОС, следуя инструкции ниже:

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

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

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

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

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

Использовать готовый Docker-образ

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

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

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

Собрать Docker-образ из исходного кода

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 для создаваемого кластера:

   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. Выберите зону доступности, в которой вы хотите развернуть кластер.

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

   • образ ОС;
   • каталог;
   • сеть;
   • подсеть в выбранной зоне доступности.

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

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

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

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

   По умолчанию согласно сгенерированному манифесту, для доступа в кластер будет развернут L7-балансировщик Application Load Balancer c динамическим внутренним IP-адресом. Вы можете присвоить L7-балансировщику фиксированный IP-адрес.

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

Согласно сгенерированному манифесту будут развернуты три узла с Control Plane. Если вы хотите также сразу развернуть узлы для рабочей нагрузки, выполните команду:

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

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

Задайте в манифесте YandexCluster следующие параметры для 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.

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

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

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

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

• Cilium Quick Installation
• Quickstart for Calico on Kubernetes

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

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, ...
   

Как удалить созданные ресурсы

Удалите кластер

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

Удалите CRD из управляющего кластера

make uninstall

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

make undeploy

Удалите вспомогательные ресурсы Yandex Cloud

Чтобы перестать платить за вспомогательные ресурсы, если вы их создавали, удалите:

• Группу узлов Managed Service for Kubernetes
• Кластер Managed Service for Kubernetes
• ВМ Compute Cloud
• Образ ОС в Compute Cloud
• Образ ОС в Object Storage
• Бакет Object Storage

См. также

• Apache-2.0 license
• Соглашение с контрибьютором
• Kubernetes Cluster API
• Kubebuilder Documentation