docs/talos_install
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: rewrite

Browse Source
This commit is contained in:
shiranui
2026-08-02 17:42:54 +03:00
parent abf3bacb75
commit 04fe026b82
2 changed files with 81 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -2,3 +2,4 @@
examples/images/* examples/images/*
examples/kubeconfig examples/kubeconfig
examples/test-cluster/talosconfig examples/test-cluster/talosconfig
examples/test-cluster/secrets.yaml
README.md
+79 -24
View File
@@ -1,5 +1,40 @@
# Оглавление
- [Введение](#введение)
- [Что такое Talos OS](#что-такое-talos-os)
- [Подготовка к развороту кластера](#подготовка-к-развороту-кластера)
- [Подготовка schematic.yaml для генерации образа](#подготовка-schematicyaml-для-генерации-образа-через-публичныйприватный-image-factory)
- [Отправка schematic.yaml, получение и скачивание образа](#отправка-schematicyaml-в-сторону-image-factory-получение-id-образа-и-скачивание-образа)
- [Подготовка виртуальных машин](#подготовка-виртуальных-машин)
- [Сборка кластера](#сборка-кластера)
- [Генерация конфига кластера](#генерация-конфига-кластера)
- [Патчи machineconfig для узлов кластера](#патчи-machineconfig-для-узлов-кластера)
- [Применение конфигурации к узлам кластера](#применение-конфигурации-к-узлам-кластера)
- [Сброс кластера](#сброс-кластера)
# Введение
## Что такое Talos OS
Talos Linux — минималистичный immutable-дистрибутив, спроектированный исключительно для запуска Kubernetes. Talos не имеет SSH, интерактивного шелла и пакетного менеджера — вся конфигурация узла и управление им происходят декларативно через API (`talosctl`) и файл `machineconfig`.
##### Ключевые особенности в сравнении с классическим разворотом кластера (kubeadm/ansible/kubespray поверх Ubuntu/Debian/RHEL):
- Управление узлом только через API поверх mTLS, нет SSH и шелла - меньшая поверхность атаки
- Конфигурация декларативная (`machineconfig` YAML), применяется атомарно, а не пошагово скриптами/ролями
- Обновления ОС и компонентов кластера (etcd, kubelet, kube-apiserver) атомарные, по схеме A/B, с возможностью отката одной командой
- Дополнительный функционал ОС подключается через System Extensions, встроенные в образ на этапе сборки (см. ниже), а не через установку пакетов после разворота
- Конфигурация - единственный источник истины: узел либо соответствует заданному `machineconfig`, либо нет, что снижает риск конфигурационного дрейфа
Именно из-за этой модели первым шагом идёт сборка кастомного образа через Image Factory: дополнительные компоненты уровня ОС (iscsi, nfs, qemu-guest-agent и т.д.) нельзя доустановить после разворота - они должны быть встроены в образ заранее.
# Подготовка к развороту кластера # Подготовка к развороту кластера
#### Требуемые инструменты
Для выполнения команд из этого документа потребуются установленные `talosctl` ([инструкция по установке](https://www.talos.dev/latest/talos-guides/install/talosctl/)), `kubectl` и `helm`.
##### Про пути в командах:
Все команды в этом документе выполнялись из директории `examples/` - именно там лежат `schematics/`, `patches/`, `test-cluster/`, `images/` и `cilium-values.yaml`. Перед копированием команд нужно перейти в эту директорию (`cd examples`).
## Подготовка schematic.yaml для генерации образа через публичный/приватный Image Factory ## Подготовка schematic.yaml для генерации образа через публичный/приватный Image Factory
```yaml ```yaml
customization: customization:
@@ -19,25 +54,18 @@ customization:
- `siderolabs/qemu-guest-agent` - гостевой агент для виртуальных машин, запущенных в среде QEMU/KVM (тестовый кластер разворачивается в Proxmox VE) - `siderolabs/qemu-guest-agent` - гостевой агент для виртуальных машин, запущенных в среде QEMU/KVM (тестовый кластер разворачивается в Proxmox VE)
- `siderolabs/util-linux-tools` - набор низкоуровневых утилит Linux, нужен для диагностики и для некоторых CSI драйверов - `siderolabs/util-linux-tools` - набор низкоуровневых утилит Linux, нужен для диагностики и для некоторых CSI драйверов
## Отправка schematic.yaml в сторону Image Fabric, получение ID образа и скачивание образа ## Отправка schematic.yaml в сторону Image Factory, получение ID образа и скачивание образа
#### Следующая команда отправляет файл в сторону Image Fabric: #### Следующая команда отправляет файл в сторону Image Factory:
`curl -X POST --data-binary @schematics/schematic.yaml https://factory.talos.dev/schematics` `curl -X POST --data-binary @schematics/schematic.yaml https://factory.talos.dev/schematics`
- `--data-binary @schematics/schematic.yaml` - передача файла, в данном случае размещен в директории для удобства, но может быть размещен в корне проекта - `--data-binary @schematics/schematic.yaml` - передача файла; в данном случае файл размещён в директории для удобства, но может быть размещён и в корне проекта
- `https://factory.talos.dev/schematics` - URL публичного Image Fabric - `https://factory.talos.dev/schematics` - URL публичного Image Factory
##### В ответ прилетит JSON с ID образа и информацией об установленных расширениях: ##### В ответ прилетит JSON с ID образа и информацией об установленных расширениях:
```json ```json
{ {
"id": "c0ad57b8eb60094dd2ebed394ae5e9dfb279c7661d6c1de5944ede4c16cbfc9d", "id": "c0ad57b8eb60094dd2ebed394ae5e9dfb279c7661d6c1de5944ede4c16cbfc9d",
"schematic": "customization:\n "schematic": "customization:\n extraKernelArgs:\n - net.ifnames=0\n systemExtensions:\n officialExtensions:\n - siderolabs/iscsi-tools\n - siderolabs/nfs-utils\n - siderolabs/qemu-guest-agent\n - siderolabs/util-linux-tools\n"
extraKernelArgs:\n
- net.ifnames=0\n
systemExtensions:\n
officialExtensions:\n
- siderolabs/iscsi-tools\n
- siderolabs/nfs-utils\n
- siderolabs/qemu-guest-agent\n"
} }
``` ```
@@ -62,7 +90,7 @@ customization:
##### Для воркеров будут закреплены IP: ##### Для воркеров будут закреплены IP:
- `10.255.200.204` - `10.255.200.204`
- `10.255.200.205` - `10.255.200.205`
- `10.255.200,206` - `10.255.200.206`
- `10.255.200.207` - `10.255.200.207`
- `10.255.200.208` - `10.255.200.208`
- `10.255.200.209` - `10.255.200.209`
@@ -77,17 +105,24 @@ customization:
# Сборка кластера # Сборка кластера
Сейчас узлы запущены в maintenance mode из iso образа и для первичной заливки machineconfig нужно в явном виде указать флаг `--insecure` Сейчас узлы запущены в maintenance mode из iso образа и для первичной заливки machineconfig нужно в явном виде указать флаг `--insecure`.
-
##### Про флаг `--insecure`:
Он нужен только для самой первой отправки machineconfig - на этом этапе узел ещё не имеет сертификатов и не может поднять mTLS-соединение с `talosctl`. После применения конфигурации узел переходит в защищённый режим, и все дальнейшие обращения к API идут только по mTLS с использованием сертификата из `talosconfig`.
## Генерация конфига кластера ## Генерация конфига кластера
`talosctl gen config test-cluster https://10.255.200.201:6443 -o ./test-cluster` #### Перед генерацией конфига отдельно генерируем bundle с секретами кластера (сертификаты, токены):
`talosctl gen secrets -o test-cluster/secrets.yaml`
Секреты вынесены в отдельный файл специально: `controlplane.yaml`, `worker.yaml` и `talosconfig` можно пересоздавать сколько угодно раз (например, при смене эндпоинта или структуры патчей) на основе одного и того же `secrets.yaml`, не перевыпуская сертификаты и токены и не теряя доступ к уже развернутому кластеру.
`talosctl gen config test-cluster https://10.255.200.201:6443 -o ./test-cluster --with-secrets test-cluster/secrets.yaml`
- `talosctl gen config` - команда генерации конфига - `talosctl gen config` - команда генерации конфига
- `test-cluster` - имя кластера - `test-cluster` - имя кластера
- `https://10.255.200.201:6443` - эндпоинт, в данном случае первый мастер (может быть адрес/домен балансировщика) - `https://10.255.200.201:6443` - эндпоинт, в данном случае первый мастер (может быть адрес/домен балансировщика)
- `-o ./test-cluster` - сохранение конфигов для доступа к кластеру - `-o ./test-cluster` - сохранение конфигов для доступа к кластеру
- `--with-secrets test-cluster/secrets.yaml` - использовать ранее сгенерированный bundle секретов вместо генерации нового
##### Пример выполнения команды: ##### Пример выполнения команды:
``` ```
@@ -100,6 +135,10 @@ Created test-cluster/talosconfig
- `test-cluster/controlplane.yaml` - конфигурация для мастер узлов - `test-cluster/controlplane.yaml` - конфигурация для мастер узлов
- `test-cluster/worker.yaml` - конфигурация для воркер узлов - `test-cluster/worker.yaml` - конфигурация для воркер узлов
##### Про хранение секретов:
- `test-cluster/secrets.yaml` - самый чувствительный файл во всей связке: в нём лежат корневые сертификаты и токены, из которых выводится всё остальное (`talosconfig`, machineconfig узлов). Его нужно хранить в надёжном месте (менеджер секретов/зашифрованное хранилище) и не коммитить в git в открытом виде
- `test-cluster/talosconfig` и весь каталог `test-cluster/` также стоит сохранить - без `secrets.yaml` повторная генерация конфига перевыпустит все сертификаты и токены заново, и доступ к уже развернутому кластеру по старому `talosconfig` будет потерян
## Патчи machineconfig для узлов кластера ## Патчи machineconfig для узлов кластера
### Общий патч для установки ОС на диск: ### Общий патч для установки ОС на диск:
```yaml ```yaml
@@ -110,7 +149,7 @@ machine:
``` ```
#### Патч указывает на образ, который будет установлен на диск `/dev/sda` #### Патч указывает на образ, который будет установлен на диск `/dev/sda`
### Общие патчи для мастер и воркер нод с зависимостью от дополнительного диска: ### Общие патчи для мастер- и воркер-нод с зависимостью от дополнительного диска:
- #### patch-controlplane.yaml - #### patch-controlplane.yaml
```yaml ```yaml
machine: machine:
@@ -175,12 +214,13 @@ cluster:
proxy: proxy:
disabled: true disabled: true
``` ```
#### В патчах для мастер и воркер нод заданы настройки для: #### В патчах для мастер- и воркер-нод заданы настройки для:
- Kubespan - настройка wireguard mesh сети между узлами кластера - Kubespan - настройка wireguard mesh сети между узлами кластера
- Отключение kube-proxy и установки дефолтного CNI (Flannel) - Отключение kube-proxy и установки дефолтного CNI (Flannel)
- Для нод с доп диском описано монтирование доп диска и проброс его в контейнер kubelet для корректной работы - Для нод с доп диском описано монтирование доп диска и проброс его в контейнер kubelet для корректной работы
- Точка монтирования `/var/lib/longhorn` подготовлена под будущую установку Longhorn CSI; сама установка и настройка Longhorn в этом документе не описывается
### Патч для настроек сети, в качестве примера показан только для одного из мастеров, по аналогии сделаны для всех узлов ### Патч для настроек сети - в качестве примера показан только для одного из мастеров, по аналогии такие патчи сделаны для всех узлов
```yaml ```yaml
machine: machine:
network: network:
@@ -211,19 +251,22 @@ talosctl apply-config \
``` ```
#### Остальные узлы по аналогии, нужно только указать соответствующие узлу и роли патчи #### Остальные узлы по аналогии, нужно только указать соответствующие узлу и роли патчи
#### После применения machineconfig нужно выполинть bootstrap на первом мастере, адрес которого был указан при инициализации конфига #### После применения machineconfig нужно выполнить bootstrap на первом мастере, адрес которого был указан при инициализации конфига
`talosctl bootstrap -n 10.255.200.201 -e 10.255.200.201` `talosctl bootstrap -n 10.255.200.201 -e 10.255.200.201`
#### Проверить, что кластер подает признаки жизни командами #### Проверить, что кластер подает признаки жизни командами
```sh ```sh
talosctl etcd members -n 10.255.200.201 -e 10.255.200.201 talosctl etcd members -n 10.255.200.201 -e 10.255.200.201,10.255.200.202,10.255.200.203
talosctl health -n 10.255.200.201 -e 10.255.200.201 talosctl health -n 10.255.200.201 -e 10.255.200.201,10.255.200.202,10.255.200.203
talosctl get members -n 10.255.200.201 -e 10.255.200.201 talosctl get members -n 10.255.200.201 -e 10.255.200.201,10.255.200.202,10.255.200.203
``` ```
##### Про флаг `-e`:
Указывает конечные точки API Talos, к которым обращается `talosctl`. Для отказоустойчивости стоит перечислять все мастера через запятую (как в примерах выше) либо использовать адрес балансировщика/VIP перед мастерами - тогда потеря одного мастера не блокирует управление кластером.
#### Получить и добавить в переменную kubeconfig: #### Получить и добавить в переменную kubeconfig:
```sh ```sh
talosctl kubeconfig ./kubeconfig -n 10.255.200.201 -e 10.255.200.201 talosctl kubeconfig ./kubeconfig -n 10.255.200.201 -e 10.255.200.201,10.255.200.202,10.255.200.203
export KUBECONFIG=$(pwd)/kubeconfig export KUBECONFIG=$(pwd)/kubeconfig
``` ```
### Установка CNI cilium в кластер через helm ### Установка CNI cilium в кластер через helm
@@ -288,3 +331,15 @@ helm install cilium cilium/cilium --version 1.19.6 --namespace kube-system -f ci
```sh ```sh
kubectl get node kubectl get node
``` ```
## Сброс кластера
##### Внимание: операция необратима и стирает данные на диске узла, включая установленную ОС и все данные приложений (в т.ч. на дисках под Longhorn).
#### Если нужно вернуть узел(ы) обратно в maintenance mode и стереть данные:
```sh
talosctl reset -n 10.255.200.201 -e 10.255.200.201 --graceful=false --reboot
```
- `--graceful=false` - пропустить graceful-выход из etcd/кластера (нужно, если кластер уже неработоспособен)
- `--reboot` - перезагрузить узел после сброса, чтобы он снова загрузился в maintenance mode
Команду нужно выполнить отдельно для каждого узла кластера, который требуется сбросить - за один вызов сбрасывается только узел, указанный в `-n`.