Подготовка

Проверки и подготовка перед инсталляцией.

Последовательность установки (открытый контур) #

Ниже — общая схема шагов от подготовки до запуска платформы. Детальный процесс GUI/CLI/YAML — на странице Процесс установки.

В открытом контуре установщик и узлы обращаются к публичному реестру образов r.shturval.tech. Утилита командной строки shtil запускается на Linux-машине администратора (её называют машина shtil): она не заменяет гипервизор и не «становится узлом кластера», а поднимает временный установочный Kubernetes локально (через контейнер) и/или выполняет развёртывание кластера управления — центра управления платформой «Штурвал».

Подготовка окружения #

Цель — чтобы к моменту запуска shtil не упираться в отсутствие лицензии, сети или прав на машине и узлах.

• Утилита shtil должна быть доступна на Linux-машине администратора.
• Лицензия подтверждает редакцию платформы (CE или Enterprise) и нужна уже на этапе bootstrap — первичной загрузки компонентов установщика. Без неё команды вида install-gui / install-cli не будет выполнена. Лицензия CE может быть получена через Telegram-бот или форму на сайте; Enterprise — по договору.
• Машина shtil с одной из поддерживаемых ОС должна уметь запускать контейнеры (Docker или Podman), видеть бинарник рантайма в PATH и иметь исходящий доступ к r.shturval.tech:443. Если вы выбираете установку с графическим интерфейсом (install-gui), установщик также использует /tmp для служебных данных временного кластера — учётная запись должна иметь на это права (часто запуск от root или через sudo).
• Провайдер инфраструктуры — заранее прочитайте, как устроена работа с провайдерами в платформе: от выбранного провайдера зависит, нужно ли подготовить готовые хосты или шаблон ВМ.
• Целевая инфраструктура: либо уже подготовленные физические или виртуальные узлы Linux (сценарий провайдера Shturval v2), либо облако/виртуализация (oVirt и подобные, VMware vSphere, OpenStack и подобные), из которой установщик создаст виртуальные машины под узлы кластера управления. Во всех случаях нужно заранее понимать, сколько узлов Control Plane и Worker вы закладываете и какие у них ресурсы (см. требования).
• Балансировка KubeAPI и Ingress: заранее определите, используете ли вы внутренние балансировщики (свободные VIP на узлах) или внешние. Требования к подсети Control Plane и VIP при внутренних балансировщиках — в разделе Подсеть Control Plane и виртуальные IP (VIP) на странице требований. Требования к внешнему балансировщику — в разделе Внешний балансировщик нагрузки.
• Для Shturval v2 на каждый узел переносится SSH-ключ без passphrase, а пользователь для установки должен уметь выполнять sudo без ввода пароля — иначе автоматизация развёртывания на узлах остановится.

Машина shtil (рабочее место администратора) #

Машина shtil — рабочая станция или хост с одной из поддерживаемых ОС машины запуска shtil, с которого вызывается утилита shtil.

На машине должно быть выполнено:

• Установлены Docker или Podman; исполняемый файл рантайма находится в PATH (иначе установка может завершиться ошибкой). Если при установке используется Docker и реестр образов доступен через самоподписной или иной недоверенный сертификат, доверие к реестру должно быть настроено на уровне демона Docker до запуска shtil.
• Есть сетевой доступ к r.shturval.tech по HTTPS (порт 443).
• Для сценария с графическим интерфейсом (install-gui) нужны права, достаточные для работы с каталогом /tmp (там создаются файлы временного установочного кластера), как правило при запуске от root или через sudo — ориентируйтесь на политику вашей ОС.

С проверкой исходящего доступа к https://r.shturval.tech:443 с машины shtil см. раздел Команды для проверки ниже.

Утилита shtil: загрузка и параметры вызова #

Скачайте shtil-2.14.0:

Сделайте файл исполняемым:

chmod +x ./shtil-2.14.0

При необходимости переименуйте файл в удобное имя (например, shtil):

mv ./shtil-2.14.0 ./shtil

Версия shtil должна соответствовать версии разворачиваемой платформы.

Подготовка машины shtil к rootless Podman #

Если shtil запускается не от root и bootstrap поднимается через rootless Podman (не Docker), на хосте выполните настройки ниже. При запуске от root/sudo или при использовании Docker раздел можно пропустить.

User namespaces #

Для rootless Podman должно быть включено разрешение на создание непривилегированных user namespaces — параметр ядра kernel.unprivileged_userns_clone.

sysctl kernel.unprivileged_userns_clone

Если значение 0, установите 1: добавьте в /etc/sysctl.conf строку kernel.unprivileged_userns_clone = 1 и выполните:

sudo sysctl -p

Если команда возвращает ошибку cannot stat /proc/sys/kernel/unprivileged_userns_clone: No such file or directory, параметр настраивать не нужно.

