Миграция Kubernetes-кластера на ALT Orchestra

Эта инструкция описывает миграцию существующего Kubernetes-кластера, установленного на обычной системе ALT Linux, на узлы ALT Orchestra.

Сценарий предполагает, что вы постепенно добавляете в существующий кластер новые control plane и worker-узлы на базе ALT Orchestra, переводите Kubernetes API на новый endpoint, а затем выводите старые узлы из эксплуатации.

Требования

Перед началом убедитесь, что у вас есть:

• полный административный доступ к старому кластеру;
• полный доступ к PKI старого кластера. Стандартный путь на обычной системе: /etc/kubernetes/pki;
• доступ к машине администратора с установленными kubectl и talosctl;
• резервная копия etcd и критичных данных кластера;
• тестовый кластер или стенд, на котором можно предварительно проверить миграцию с вашей сетевой инфраструктурой и рабочими нагрузками.

Версия Kubernetes в старом кластере должна входить в матрицу поддержки ALT Orchestra (замечание по kube-proxy также очень важно для миграции). Если версия не поддерживается, сначала обновите старый кластер до поддерживаемой версии, а затем выполните миграцию.

WARNING

Не выполняйте миграцию сразу на production-кластере без проверки на тестовом стенде. Инструкция рассчитана на сценарий с полным административным доступом к старому кластеру и его PKI.

Тестовая среда

Инструкция проверялась на следующем стенде:

• старый кластер: Kubernetes v1.33.12 с Flannel;
• новый кластер: ALT Orchestra 11.0.

Подготовка переменных

Зафиксируйте параметры нового кластера в переменных среды:

CONTROL_PLANE_IP=<control-plane-ip>
WORKER_IP=("<worker-ip-1>" "<worker-ip-2>" "<worker-ip-3>")
CLUSTER_ENDPOINT=<endpoint-ip>
CLUSTER_NAME="myOldClusterName"

CLUSTER_ENDPOINT — IP-адрес или DNS-имя, по которому будет доступен Kubernetes API после миграции. Варианты настройки отказоустойчивой точки доступа описаны в разделе Конечная точка доступа Kubernetes API.

CLUSTER_NAME должен совпадать с именем старого Kubernetes-кластера.

Генерация секретов из PKI старого кластера

Сгенерируйте файл secrets.yaml из PKI старого кластера:

talosctl gen secrets \
  --from-kubernetes-pki /etc/kubernetes/pki \
  --output-file secrets.yaml

Команду не обязательно выполнять на старой control plane-ноде. Можно перенести каталог /etc/kubernetes/pki на машину с установленным talosctl и запустить команду оттуда.

Генерация конфигураций ALT Orchestra

Сгенерируйте конфигурационные файлы для узлов ALT Orchestra:

talosctl gen config \
  --with-secrets secrets.yaml \
  "$CLUSTER_NAME" \
  "https://$CLUSTER_ENDPOINT:6443"

Подробно генерация конфигураций описана в разделе быстрый старт, но при миграции не выполняйте шаги talosctl bootstrap и talosctl kubeconfig из этой инструкции. В миграционном сценарии Kubernetes-кластер уже существует, а первая control plane-нода ALT Orchestra должна присоединиться к нему с использованием PKI старого кластера.

Для миграции важно изменить сгенерированные манифесты:

• имя кластера должно совпадать с именем старого кластера;
• поле cluster.network.cni должно быть установлено в none, чтобы ALT Orchestra не разворачивала новую CNI-сеть поверх существующей. Подробнее этот режим описан в разделе Пользовательское развертывание CNI.

cluster:
  network:
    cni:
      name: none

Перенос параметров kube-apiserver

На старой control plane-ноде посмотрите параметры kube-apiserver, связанные с service account:

grep -E 'service-account-issuer|api-audiences|service-account-key-file|service-account-signing-key-file' \
  /etc/kubernetes/manifests/kube-apiserver.yaml

В манифестах новых control plane-нод ALT Orchestra явно задайте такие же issuer и audience:

cluster:
  apiServer:
    extraArgs:
      service-account-issuer: https://kubernetes.default.svc.cluster.local
      api-audiences: https://kubernetes.default.svc.cluster.local

Отключение KubePrism

На время миграции отключите KubePrism, чтобы kubelet и компоненты узла обращались к Kubernetes API напрямую через заданный cluster.controlPlane.endpoint. Это важно в переходном состоянии, когда первая control plane-нода ALT Orchestra присоединяется к уже существующему кластеру и endpoint сначала указывает на старый Kubernetes API. После завершения миграции KubePrism можно включить отдельным изменением конфигурации, если он нужен в вашей схеме эксплуатации:

machine:
  features:
    diskQuotaSupport: true
    kubePrism:
      enabled: false

Добавление первой control plane-ноды ALT Orchestra

Перед применением конфигурации первой новой control plane-ноды временно укажите в поле cluster.controlPlane.endpoint endpoint старого Kubernetes API:

cluster:
  controlPlane:
    endpoint: https://<old-control-plane-endpoint>:6443

Примените конфигурацию на новую control plane-ноду:

talosctl apply-config \
  -n "$CONTROL_PLANE_IP" \
  --endpoints <old-control-plane-endpoint> \
  -f <path-to-controlplane.yaml> \
  --insecure

На ноду будут загружены образы core-компонентов Kubernetes и установщик ALT Orchestra. Во время установки предупреждения вида Get https://localhost:6443/... dial tcp [::1]:6443: connect: connection refused можно игнорировать.

Дождитесь, когда новая нода перейдёт в состояние Ready:

kubectl get nodes -o wide

Проверьте состояние системных компонентов:

kubectl get pods -n kube-system \
  --field-selector=status.phase!=Running

Также проверьте сетевую инфраструктуру и критичные namespace ваших приложений.

Переключение endpoint на новую control plane-ноду

На машине администратора обновите endpoint Kubernetes API в kubeconfig:

kubectl config set-cluster "$CLUSTER_NAME" \
  --server="https://$CLUSTER_ENDPOINT:6443"

В конфигурации новой control plane-ноды поменяйте cluster.controlPlane.endpoint на адрес новой control plane-ноды или новый постоянный endpoint:

cluster:
  controlPlane:
    endpoint: https://<new-control-plane-endpoint>:6443

Примените конфигурацию повторно, уже без --insecure:

talosctl --talosconfig <path-to-talosconfig> apply-config \
  -n "$CONTROL_PLANE_IP" \
  --endpoints "$CONTROL_PLANE_IP" \
  -f <path-to-controlplane.yaml>

Переключение старых worker-нод

На всех старых worker-нодах измените endpoint control plane в файле /etc/kubernetes/kubelet.conf. Найдите поле server и укажите новый endpoint Kubernetes API.

Перезапустите kubelet на каждой старой worker-ноде:

systemctl restart kubelet

Если используется kube-proxy, обновите endpoint Kubernetes API в его ConfigMap:

kubectl -n kube-system edit cm kube-proxy

Найдите в блоке kubeconfig.conf строку server и замените старый endpoint на новый:

kubeconfig.conf: |-
  clusters:
  - cluster:
      server: https://<new-control-plane-endpoint>:6443

Перезапустите kube-proxy:

kubectl -n kube-system rollout restart ds kube-proxy
kubectl -n kube-system rollout status ds kube-proxy

Проверьте, что все ноды доступны и находятся в состоянии Ready:

kubectl get nodes -o wide

Проверьте, что kube-proxy перезапустился на всех нодах:

kubectl -n kube-system get pods -l k8s-app=kube-proxy -o wide

Вывод старых control plane-нод

Если в старом кластере была только одна control plane-нода, перед её удалением добавьте ещё одну control plane-ноду на базе ALT Orchestra. Это нужно, чтобы после удаления старой control plane-ноды у etcd сохранился кворум.

Альтернативный вариант — удалить старую control plane-ноду из состава etcd вручную с помощью etcdctl на старой control plane-ноде.

Удалите старые control plane-ноды из Kubernetes:

kubectl cordon <node-name>
kubectl delete node <node-name>

После этого добавьте остальные control plane-ноды ALT Orchestra, если они запланированы.

Добавление новых worker-нод ALT Orchestra

Примените конфигурации новых worker-нод:

talosctl apply-config \
  -n <worker-ip> \
  --endpoints "$CONTROL_PLANE_IP" \
  -f <path-to-worker.yaml> \
  --insecure

Проверьте, что новые worker-ноды присоединились к кластеру:

kubectl get nodes -o wide

Вывод старых worker-нод

Для каждой старой worker-ноды выполните:

kubectl cordon <node-name>
kubectl drain <node-name> \
  --ignore-daemonsets \
  --delete-emptydir-data
kubectl delete node <node-name>

Обновление Kubernetes после миграции

После миграции обновите Kubernetes средствами talosctl. Базовая процедура описана в разделе Обновление версии кластера Kubernetes.

После завершения этих шагов узлы кластера работают на базе ALT Orchestra, а Kubernetes обновлён до целевой версии.