Использование 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 - директория, содержащая общую библиотеку чартов с функциями, используемыми для запроса информации из Talos Linux.
• Chart.yaml - файл, содержащий общую информацию о вашем проекте; имя чарта используется как имя для новосозданного кластера.
• templates - директория, используемая для описания шаблонов генерации конфигурации.
• secrets.yaml - файл, содержащий секреты для вашего кластера.
• secrets.encrypted.yaml, talosconfig.encrypted - зашифрованные аналоги, созданные с помощью talm.key (коммитьте их в git вместо файлов в открытом виде).
• talm.key - локальный для проекта age-ключ, используемый для шифрования/расшифровки. Сделайте его резервную копию: без него зашифрованные файлы невозможно открыть снова.
• values.yaml - общий файл значений, используемый для передачи параметров в шаблонизацию.
• .talm-preset.lock - управляемый программой файл, фиксирующий имя пресета и хэш его содержимого на момент инициализации; используется для отслеживания отклонений пресета после обновления бинарника talm. Коммитьте его в git, чтобы базовая версия была общей для всей команды.
• 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 - re-extract charts/talm/ and other preset-shipped files from the talm binary. --preset is required; --name is not.

• --force - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI).

• --update rewrites preset-shipped files only; your values.yaml, secrets.yaml, templates/, and nodes/ customisations are preserved.

Управление зашифрованными 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

--update re-syncs the vendored charts/talm/ exactly — files that the new library no longer ships (or strays like .DS_Store) are pruned — and advances the preset baseline in .talm-preset.lock.

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, strictCharts among them, so chart drift quietly goes back to being a warning. 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.

Обнаружение дрейфа чартов (Talm v0.32+)

Команды рендеринга читают локальную копию проекта charts/talm/, а не встроенные чарты бинарника, поэтому обновление бинарника talm не затрагивает ваш проект — зависшая копия чарта молча устаревает. Релизные сборки talm обнаруживают это и выводят нефатальную строку WARN: в stderr для двух независимых сигналов:

• Дрейф библиотеки: зависшая копия charts/talm/ отличается по содержимому от копии, встроенной в бинарник. Чисто версионное расхождение штампа остаётся немым; реальное различие сообщается с выборкой различающихся путей (modified: / extra: / missing:).
• Дрейф пресета: бинарник поставляется с более новым пресетом, чем базовая линия, зафиксированная в .talm-preset.lock на момент инициализации. Ваши правки в templates/ никогда не сообщаются как дрейф — сравнение идёт бинарник-против-базовой-линии, а не бинарник-против-проекта.

Оба предупреждения указывают на исправление, описанное выше. Чтобы эскалировать предупреждение до жёсткой ошибки (код выхода 1) — например, в CI — установите strictCharts: true в Chart.yaml, чтобы вся команда унаследовала это поведение, или передайте --strict-charts для однократного запуска. В строгом режиме базовая линия, которую невозможно провери

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

В 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.6"
## Подсеть 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* непуст.

Beyond the extra* extension points, the cozystack preset exposes two opinionated tunables you can change without forking the chart:

The five always-on DRBD/LINSTOR sysctls listed in the extraSysctls row above ship unconditionally on the cozystack preset — they address TCP-port exhaustion observed under DRBD reconnect storms and have no equivalent on the generic preset.

Describing the node’s network and registries from values (Talm v0.34+)

The extra* keys above add to the preset’s curated defaults. A second group of keys describes parts of the config the preset used to leave to the template — so a topology that once required forking templates/_helpers.tpl is now expressible in values.yaml. Both presets accept all of them.

Example:

timeServers:
  - time.cloudflare.com
extraApiServerArgs:
  max-requests-inflight: "2000"
registryMirrors:
  ghcr.io:
    endpoints:
      - https://mirror.example.com
registryTLS:
  mirror.example.com:
    insecureSkipVerify: true
vips:
  - link: bond1
    ip: 192.0.2.254

Every key defaults empty, so a config that sets none of them renders exactly as before.

Declaring links with network.extraLinks

On a node that already carries its topology, nothing needs declaring: discovery reconstructs each link — including bond members, tuning, MTU and VLAN children — into typed documents on its own. network.extraLinks is for what the node does not carry yet.

