Руководство по установке

На этой странице рассказано, как развернуть кластер Yandex Cloud Stackland на заранее подготовленной инфраструктуре.

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

ИнфраструктураИнфраструктура

Для развертывания Stackland вам понадобится минимальная инфраструктура:

• 3 сервера или виртуальные машины с 32 vCPU, 64 GB RAM, связанных L2-сетью.
• На каждом из серверов должно быть минимум 2 диска объемом 100 или больше ГБ — один из дисков используется для установки системы, другой для хранения данных. На control-plane-серверах для установки системы должен использоваться SSD.
• Компьютер или джамп-хост, с которого будет производиться доступ к кластеру.
• У серверов должна быть возможность синхронизировать время, желательно локальный NTP или NTP-сервер в интернете.

Сервера Stackland могут иметь одну из трех ролей:

• control-plane — управляющий сервер, на котором развернуты ключевые компоненты Stackland;
• worker — сервер для выполнения пользовательской нагрузки;
• combined — сервер, который совмещает функции control-plane и worker.

В небольших кластерах (до трех узлов) рекомендуется использовать роль combined, которая позволяет запускать пользовательские нагрузки на управляющих серверах. Рекомендуется использовать не менее трех узлов с функциями control-plane (роли control-plane или combined) для обеспечения отказоустойчивости кластера и всегда иметь нечетное число таких серверов.

Если кластер разворачивается более чем на 3 серверах, то минимальные ресурсы каждого сервера могут быть снижены до 8 vCPU и 16 ГБ RAM, но суммарное количество ресурсов worker-нод должно быть не меньше 96 vCPU и 192 ГБ RAM.

Сетевые настройкиСетевые настройки

Сервера Stackland должны находиться в одном L2-домене. Хостам может быть назначен один (предпочтительно) или несколько IP-диапазонов, и со стороны инфраструктуры должна быть обеспечена доставка трафика до этих диапазонов (поднят анонс BGP, OSPF, статическая маршрутизация и т.п.).

Определите диапазон адресов, из которого будут назначаться адреса балансировщиков. Он не должен пересекаться ни с какими другими диапазонами в конфигурационном файле. Это можно обеспечить, разделив диапазон, выделенный хостам кластера, пополам. Например, если кластеру выделен диапазон 192.168.1.0/24, его нижняя половина (192.168.1.0/25) может быть отведена для IP-адресов хостов, а верхняя (192.168.1.128/25) — предназначена для сетевых балансировщиков. Можно также использовать для адресов балансировщиков отдельную подсеть (192.168.2.0/24).

Настоятельно рекомендуется назначить один из IP-адресов хостового диапазона как виртуальный IP-адрес для API-сервера Kubernetes. Этот IP-адрес не должен быть назначен ни одному хосту и не должен находиться в диапазоне, назначенном сетевым балансировщикам. Stackland гарантирует, что API Kubernetes будет доступно по указанному адресу, даже если часть control-plane-серверов временно недоступна.

IP-адреса хостов кластера могут назначаться статически либо по DHCP, но в любом случае они должны быть стабильными, т.е. не меняться в ходе установки Stackland и в процессе эксплуатации кластера. Подготовьте также MAC-адреса сетевых интерфейсов серверов, на которых скоммутирована хостовая сеть: они понадобятся вам при создании конфигурационного файла кластера.

Помимо диапазонов, используемых в физической (хостовой) сети, Stackland также использует несколько виртуальных IPv4-диапазонов, из которых выделяются адреса для подов и сервисов Kubernetes. Эти диапазоны могут быть любыми из списка RFC1918, рекомендуем выбрать широкие (/16 или /12) и непересекающиеся с диапазонами, используемыми в хостовой сети.

DNSDNS

DNS-зона $cluster.$baseDomain должна быть делегирована на хосты с ролью control-plane или combined (см. блок hosts: конфигурации).

Если у вас нет возможности делегировать зону, то вы можете использовать wildcard-записи или указать нужные записи по отдельности.

Следующие FQDN должны указывать:

