Использование Talm для инициализации кластера Cozystack

В этом руководстве описано, как установить и настроить Kubernetes в кластере Talos Linux с помощью Talm. После выполнения этого руководства у вас будет кластер Kubernetes, готовый к установке Cozystack.

Talm — Helm-подобная утилита для декларативного управления конфигурацией Talos Linux. Talm был создан Ænix, чтобы сделать конфигурации управления кластером более декларативными и настраиваемыми. Talm поставляется с готовыми пресетами для Cozystack.

Предварительные требования

К началу работы с этим руководством Talos Linux должен быть установлен на нескольких узлах, но еще не инициализирован (bootstrapped). Эти узлы должны находиться в одной подсети или иметь публичные IP-адреса.

В руководстве используется пример, где узлы кластера находятся в подсети 192.168.123.0/24 и имеют следующие IP-адреса:

• node1: private 192.168.123.11 or public 12.34.56.101.
• node2: private 192.168.123.12 or public 12.34.56.102.
• node3: private 192.168.123.13 or public 12.34.56.103.

Публичные IP-адреса необязательны. Для установки с Talm нужен только доступ к узлам: напрямую, через VPN, bastion host или другим способом. В примерах этого руководства по умолчанию используются private IP, а public IP используются в инструкциях и примерах, относящихся к конфигурации с public IP.

Если вы используете DHCP, вы можете не знать IP-адреса, назначенные узлам в private subnet. Узлы с Talos Linux открывают Talos API на порту 50000. Чтобы найти их, можно использовать nmap, указав маску сети (192.168.123.0/24 в примере):

nmap -Pn -n -p 50000 192.168.123.0/24 -vv | grep 'Discovered'

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

Discovered open port 50000/tcp on 192.168.123.11
Discovered open port 50000/tcp on 192.168.123.12
Discovered open port 50000/tcp on 192.168.123.13

1. Установка зависимостей

Для этого руководства нужно установить несколько инструментов:

• Talm. Чтобы установить последнюю сборку для вашей платформы, скачайте и запустите установочный скрипт:

  curl -sSL https://github.com/cozystack/talm/raw/refs/heads/main/hack/install.sh | sh -s
  

  Для Talm доступны бинарные файлы для Linux, macOS и Windows, как для AMD, так и для ARM. Также можно скачать бинарный файл с GitHub или собрать Talm из исходного кода.

• talosctl распространяется как brew package:

  brew install siderolabs/tap/talosctl
  

  Другие варианты установки см. в руководстве по установке talosctl

2. Инициализация конфигурации кластера

Первый шаг — инициализировать шаблоны конфигурации и указать значения для шаблонизации.

2.1 Инициализация конфигурации

Начните с инициализации конфигурации для нового кластера, используя preset cozystack:

mkdir -p cozystack-cluster
cd cozystack-cluster
talm init --preset cozystack --name mycluster

Структура проекта в основном повторяет обычный Helm chart:

• charts - каталог с общим library chart, содержащим функции для запроса информации из Talos Linux.
• Chart.yaml - файл с общей информацией о проекте; имя chart используется как имя создаваемого кластера.
• templates - каталог для описания шаблонов генерации конфигурации.
• secrets.yaml - файл с secrets вашего кластера.
• secrets.encrypted.yaml, talosconfig.encrypted — зашифрованные копии, создаваемые из talm.key (коммитьте в git именно их, а не файлы в открытом виде).
• talm.key — локальный для проекта age-ключ, используемый для шифрования / расшифровки. Сделайте его резервную копию; без него зашифрованные файлы нельзя будет открыть.
• values.yaml - общий values-файл для передачи параметров в шаблоны.
• nodes - необязательный каталог для описания и хранения сгенерированной конфигурации узлов.

Доступные пресеты

talm поставляется с двумя встроенными пресетами:

• cozystack — production-пресет, используемый в этом руководстве.
• talm — минимальный library chart для продвинутых пользователей, желающих построить собственный пресет поверх него.

Имя пресета передаётся через -p / --preset.

Справочник флагов talm init

Каноничный список см. по talm init -h. Сгруппировано по режимам:

Создание нового проекта (режим по умолчанию):