Делегирование cgroup #

На части дистрибутивов, где systemd ниже 252 (например, Debian 11, РЕД ОС 7.3, Astra Linux 1.7, RHEL/Rocky 8, Ubuntu 20.04) без делегирования контейнер bootstrap-кластера падает с ошибкой UserNS: cpu controller needs to be delegated. См. kind rootless. Делегирование можно выполнить скриптом (см. ниже). Он создаёт /etc/systemd/system/user@.service.d/delegate.conf с Delegate=cpu cpuset io memory pids и выполняет systemctl daemon-reload.

После выполнения скрипта потребуется полный выход из SSH/сессии и повторный вход. Если bootstrap по-прежнему падает — перезагрузка хоста (как в выводе скрипта).

chmod +x ./scripts/setup-systemd-user-cgroup-delegate.sh
sudo ./scripts/setup-systemd-user-cgroup-delegate.sh

#!/usr/bin/env bash
# Настраивает делегирование cgroup-контроллеров для user@.service (systemd user session).
# Нужно для rootless Podman и локального bootstrap-кластера (kind-подобный node-image):
# без делегирования cpu контейнер падает с "UserNS: cpu controller needs to be delegated".
# См. https://kind.sigs.k8s.io/docs/user/rootless/
#
# Запуск: sudo ./scripts/setup-systemd-user-cgroup-delegate.sh
# После выполнения — полный выход из сессии пользователя и вход снова или reboot.
set -euo pipefail
DROP_IN_DIR="/etc/systemd/system/user@.service.d"
DROP_IN_FILE="${DROP_IN_DIR}/delegate.conf"
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
  echo "Запустите от root: sudo $0" >&2
  exit 1
fi
mkdir -p "$DROP_IN_DIR"
tee "$DROP_IN_FILE" <<'EOF'
[Service]
Delegate=cpu cpuset io memory pids
EOF
systemctl daemon-reload
echo "Готово: $DROP_IN_FILE"
echo "Выполните полный выход из SSH/сессии и вход снова или: sudo reboot"

Команды для проверки #

Машина shtil: доступ к публичному реестру образов r.shturval.tech #

curl -I https://r.shturval.tech

При успехе в заголовках ответа обычно есть HTTP/2 200 или HTTP/1.1 200.

Если ответа нет или есть ошибка — нужно обеспечить исходящий доступ к хосту r.shturval.tech по TCP 443 (HTTPS). Действуйте по шагам:

1. Проверка DNS — имя должно резолвиться в IP:

getent hosts r.shturval.tech

Если записей нет, настройте корпоративные DNS или параметры резолвера на машине согласно вашей ОС и политике (иначе curl не сможет подключиться).

2. Диагностика HTTPS — подробный вывод показывает, на каком этапе обрыв (резолв, TCP, TLS, ответ сервера):

curl -vI --connect-timeout 10 https://r.shturval.tech

3. Прокси — если исходящий HTTPS возможен только через прокси, задайте переменные (подставьте URL своего прокси; логин/пароль, если нужны, добавьте в URL по правилам вашей организации):

export HTTPS_PROXY=http://proxy.corp:3128

export HTTP_PROXY=http://proxy.corp:3128

curl -I https://r.shturval.tech

4. Сетевая политика — если после шагов 1–3 успешного ответа по-прежнему нет, согласуйте с администраторами сети разрешение исходящего доступа к r.shturval.tech:443 (и корректную схему прокси, если она обязательна).

Если проверка неуспешна после выполнения шагов 1–4: без исходящего доступа к r.shturval.tech:443 с машины shtil открытый контур к установке не готов — устраняйте блокировку на стороне сети или выберите другое рабочее место с уже разрешённым доступом.

Машина shtil: проверка доступа в /tmp (сценарий install-gui) #

Выполняйте под той же учётной записью, с которой будете запускать ./shtil.

touch /tmp/shturval-install-prep-check

rm -f /tmp/shturval-install-prep-check

Если проверка неуспешна: запускайте install-gui от пользователя с правами записи в /tmp (часто root или через sudo), либо устраните ограничения по политике вашей ОС. Иначе установщик не сможет разместить служебные данные временного кластера.

Проверка, что виртуальные IP-адреса свободны #

На каждом IP-адресе из подсети Control Plane, которые будут использованы в качестве VIP (для KubeAPI и/или Ingress) выполните проверку:

ping IP

Замените IP на реальный адрес (в командной строке допускается, например, ping -c 2 10.11.12.100).

Если узел отвечает на ping по выбранному VIP — выберите другой свободный IP из подсети Control Plane;

Проверка, что SELinux отключен или permissive (если дистрибутив с SELinux) #

getenforce

Если команда getenforce недоступна: на дистрибутиве без SELinux этот подраздел не применяйте (см. чек-лист).

Варианты вывода:

• enforcing — политика применяется (для согласованного сценария нужен переход в permissive или disabled, либо отдельная политика по согласованию с ИБ).
• permissive — предупреждения без блокировок (подходит при согласовании с ИБ).
• disabled — политика не загружена (подходит при согласовании с ИБ).

Если режим enforcing и требуется отключить SELinux до установки (после согласования с ИБ):

Отключение SELinux в конфигурации (действует после перезагрузки):

sudo sed -i 's/^SELINUX=.*/SELINUX=disabled/' /etc/selinux/config

После этого выполните перезагрузку:

sudo reboot

Узел: время и NTP #

timedatectl status

Если установлен Chrony:

chronyc tracking

Если команда chronyc недоступна: используйте в первую очередь timedatectl и сравнение date; при необходимости настройте или установите Chrony по документации вашей ОС.

Узел: репозитории пакетов (одна команда под вашу ОС) #

Debian / Ubuntu:

sudo apt update

RHEL и совместимые (если есть dnf):

sudo dnf repolist

Если dnf нет:

sudo yum repolist

Если проверка неуспешна: устраните ошибки доступа к зеркалам (отключите недоступные «родные» репозитории или настройте доступные источники пакетов по политике вашей организации). Повторите команду. Пока обновление индекса пакетов срывается из‑за недоступных репозиториев, установка может прерваться на шагах с пакетами ОС.

Работа с провайдерами #

Перед установкой выберите провайдера инфраструктуры и подготовьте его по соответствующему сценарию. Общую схему — экземпляры провайдеров, пулы IP и шаблоны ВМ — см. на странице Как устроена работа с провайдерами в платформе.

oVirt и подобные провайдеры #

Если выбран oVirt, zVirt, HostVM, РЕД Виртуализация или ROSA Virtualization, подготовьте среду виртуализации до запуска инсталляции: учётную запись с нужными правами, Datacenter, Cluster, сеть с профилем VNIC и DHCP. Подробности — на странице oVirt и подобные провайдеры.

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

VMware vSphere #

Если выбран VMware vSphere, подготовьте vCenter: учётную запись с сервисными ролями, Datacenter, Resource Pool, Network, Datastore и путь для хранения ВМ. Подробности — на странице VMware vSphere.

Для узлов кластера управления заранее создайте шаблон виртуальной машины. Убедитесь, что шаблон подключён к сети, из которой будущие ВМ получат адреса по DHCP.

OpenStack и подобные провайдеры #

Если выбран OpenStack, VK Cloud или Selectel, подготовьте облако до запуска инсталляции: сервисную учётную запись с нужными правами, параметры подключения к API, проект, регион, сети, типы ВМ и типы дисков. Подробности — на странице OpenStack, VK Cloud, Selectel.

Для узлов кластера управления заранее создайте шаблон виртуальной машины. Для VK Cloud проверьте тип доступа к образу: платформа может использовать только образы с типом доступа public.

Провайдер Shturval v2 #

Поднимите физические или виртуальные хосты до начала инсталляции с одной из ОС из таблицы ОС узлов кластера. Требования к ресурсам — в разделе требований, а порядок добавления хостов — на странице Shturval v2.

Локально сгенерируйте ключ без passphrase и скопируйте его на каждый узел:

ssh-keygen -t ed25519 -f ./shturval -N ""

ssh-copy-id -i ./shturval.pub shturval@10.11.12.1

Повторите ssh-copy-id для каждого IP-адреса узла (подставьте свой пользователь и адреса). SSH-ключ должен быть без passphrase. Пользователь (например, shturval) должен иметь sudo без пароля на всех целевых узлах.

Проверьте вход по SSH-ключу:

ssh -i /path/to/private_key USER@NODE

ssh -i /path/to/private_key USER@NODE 'sudo -n true'

Критерий успеха: вход по ключу без запроса пароля ключа; второй вызов завершается с кодом 0.

Если вход по SSH неуспешен: проверьте IP или имя узла, пользователя, путь к приватному ключу, права на файл ключа и что открытый ключ скопирован на узел. Убедитесь, что служба sshd на узле принимает подключения и не блокируется межсетевым экраном.

Если sudo -n true завершается ошибкой: настройте выполнение sudo без запроса пароля для пользователя установки, например через sudoers по правилам вашей организации.

Чек-лист перед установкой #

Отметьте пункты до первого запуска shtil. Команды для проверки — в разделе Команды для проверки выше. Указание «на узлах» относится к целевым узлам кластера управления при провайдере Shturval v2 (заранее подготовленные хосты); при oVirt и подобных / VMware vSphere / OpenStack и подобных часть пунктов выполняется после появления виртуальных машин узлов.

Машина shtil #