• api.sys.$cluster.$baseDomain — на виртуальный IP-адрес API Kubernetes ($virtualIPs.$api). Если же и это невозможно, то на IP-адреса нод из секции hosts с ролью control-plane или combined.
• *.sys.$cluster.$baseDomain — на первый IP-адрес диапазона, из которого назначаются адреса балансировщиков.

Если у вас нет возможности использовать wildcard, то на первый IP-адрес диапазона, из которого назначаются адреса балансировщиков, должны указывать следующие FQDN:

• alertmanager.sys.$cluster.$baseDomain
• auth.sys.$cluster.$baseDomain
• console.sys.$cluster.$baseDomain
• dashboard.sys.$cluster.$baseDomain
• grafana.sys.$cluster.$baseDomain
• prometheus.sys.$cluster.$baseDomain
• storage.sys.$cluster.$baseDomain

Начальная конфигурацияНачальная конфигурация

Перед установкой Stackland нужно описать инфраструктуру будущего кластера в конфигурационных файлах. Конфигурационные файлы Stackland используют формат YAML и синтаксис ресурсов Kubernetes. Конфигурацию можно сохранить в одном или нескольких файлах — инсталлятор автоматически загружает все файлы, оканчивающиеся на .yml или .yaml, из указанной папки. Чтобы объединить несколько ресурсов в одном конфигурационном файле, используйте --- в качестве разделителя. Рекомендуется сохранять каждый ресурс в отдельном файле: это упрощает управление конфигурацией и отслеживание изменений.

Независимо от фактического распределения по файлам, конфигурация Stackland состоит из трех частей:

• Конфигурация кластера (ресурс StacklandClusterConfig) — содержит общие настройки кластера: домен, сетевые диапазоны, параметры платформы и балансировщика нагрузки.
• Конфигурация хостов (ресурс StacklandHostsList) — содержит описание серверов кластера: имена хостов, роли, а также настройки, специфичные для конкретных узлов.
• Секреты (ресурс StacklandSecretsConfig) — содержит секреты, такие как лицензионный ключ или сертификат внутреннего CA. Управление этим ресурсом происходит с помощью команды sladm secrets.

Пример файла конфигурации (для простоты все ресурсы объединены в одном файле):

# Конфигурация может быть разделена на несколько файлов.
# Ниже приведен пример с четырьмя документами (включая секреты) в одном файле.
# Это сделано для наглядности, при реальном развертывании рекомендуется разнести документы по файлам.

# Конфигурация кластера
apiVersion: v1alpha1
kind: StacklandClusterConfig
metadata:
  name: main
spec:
  platform:
    type: "baremetal"                            # Платформа, на которой происходит развертывание: "baremetal" для физических серверов или "vmware" для виртуализации VMware
    loadBalancer:
      type: "cilium-l2"                          # Тип балансировщика. В настоящий момент доступен только "cilium-l2" (L2-анонсы Cilium)
      ipPools:
        - cidrs:
          - 192.168.23.128/25                    # Диапазон, из которого будут назначаться адреса балансировщиков, может быть задан в CIDR-нотации...