• -p, --preset <name> — пресет для генерации файлов.
• -N, --name <cluster-name> — имя кластера.
• --endpoints <list> — Talos API endpoints (через запятую), встраиваемые в talosconfig.contexts.<name>.endpoints для клиента talosctl. См. «Флаги endpoint: клиент talosctl против control plane Kubernetes» ниже.
• --cluster-endpoint <url> — URL control-plane Kubernetes, записываемый в values.yaml::endpoint (например, https://<vip>:6443). При init проверяется на наличие scheme + host + port.
• --image <ref> — переопределить образ установщика Talos, записываемый в values.yaml пресета (например, factory.talos.dev/installer/<sha256>:<version>).
• --talos-version <ver> — желаемая contract-версия Talos для шаблонизации с обратной совместимостью (например, v1.12).
• --force — перезаписывать существующие файлы без запроса.

Флаги endpoint: клиент talosctl против control plane Kubernetes

В проектах talm слово «endpoint» обозначает две разные сущности:

• talosconfig.contexts.<name>.endpoints — список записей host[:port], которые клиент talosctl использует для доступа к Talos API. Заполняется флагом --endpoints (множественное число, список через запятую).
• values.yaml::endpoint — один URL со scheme + host + port, который чарт подставляет в cluster.controlPlane.endpoint в MachineConfig каждого узла. Именно к нему обращаются kubelet и kube-proxy. Заполняется флагом --cluster-endpoint (единственное число, полный URL).

Когда --endpoints задан ровно с одним значением, init автоматически выводит values.yaml::endpoint как https://<это>:6443, потому что случай с единственной целью однозначен. При нескольких endpoints автоматический вывод не выполняется (выбор одного узла молча привязал бы доступность кластера к нему) — задайте --cluster-endpoint явно или заполните values.yaml::endpoint позже вручную. В конце init выводит подсказку, если поле осталось пустым.

Обновление существующего проекта до последнего встроенного library chart:

• -u, --update — заново извлечь charts/talm/ и другие файлы пресета из бинарника talm. --preset обязателен; --name — нет.
• --force - auto-accept every preset-template diff, including the Chart.yaml and values.yaml overwrites described below.
• --update rewrites preset-shipped files: charts/talm/ outright, and Chart.yaml, values.yaml and templates/ behind a per-file prompt that --force auto-accepts. Your secrets.yaml and nodes/ are not preset-shipped, so they stay as they are.

Управление зашифрованными secrets на месте:

• -e, --encrypt — зашифровать secrets.yaml / talosconfig / kubeconfig в их .encrypted-копии. Требует talm.key.
• -d, --decrypt — обратная операция. Не требует --preset или --name.

Обновление до новой версии Talm

Когда новая версия talm поставляется с более новым встроенным library chart, обновите проект на месте:

cd cozystack-cluster
talm init --update --preset cozystack          # интерактивно: запрашивает по каждому diff шаблона пресета
talm init --update --preset cozystack --force  # неинтерактивно: автоматически принять все diff

talm v0.35.0 changes what an empty templateOptions.kubernetesVersion means. A Chart.yaml that leaves the key empty still renders while its talosVersion is v1.13 or older, but talm no longer substitutes a Kubernetes version of its own: it emits no image for the kubelet, for kube-proxy or for the control-plane components, so Talos picks those versions itself, and talm prints a warning on stderr saying so. Pin templateOptions.kubernetesVersion in Chart.yaml to the version the cluster actually runs. Do not raise templateOptions.talosVersion above v1.13 to get there: past that contract Talos keeps the Kubernetes settings in documents of their own that v0.35.0’s charts do not emit, and the render stops whether or not kubernetesVersion is pinned — on the cozystack preset a control-plane node stops earlier still, on the preset’s machine.nodeLabels patch, because that label moved out of v1alpha1 at the same contract. Talos versions and output format explains what each key selects.

--update can undo those pins. With --force, or when you accept its prompt for a file, it rewrites Chart.yaml, values.yaml and templates/ from the preset without showing a diff; of Chart.yaml only the chart name survives, and its version is restamped to the talm release you ran. Every other key returns to the preset’s value: the two version pins, valueFiles, the apply timeout, any pinned certFingerprints. A key the preset does not ship at all is dropped outright. values.yaml is reset the same way: an empty endpoint fails the next render, while an empty floatingIP does not — the render simply comes out with no VIP, and a node file regenerated from it carries none either. image goes back to the installer the preset ships (v1.12.6 in talm v0.35.0), also without an error or a warning, and talm upgrade takes its target from values.yaml unless you pass --image: if your nodes run a newer Talos than the preset, the next upgrade downgrades them. Put the pinned image back before that upgrade. Keep both files in git and diff them after every --update.

Цикл шифрования / расшифровки

В git вы коммитите зашифрованные копии, а talm читает копии в открытом виде. Для перехода между ними используйте:

talm init --encrypt   # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> talosconfig.encrypted
talm init --decrypt   # обратная операция — не требует --preset или --name

Если потерять файл talm.key, зашифрованные копии станут нечитаемыми, поэтому храните резервную копию ключа отдельно. Когда talm init --decrypt запускается в проекте без talm.key, talm показывает оба пути восстановления в подсказке ошибки: восстановить сохранённый ключ или заново выполнить talm init для регенерации (с явным предупреждением, что регенерация записывает новые secrets, из-за чего старый secrets.encrypted.yaml нельзя будет расшифровать без исходного ключа).

2.2. Редактирование значений конфигурации и шаблонов

Сила Talm — в шаблонизации. Есть несколько файлов с исходными значениями и шаблонами, которые можно редактировать: Chart.yaml, values.yaml и templates/*. Talm использует эти значения и шаблоны для генерации конфигурации Talos для всех узлов кластера: и control plane, и workers.

Все часто изменяемые значения конфигурации находятся в values.yaml:

## Используется для доступа к control plane кластера
endpoint: "https://192.168.100.10:6443"
## Домен кластера Cozystack API — используется сервисами и K8s-кластерами tenant'ов для доступа к управляющему кластеру
clusterDomain: cozy.local
## Floating IP — должен быть неиспользуемым IP-адресом в той же подсети, что и узлы
floatingIP: 192.168.100.10
## Исходный образ Talos: используйте последнюю доступную версию
## https://github.com/cozystack/cozystack/pkgs/container/cozystack%2Ftalos
image: "ghcr.io/cozystack/cozystack/talos:v1.13.0"
## Подсеть Pod'ов — используется для назначения IP-адресов pod'ам
podSubnets:
- 10.244.0.0/16
## Подсеть сервисов — используется для назначения IP-адресов сервисам
serviceSubnets:
- 10.96.0.0/16
## Подсеть с IP-адресами узлов
advertisedSubnets:
- 192.168.100.0/24
## Добавьте URL OIDC issuer, чтобы включить OIDC — см. комментарии ниже.
oidcIssuerUrl: ""
certSANs: []

На этом шаге не нужно указывать IP-адреса узлов. Вы укажете их позже, при генерации конфигураций узлов.

Расширение формируемой конфигурации Talos (Talm v0.30+)

Пресет cozystack поставляется с подобранными значениями по умолчанию для machine.kernel.modules, machine.sysctls, machine.kubelet.extraConfig и machine.files. Операторам, желающим дополнить любой из них без форка чарта, доступны четыре ключа values extra*:

Пример дополнения values.yaml:

extraKernelModules:
  - name: nf_conntrack
extraKubeletExtraArgs:
  feature-gates: "NodeSwap=true"
extraSysctls:
  net.core.somaxconn: "65535"
extraMachineFiles:
  - path: /etc/example.conf
    op: create
    content: "hello = world"

Пресет generic не поставляет значений по умолчанию ни в одной из этих секций — каждый блок формируется только когда соответствующий ключ extra* непуст.

Помимо точек расширения extra*, пресет cozystack предоставляет два преднастроенных параметра, которые можно менять без форка чарта:

Пять всегда включённых sysctls DRBD/LINSTOR, перечисленных в строке extraSysctls выше, поставляются безусловно в пресете cozystack — они устраняют исчерпание TCP-портов, наблюдаемое при штормах переподключений DRBD, и не имеют аналога в пресете generic.

2.3 Добавление конфигурации Keycloak

По умолчанию кластер будет доступен только при аутентификации с помощью токена. Однако можно настроить OIDC-провайдера, чтобы использовать аутентификацию на основе учётных записей. Эта настройка начинается на данном шаге и продолжается позже, после установки Cozystack.

Чтобы настроить Keycloak как OIDC-провайдера, внесите следующие изменения в шаблоны:

• Для Talm v0.6.6 или новее: в ./templates/_helpers.tpl замените keycloak.example.com на keycloak.<your-domain.tld>.

• Для Talm старше v0.6.6 обновите ./templates/_helpers.tpl следующим образом:

   cluster:
     apiServer:
       extraArgs:
         oidc-issuer-url: "https://keycloak.example.com/realms/cozy"
         oidc-client-id: "kubernetes"
         oidc-username-claim: "preferred_username"
         oidc-groups-claim: "groups"
  

3. Генерация конфигурационных файлов узлов

Следующий шаг — создать конфигурационные файлы узлов из шаблонов. Создайте каталог nodes и соберите информацию с каждого узла в отдельный файл для этого узла:

mkdir nodes
talm template -e 192.168.123.11 --nodes 192.168.123.11 -t templates/controlplane.yaml -i > nodes/node1.yaml
talm template -e 192.168.123.12 --nodes 192.168.123.12 -t templates/controlplane.yaml -i > nodes/node2.yaml
talm template -e 192.168.123.13 --nodes 192.168.123.13 -t templates/controlplane.yaml -i > nodes/node3.yaml

Параметр --insecure (-i) нужен потому, что Talm должен получить конфигурационные данные с узлов Talos, которые еще не инициализированы, находятся в maintenance mode и поэтому не могут принять аутентифицированное соединение. Узлы будут инициализированы только на следующем шаге с помощью talm apply.

Сгенерированные файлы содержат блок комментариев с обнаруженными сетевыми интерфейсами и дисками. Эти файлы можно отредактировать перед применением, чтобы настроить сетевую конфигурацию. Например, если нужно настроить network bonding (LACP), см. Настройка bonding (LACP).

4. Применение конфигурации и инициализация кластера

На этом этапе конфигурационные файлы в node/*.yaml готовы к применению на узлах.

4.1 Применение конфигурационных файлов

Используйте talm apply, чтобы применить конфигурационные файлы к соответствующим узлам:

talm apply -f nodes/node1.yaml -i
talm apply -f nodes/node2.yaml -i
talm apply -f nodes/node3.yaml -i

Эта команда инициализирует узлы и настраивает аутентифицированное соединение, поэтому дальше -i (--insecure) не потребуется. Если команда выполнена успешно, она вернет IP узла:

$ talm apply -f nodes/node1.yaml -i
- talm: file=nodes/node1.yaml, nodes=[192.168.123.11], endpoints=[192.168.123.11]

Позже с talm apply также можно использовать следующие опции:

• --dry-run - dry run mode покажет diff с существующей конфигурацией без внесения изменений.
• -m try - try mode откатит конфигурацию через 1 минуту.

4.2 Ожидание перезагрузки

Дождитесь, пока все узлы перезагрузятся. Если использовался установочный носитель, например USB-накопитель, извлеките его, чтобы узлы загрузились с внутреннего диска.

Когда узлы будут готовы, они откроют порт 50000; это признак того, что узел завершил настройку Talos и перезагрузился. Если нужно автоматизировать проверку готовности узлов, используйте такой пример:

timeout 60 sh -c 'until \
  nc -nzv 192.168.123.11 50000 && \
  nc -nzv 192.168.123.12 50000 && \
  nc -nzv 192.168.123.13 50000; \
  do sleep 1; done'

4.3. Инициализация Kubernetes

Инициализируйте кластер Kubernetes, выполнив talm bootstrap для одного из узлов control plane:

talm bootstrap -f nodes/node1.yaml

5. Доступ к кластеру Kubernetes

На этом этапе кластер Kubernetes готов к установке Cozystack.

До этого шага взаимодействие с кластером выполнялось через Talos API и talosctl. Для следующих шагов нужны Kubernetes API и kubectl, которым требуется kubeconfig.

5.1. Получение kubeconfig

Используйте Talm, чтобы сгенерировать административный kubeconfig:

talm kubeconfig -f nodes/node1.yaml

Эта команда создаст файл kubeconfig в текущем каталоге.

5.2. Изменение URL Cluster API

Теперь в kubeconfig URL Cluster API указывает на floating IP (VIP) в private subnet.

Если вместо floatingIP используется public IP, обновите endpoint соответствующим образом. Отредактируйте kubeconfig — замените URL кластера на public IP одного из узлов:

  apiVersion: v1                                                                                                          
  clusters:                                                                                                               
  - cluster:     
      certificate-authority-data: ...                                                                                                         
-     server: https://10.0.1.101:6443   
+     server: https://12.34.56.101:6443   

5.3. Активация kubeconfig

Затем настройте переменную KUBECONFIG или используйте другие инструменты, чтобы сделать этот kubeconfig доступным вашему клиенту kubectl:

export KUBECONFIG=$PWD/kubeconfig

5.4. Проверка доступности кластера

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

kubectl get ns

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

NAME              STATUS   AGE
default           Active   7m56s
kube-node-lease   Active   7m56s
kube-public       Active   7m56s
kube-system       Active   7m56s

5.5. Проверка состояния узлов

Проверьте состояние узлов кластера:

kubectl get nodes    

Вывод показывает состояние узлов и версию Kubernetes:

NAME    STATUS     ROLES           AGE     VERSION
node1   NotReady   control-plane   7m56s   v1.33.1
node2   NotReady   control-plane   7m56s   v1.33.1
node3   NotReady   control-plane   7m56s   v1.33.1

Обратите внимание, что все узлы показывают STATUS: NotReady, и на этом этапе это нормально. Так происходит потому, что стандартный CNI-плагин Kubernetes был отключен в конфигурации Talos, чтобы Cozystack мог установить собственный CNI-плагин.

Следующие шаги

Теперь у вас есть инициализированный кластер Kubernetes, готовый к установке Cozystack. Чтобы завершить установку, следуйте руководству по развертыванию, начиная с раздела Установка Cozystack.