• ОС машины — из списка поддерживаемых для shtil. Хост не планируется как узел кластера.
• Лицензия готова для параметра --bootstrap-license. Текст лицензии сохранён полностью, без обрезки строк; при спецсимволах в строке передавайте её в одинарных кавычках в команде запуска (пример и сценарии — на странице Процесс установки). Окончательная проверка корректности — при успешном bootstrap. Если bootstrap отклоняет лицензию: ещё раз проверьте полноту строки и одинарные кавычки в команде; убедитесь, что редакция (CE / Enterprise) и канал получения соответствуют разделу «Лицензия и контур» выше на странице.
• Установлен Docker или Podman, исполняемый файл в PATH. Для вашего рантайма команды завершаются без ошибки и показывают версию. Если Docker работает с реестром через недоверенный сертификат, доверие настроено на уровне Docker daemon.
• С машины shtil есть исходящий доступ к https://r.shturval.tech:443. См. «Машина shtil: доступ к r.shturval.tech» в разделе Команды для проверки (включая диагностику при ошибке: DNS, curl -vI, HTTPS_PROXY / HTTP_PROXY).
• Для install-gui учётная запись может писать в /tmp. См. «Машина shtil: проверка доступа в /tmp (сценарий install-gui)» в разделе Команды для проверки; обе команды завершаются без ошибки доступа.
• Rootless Podman: при запуске shtil не от root — подготовка хоста (user namespaces и делегирование cgroup)

Сеть и адреса #

• Два свободных VIP в подсети Control Plane (если нет внешних балансировщиков KubeAPI и Ingress): выбранные адреса ещё не находятся на интерфейсах узлов до установки. Пример: 10.11.12.100 (API) и 10.11.12.101 (Ingress) — см. требования. Дополнительная проверка сети — «Проверка, что виртуальные IP-адреса свободны» в разделе Команды для проверки.
• Внешний балансировщик для Ingress и/или KubeAPI (если вы не используете два свободных VIP на узлах): сеть и точки входа согласованы с вашей инфраструктурой. Требования — в разделе Внешний балансировщик нагрузки.
• Ресурсы и число узлов соответствуют сценарию (минимум / production). Сверьте с разделом Работа с провайдерами выше и с требованиями. Если конфигурация слабее требований: увеличьте vCPU / RAM / диск узлов или число узлов по таблицам в требованиях и повторите планирование до запуска установки.
• Работа с провайдерами — прочитано, как устроены провайдеры в платформе.
• Провайдер Shturval v2 — если выбран этот провайдер, созданы физические или виртуальные хосты будущего кластера, настроены SSH-ключ без passphrase и sudo без пароля (см. Shturval v2).
• Провайдер oVirt и подобные, VMware vSphere или OpenStack и подобные — если выбран один из этих провайдеров, подготовлена виртуализация или облако и создан шаблон ВМ провайдера; подробности: oVirt и подобные, VMware vSphere, OpenStack, VK Cloud, Selectel.

На узлах кластера управления #

• SELinux — режим permissive или disabled, либо политика, согласованная с ИБ. См. «Проверка, что SELinux отключен или permissive (если дистрибутив с SELinux)» в разделе Команды для проверки (на дистрибутивах без SELinux пункт неприменим).
• Время на узлах согласовано с машиной shtil, NTP в норме. См. «Узел: время и NTP» в разделе Команды для проверки: в timedatectl есть признак синхронизации (формулировка зависит от ОС); при Chrony — разумный вывод chronyc tracking; расхождение date между узлом и shtil не больше типичного для вашей сети (минуты и больше — риск для сертификатов и etcd). При сбоях — Диагностика.
• Репозитории ОС не срывают установку (недоступные родные зеркала лучше отключить). См. «Узел: репозитории пакетов (одна команда под вашу ОС)» в разделе Команды для проверки; ошибок из‑за недоступных репозиториев быть не должно. Для типовой установки обычно нужны пакеты вроде iptables, gnupg (уточните по дистрибутиву).
• С узла есть доступ к r.shturval.tech:443. См. «Узел: исходящий доступ к r.shturval.tech» в разделе Команды для проверки (локально на узле или через SSH с shtil).
• Провайдер Shturval v2: SSH по ключу без passphrase и sudo без пароля. См. подраздел «Провайдер Shturval v2» в разделе Работа с провайдерами: вход по ключу без запроса passphrase; sudo -n true завершается с кодом 0.

После установки кластера (напоминание) #

• NTP и часовой пояс при необходимости донастроены: мастер инсталляции NTP на узлах не задаёт; по умолчанию часто Europe/Moscow. Настройка через NCI; контроль — командами из «После установки кластера: время (при необходимости)» в разделе Команды для проверки.

Дальнейшие действия — выбор сценария и команды на странице Процесс установки:

• с GUI — install-gui, затем мастер установки в браузере;
• с флагами — install-cli и подкоманда провайдера;
• с YAML — install-cli … --yaml-path / -f.