#        - ranges:
#          - start: 192.168.24.10                # ...или в форме первого и последнего адреса (включительно)
#            end: 192.168.24.12

  cluster:
    baseDomain: "stackland.internal"             # Обязательно. Домен кластера.

    networking:
      hostsNetwork:
        - cidr: 192.168.23.0/25                  # Обязательно. Подсеть, в которой находятся IP-адреса хостов кластера.
      clusterNetwork:
        - cidr: 172.16.0.0/16                    # Обязательно. Подсеть, из которой выделяются IP-адреса подов кластера.
      servicesNetwork:
        - cidr: 10.96.0.0/12                     # Обязательно. Подсеть, из которой выделяются IP-адреса сервисов кластера.
      virtualIPs:
        api: 192.168.23.127                      # Необязательно, но настоятельно рекомендуется. Виртуальный IP-адрес, который назначается одной из работоспособных нод control-plane, и переносится на другую ноду при возникновении неполадок. Выберите любой незанятый IP-адрес из диапазона hostsNetwork.

    storage:
      defaultStorageClass: "stackland-other"     # Обязательно. Класс хранения по умолчанию: "stackland-hdd", "stackland-ssd", "stackland-nvme" или "stackland-other". В указанном классе хранения обязательно должны быть диски, иначе кластер не развернется.

  genericHostConfig:                           # Общие настройки для всех хостов кластера. Могут быть переопределены для отдельных хостов в StacklandHostsList.

    disksConfig:                               # Настройки дисков. Все приведенные параметры также поддерживаются на уровне отдельных хостов в StacklandHostsList.
      - installDisk:
          name: "/dev/sda"                     # Обязательно. Диск, на который будет устанавливаться система.

    networkConfig:                             # Настройки сети. Все приведенные параметры также поддерживаются на уровне отдельных хостов в StacklandHostsList.
      routes:                                  # Необязательно. Настройки статических маршрутов.
        - to: 0.0.0.0/0                        # Обязательно. IPv4 CIDR.
          via: "192.168.23.1"                  # Необязательно. Если не указано, маршрут доступен напрямую.
          iface: "eth0"                        # Обязательно. Имя интерфейса, для которого указывается маршрут.
      resolvers:
        - 192.168.23.1                         # Необязательно. IP-адрес DNS-резолвера, который следует использовать на узлах сервера.
      timeservers:
        - 192.168.23.1                         # IP-адрес сервера времени (NTP). Необязателен, если кластер Stackland имеет доступ в интернет. В противном случае укажите адрес внутреннего NTP-сервера.

#    genericHostConfigByRole:                    # Общие настройки, которые будут применены к хостам конкретной роли. Могут быть переопределены для отдельных хостов в StacklandHostsList. Не может использоваться одновременно с genericHostConfig.
#      controlPlane: {...}
#      worker: {...}
#      combined: {...}
---
# Конфигурация control-plane хостов
apiVersion: v1alpha1
kind: StacklandHostsList
metadata:
  name: control-plane
spec:
  hosts:                                         # Настройки хостов, на которых будет размещаться кластер.

    - hostname: "cp1.stackland.internal"         # Обязательно. FQDN хоста. Если у хоста есть только адреса, назначаемые по DHCP, имя должно быть разрешимо в момент развертывания кластера.
      role: "control-plane"                      # Обязательно. Роль хоста: "control-plane", "worker" или "combined".

      networkConfig:
        interfaces:                              # Настройки сетевых интерфейсов. Для машин с единственным интерфейсом блок можно опустить; интерфейсу будет автоматически назначено имя "eth0".
          - macaddress: "f4:52:14:0b:10:a1"      # Обязательно. MAC-адрес сетевого интерфейса, используется в качестве идентификатора интерфейса при поиске.
            name: "eth0"                         # Обязательно. Имя (идентификатор), используемое для ссылки на интерфейс из секции addresses. Может не совпадать с именем сетевого интерфейса, назначаемым ядром Linux (eth0, eno1 и т.п.)
        addresses:                               # Настройки адресов. Для машин с единственным сетевым интерфейсом блок можно опустить, в этом случае подразумевается DHCP на eth0.
          - interface: "eth0"                    # Обязательно. Имя одного из интерфейсов, должно совпадать с назначенным в секции interfaces.
            ip: "192.168.23.2/24"                # Обязательно. IPv4-адрес в формате CIDR, по которому хост будет доступен во время и после установки.
#           dhcp: true                           # Назначать адрес интерфейсу по DHCP. Имеет приоритет над ip: выше.
---
#  Настройки хостов, на которых будет размещаться полезная нагрузка
apiVersion: v1alpha1
kind: StacklandHostsList
metadata:
  name: workers