An entry with addresses or a bond declares a new link; an entry with only vlans hangs VLANs off a link that already exists. Both an entry and each of its vlans children accept mtu and routes (a route needs a gateway; omit destination for a default route):

network:
  extraLinks:
    - interface: bond0
      mtu: 9000
      bond:
        interfaces: [enp3s0, enp4s0]
        mode: 802.3ad
        xmitHashPolicy: layer2+3
        lacpRate: slow
        miimon: 100
      addresses: [192.0.2.10/24]
      routes:
        - gateway: 192.0.2.1
      vlans:
        - vlanId: 100
          addresses: [198.51.100.10/24]

A link named in bond.interfaces becomes a slave and gets no document of its own — the same filter discovery applies once the bond exists. Moving an already-addressed NIC into a bond therefore has to say where its addressing goes: a slave carrying addresses needs addresses on the bond entry, and one carrying the default route needs a routes entry there too. Miss either and the render stops, naming the addresses and the gateway to restate, rather than handing the node a config that leaves it unreachable.

Inputs Talos would reject are refused at render time, where the message can name the offending document: a bond with no mode or an unknown one, a VLAN on a parent that exists nowhere, a vlanId outside 1-4094 or with a fractional part, an address or route destination whose prefix does not parse, an mtu outside the kernel’s 68-65535 range, and an address that is also a declared VIP — that one belongs to its Layer2VIPConfig, and pinning it statically as well puts the leader and its followers out of sync.

2.3 Add Keycloak Configuration

По умолчанию кластер будет доступен только при аутентификации с помощью токена. Однако можно настроить 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"
  

2.4 Зашифрованные пользовательские значения и скрытие секретов (Talm v0.32+)

Помимо secrets.yaml (секретов начальной загрузки Talos), шаблоны часто внедряют в конфигурацию секреты, предоставленные оператором - пароль реестра, секрет клиента OIDC, значение переменной окружения статического pod-а. Talm позволяет хранить их в git в зашифрованном виде так же, как secrets.yaml, расшифровывать их в памяти во время рендеринга и не допускать их попадания в закоммиченные файлы узлов, вывод терминала и логи CI.

Шаг 1 - поместите значения секретов в values-secret.yaml:

registryPassword: "s3cr3t-high-entropy-value"

Шаг 2 - зашифруйте его с помощью talm.key проекта. talm init --encrypt создаёт values-secret.encrypted.yaml. Закоммитьте зашифрованный файл; незашифрованный values-secret.yaml игнорируется git.

Шаг 3 - сошлитесь на зашифрованный файл из Chart.yaml, добавив его в templateOptions.valueFiles, чтобы и talm template, и talm apply могли его прочитать:

templateOptions:
  valueFiles:
    - values-secret.encrypted.yaml

Ссылаться на него только через флаг CLI --values - это грабли: modeline в файле узла не сохраняет файлы значений, поэтому последующий talm apply перерендерит конфигурацию БЕЗ секрета и незаметно отбросит поле. Talm выводит предупреждение, если зашифрованный файл передан через --values, но не указан в templateOptions.valueFiles.

Шаг 4 - используйте значения в шаблонах как любые другие: {{ .Values.registryPassword | quote }}.

Как секреты обрабатываются в разных командах:

Флаг --show-secrets-in-drift управляет каждой поверхностью apply dry-run, содержащей секреты, охватывая как эти пользовательские значения, так и материал начальной загрузки Talos (cluster.ca.key, machine.token, секреты шифрования, ключи Wireguard и т.д.). По умолчанию dry-run никогда не выводит закрытый ключ CA или пользовательский секрет в открытом виде.

talm apply учитывает полный набор источников значений, соответствуя talm template: --values, --set, --set-string, --set-file, --set-json, --set-literal, объединённые поверх значений по умолчанию templateOptions.* из Chart.yaml. Это обеспечивает идентичность рендеринга template и apply.

Осторожно - сопоставление по значению. Скрытие секретов работает через точное сопоставление значения по всему отрендеренному конфигу, поэтому секрет, чей открытый текст совпадает с обычной структурной строкой (пароль, буквально равный controlplane, или обычный порт вроде 6443), также скроет это несвязанное поле. Предпочитайте значения с высокой энтропией; не шифруйте строки с низкой энтропией, совпадающие с несекретной конфигурацией.

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.