spec:
  hosts:
    - hostname: "wrk1.stackland.internal"
      role: "worker"

      # Блок networkConfig отсутствует, поскольку на хосте есть единственный сетевой интерфейс, настраиваемый по DHCP, а настройки маршрутов, DNS-резольвера и NTP не отличаются от типовых

    - hostname: "wrk2.stackland.internal"
      role: "worker"

      disksConfig:
        - installDisk:
            name: "/dev/sdc"                     # Переопределяет типовое значение, заданное в `StacklandClusterConfig`

      # Блок networkConfig отсутствует, поскольку на хосте есть единственный сетевой интерфейс, настраиваемый по DHCP, а настройки маршрутов, DNS-резольвера и NTP не отличаются от типовых

      features:                                  # Переопределяет типовое значение, заданное в `StacklandClusterConfig`
        - gpu                                    # На хосте нужно включить поддержку GPU
        - nvlink                                 # На хосте нужно включить поддержку NVLink
---
# Секреты (управление происходит через команду sladm secrets)
apiVersion: v1alpha1
kind: StacklandSecretsConfig
metadata:
  name: main
spec:
#  ...

Перед установкойПеред установкой

У вас должен быть лицензионный ключ, с помощью которого вы получите доступ к необходимым компонентам Stackland. Развертывание Stackland рекомендуется производить с машины, работающей под управлением Ubuntu 22.04 и выше, либо аналогичного по возможностям дистрибутива Linux.

Скачивание необходимых файловСкачивание необходимых файлов

Скачайте инструмент sladm и установочный образ:

wget https://storage.yandexcloud.net/stackland-public/stackland/26.1.0/sladm-26.1.0-linux-amd64.zip
unzip sladm-26.1.0-linux-amd64.zip
chmod +x sladm

wget https://storage.yandexcloud.net/stackland-public/stackland/26.1.0/images/stackland-amd64-26.1.0.iso
wget https://storage.yandexcloud.net/stackland-public/stackland/26.1.0/images/stackland-amd64-26.1.0.iso.sha256
sha256sum -c stackland-amd64-26.1.0.iso.sha256

Подготовка секретовПодготовка секретов

Перед началом установки нужно сгенерировать ресурс StacklandSecretsConfig, содержащий необходимые для установки секреты. Как правило, этот файл хранится отдельно от других конфигурационных файлов и не попадает в систему контроля версий, если она используется для управления конфигурацией. По этой причине ресурс StacklandSecretsConfig обычно сохраняется в отдельном файле, традиционно называемом secrets.yaml.

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

sladm secrets add --out config/secrets.yaml --license-key key.json

Где:

• --out — путь к файлу, в который будет сохранен ресурс StacklandSecretsConfig;
• --license-key — путь к файлу с лицензионным ключом.

В ходе выполнения команды будут, в частности, созданы сертификат и ключ внутреннего удостоверяющего центра (CA), которым подписываются сертификаты сервисов Stackland. Политика СИБ вашей организации может предусматривать аутентификацию межсервисного взаимодействия удостоверяющим центром компании. В этом случае сгенерируйте сертификат и ключ промежуточного удостоверяющего центра (Intermediate CA), подпишите его в удостоверяющем центре вашей организации и передайте в sladm secrets add следующим образом:

sladm secrets add \
  --out config/secrets.yaml \
  --license-key key.json \
  --int-ca-chain ca.crt \
  --int-ca-key ca.key

Здесь под ca.crt и ca.key подразумеваются подписанный сертификат и ключ промежуточного CA. Подробнее про управление сертификатами см. в разделе "Certificate Manager".

Обновить существующий ресурс StacklandSecretsConfig можно командой sladm secrets update, которой следует передать новые лицензионный ключ, сертификат и ключ промежуточного CA в любой комбинации, используя те же флаги, что и в команде sladm secrets add. Например, команда

sladm secrets update config/secrets.yaml \
  --int-ca-chain ca.crt \
  --int-ca-key ca.key

заменит в ресурсе сертификат и ключ промежуточного CA. Флаг --regenerate принудительно пересоздает все секреты, кроме тех, что были указаны явно. Например, команда

sladm secrets update config/secrets.yaml --license-key key.json --regenerate

сгенерирует новые самоподписанные сертификат и ключ промежуточного CA. Используйте --regenerate с осторожностью, чтобы не потерять секреты уже развернутых кластеров.

Предварительная настройка серверовПредварительная настройка серверов

Загрузите ваши серверы из установочного ISO-образа. На экране загрузчика выберите Talos ISO.

Если в хостовой сети кластера не используется DHCP, после загрузки нажмите F3 и перейдите к сетевым настройкам сервера. Заполните поля в соответствии с конфигурацией:

• Hostname: имя хоста, например cp1.stackland.internal
• DNS Servers: <адрес DNS-сервера>, необязательно при первичной настройке.
• Time Servers: <адрес NTP-сервера>, необязательно при первичной настройке.
• Interface: интерфейс, для которого задаются настройки сети, например eth0. Это должен быть интерфейс, MAC-адрес которого указан в конфигурационном файле.
• Mode: Static.
• Addresses: адрес сервера, например 192.168.23.2/24. Этот адрес должен совпадать с installationIP в конфигурационном файле кластера.
• Gateway: адрес шлюза, например 192.168.23.1. Для кластера без доступа в интернет можно указать любой свободный адрес из хостового диапазона.

Аналогично настройте остальные серверы.

Установка кластераУстановка кластера

Установка с доступом в интернетУстановка с доступом в интернет

Установите кластер, используя созданный на прошлых шагах итоговый файл конфигурации:

sladm install --config config/

Где --config — путь к папке с конфигурационными файлами или объединенному конфигурационному файлу.

Перед началом установки команда sladm install выполнит проверку готовности нод и, в случае обнаружения проблем, выведет сообщение об ошибке. Никакие изменения в кластер при этом внесены не будут. Если вы хотите продолжить установку, невзирая на обнаруженные проблемы, используйте флаг --ignore-checks:

sladm install --config config/ --ignore-checks

Проверку также можно выполнить отдельно, не начиная установку Stackland:

sladm validate --config config/

Установка без доступа в интернетУстановка без доступа в интернет

Герметизированная установка Stackland предназначена для изолированных сред без доступа в интернет. Процедура состоит из трех этапов: подготовка артефактов на машине с интернетом, перенос на изолированную машину, развертывание кластера.

Подготовка артефактов на машине с интернетомПодготовка артефактов на машине с интернетом

На машине с доступом в интернет выполните следующие действия:

1. Загрузите образы контейнеров:

   sladm pull \
     --config config/ \
     --image-bundle full
   

   Где:

   • --config — путь к папке с конфигурационными файлами Stackland;
   • --image-bundle — тип пакета образов. Используйте full для полного набора всех необходимых образов.

   Команда создаст папку stackland-26.1.0-full-oci с образами контейнеров в формате OCI. Папка занимает 20-25 ГБ.

   Примечание

   Пакет full содержит только базовые компоненты Stackland. Для загрузки образов отдельно лицензируемых компонентов, таких как SpeechSense, используйте отдельную команду с --image-bundle speechsense. Подробнее см. в разделе Загрузить образы SpeechSense.

2. Подготовьте список файлов для переноса:

   • stackland-26.1.0-full-oci/ — папка с образами контейнеров;
   • config/ — папка с конфигурационными файлами;
   • stackland-26.1.0-amd64.iso — установочный ISO-образ;
   • sladm — инструмент установки.

Перенос артефактов на изолированную машинуПеренос артефактов на изолированную машину

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

• Съемные носители (USB-накопители, внешние диски);
• Защищенные файловые хранилища;
• Изолированные сетевые сегменты с контролируемым доступом.

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

На изолированной машине выполните установку с использованием локального пакета образов:

sladm install \
  --config config/ \
  --image-bundle-folder stackland-26.1.0-full-oci \
  --image-bundle full

Где:

• --config — путь к папке с конфигурационными файлами Stackland;
• --image-bundle-folder — путь к папке с загруженными образами контейнеров;
• --image-bundle — тип пакета образов (должен совпадать с типом, указанным при загрузке).

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

Общие сведения об установкеОбщие сведения об установке

Важно иметь в виду, что Stackland самостоятельно управляет своим инфраструктурным слоем, в частности, операционной системой. В случае, если на серверах, на которые происходит установка Stackland, уже есть операционная система, она будет удалена. В основе Stackland лежит Talos, открытая минималистичная операционная система на базе ядра Linux. Talos не является дистрибутивом Linux в привычном смысле этого слова, и в частности не подразумевает удаленного доступа по SSH или иного интерактивного взаимодействия с администратором. Все необходимые настройки применяются компонентами Stackland автоматически.

Возобновление установкиВозобновление установки

Установку Stackland, завершившуюся неудачей, не обязательно начинать с нуля. После устранения проблемы (например, перезагрузки дефектной ноды или исправления сетевых настроек) ее можно запустить повторно той же командой sladm install. Инсталлятор автоматически определит, на каком этапе произошел сбой, и продолжит процесс с этого места, пропустив уже выполненные шаги.

По умолчанию для процесса установки Stackland установлен таймаут в 1 час. При необходимости переопределите его с помощью флага --installation-timeout:

sladm install --config config/ --installation-timeout 2h

Если процесс установки не завершился за отведенное время, перезапустите его, как описано выше. Для ускорения добавьте --ignore-checks. В большинстве случаев этого достаточно для успешного завершения установки.

По завершении установки в локальном файле, на который указывает переменная окружения $KUBECONFIG (по умолчанию $HOME/.kube/config) будет создан контекст для роли cluster-admin в развернутом кластере. Это роль суперпользователя, обладая которой, можно выполнить любые, в том числе деструктивные операции. Если доступ к файлу kubeconfig на хосте, с которого производится установка, не ограничен, рекомендуется указать альтернативный путь к создаваемому файлу kubeconfig при помощи --kubeconfig-path:

sladm install \
  --config config/ \
  --kubeconfig-path <путь к папке с ограниченными правами доступа>/kubeconfig

По умолчанию, инсталлятор не заменяет существующий файл kubeconfig, а добавляет в него новый контекст с именем admin@$cluster.$baseDomain. Перед выполнением запросов к кластеру, активируйте этот контекст командой kubectl config set-context admin@$cluster.$baseDomain.

В процессе работы инсталлятора будет также создан набор артефактов в папке _out. После развертывания кластера Stackland, сохраните ее содержимое, поскольку оно может потребоваться в дальнейшем при сборе диагностики и анализе возникающих проблем (см. раздел "Диагностика и устранение неполадок").

По завершении установки sladm выведет реквизиты для подключения к кластеру: адрес консоли управления, логин и пароль по умолчанию.

Проверка работы кластераПроверка работы кластера

После развертывания кластера вы можете получить доступ к разным компонентам кластера:

• https://console.sys.$cluster.$baseDomain — консоль управления кластером.
• https://dashboard.sys.$cluster.$baseDomain — дашборд кластера.
• https://grafana.sys.$cluster.$baseDomain — графики кластера в Grafana.
• https://prometheus.sys.$cluster.$baseDomain — метрики кластера в Prometheus.
• https://alertmanager.sys.$cluster.$baseDomain — алерты кластера в Alertmanager.

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

Ошибки при установке и способы их устраненияОшибки при установке и способы их устранения

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

• Загрузите сервер с установочного образа Stackland.
• В появившемся меню выберите пункт Reset Talos installation and return to maintenance mode.
• Дождитесь повторной перезагрузки сервера.
• Убедитесь, что в графе STAGE на дашборде, отображаемом на локальной консоли сервера (см. иллюстрацию), значится Maintenance.

Данный метод сброса сохраняет сетевые настройки, в частности, IP-адрес сервера. Если необходимо изменить их, это можно сделать вручную через меню, доступное по клавише F3 (см. иллюстрацию ниже). Введите требуемую конфигурацию целиком (отредактировать текущие параметры нельзя), после чего перезагрузите сервер.

Альтернативно, можно очистить жесткий диск любым удобным способом, например:

• Загрузить сервер с SystemRescueCd и затереть первые несколько мегабайт при помощи команды dd.
• Удалить диск и пересоздать его заново, если развертывание происходит в виртуальной среде.

Если повторная установка также завершается неудачей, соберите диагностику, как описано в разделе "Диагностика и устранение неполадок" и обратитесь за помощью к разработчику.