Установка Kubernetes-оркестратора на TrueNAS Scale с помощью k3s: пошаговое руководство | AdminWiki
AdminWiki

Установка Kubernetes-оркестратора на TrueNAS Scale с помощью k3s: пошаговое руководство

15 августа 2026 8 мин. чтения
Содержание статьи

Введение: зачем запускать Kubernetes на TrueNAS Scale с k3s

TrueNAS Scale объединяет отказоустойчивое хранилище ZFS и встроенную поддержку контейнеризации. Добавьте к этому k3s, легковесный дистрибутив Kubernetes от Rancher, и вы получите полноценный домашний кластер для тестирования рабочих нагрузок без покупки дорогого оборудования. k3s потребляет меньше ресурсов, чем полный Kubernetes, при этом сохраняет совместимость с основными API и инструментами: kubectl, Helm, CSI-драйверами.

В этом руководстве разобрана установка k3s на поддерживаемую версию TrueNAS Scale, настройка интеграции с ZFS для персистентных томов и деплой первого приложения. Все шаги проверены на практике. После выполнения инструкции вы получите рабочую основу для запуска контейнеров с постоянным хранилищем и внешним доступом.

  • одиночный Kubernetes-кластер на TrueNAS Scale с узлом в статусе Ready;
  • хранилище ZFS, доступное через CSI и StorageClass;
  • проверенный PVC со статусом Bound;
  • тестовое приложение Nginx с персистентным томом;
  • внешний доступ к приложению через Service типа NodePort.

Сценарий подходит для лабораторных стендов, домашних серверов, тестирования Helm-чартов и небольших непроизводственных нагрузок. TrueNAS Scale при этом остаётся прежде всего системой хранения: обновления, настройки и сторонние компоненты Kubernetes нужно планировать отдельно, а одиночный узел не обеспечивает отказоустойчивость к сбою самого сервера.

Если вы ещё не развернули TrueNAS Scale, начните с базовой настройки TrueNAS. Для понимания работы с приложениями в TrueNAS Scale пригодится руководство по установке приложений.

Требования и подготовка TrueNAS Scale для k3s

Перед установкой k3s убедитесь, что ваше оборудование соответствует минимальным требованиям. Это сэкономит время и предотвратит сбои на этапе запуска.

Аппаратные требования для TrueNAS Scale и k3s

Минимальная конфигурация для TrueNAS Scale с k3s:

  • 2 ядра CPU;
  • 4 ГБ оперативной памяти;
  • 20 ГБ свободного места на системном диске.

Рекомендуемая конфигурация для комфортной работы:

  • 4 ядра CPU;
  • 8 ГБ оперативной памяти и больше;
  • SSD для системного пула.

k3s в базовой конфигурации потребляет примерно 500 МБ RAM. Для сравнения, полный Kubernetes с kube-apiserver, kube-scheduler и etcd требует от 2 ГБ RAM. Фактическое потребление зависит от числа приложений, CSI-драйвера и дополнительных компонентов.

Проверка версии TrueNAS Scale и доступ по SSH

Откройте веб-интерфейс TrueNAS и проверьте версию системы в правом верхнем углу. Используйте поддерживаемую версию TrueNAS Scale и заранее проверьте совместимость с выбранным выпуском k3s. Если версия устарела, выполните обновление по инструкции обновления TrueNAS.

Включите SSH: System Settings -> Services -> SSH. Установите флажок «Start Automatically» и запустите службу. Подключитесь к серверу:

ssh admin@IP_АДРЕС_TRUENAS

Перед установкой создайте резервную копию конфигурации: System Settings -> General -> Save Config. Это позволит быстро восстановить систему при сбое. Не устанавливайте k3s на сервер, если на нём уже работают сервисы, использующие те же порты или сетевые настройки, без предварительной проверки.

Установка и базовая настройка k3s на TrueNAS Scale

Установка k3s на TrueNAS Scale выполняется через официальный скрипт. Он автоматически определяет архитектуру, загружает бинарные файлы и настраивает systemd-службу.

Использование официального скрипта установки k3s

Выполните команду от root:

curl -sfL https://get.k3s.io | sh -s - --disable traefik --write-kubeconfig-mode 644

Разберём флаги:

  • --disable traefik - отключает встроенный ingress-контроллер Traefik. Это экономит ресурсы, если вы планируете использовать другой ingress-контроллер или не нуждаетесь в нём на первом этапе.
  • --write-kubeconfig-mode 644 - устанавливает права 644 на файл kubeconfig, чтобы читать его без sudo.

Проверьте статус службы:

sudo systemctl status k3s

Служба должна быть в состоянии active (running). Если статус failed, перейдите к разделу «Типичные проблемы и их решение». Перед повторной установкой проверьте логи и не запускайте несколько вариантов скрипта с разными параметрами без понимания результата.

Настройка kubectl для управления кластером

k3s создаёт kubeconfig в файле /etc/rancher/k3s/k3s.yaml. Скопируйте его на рабочую станцию:

scp admin@IP_АДРЕС_TRUENAS:/etc/rancher/k3s/k3s.yaml ~/.kube/config-truenas

Установите переменную окружения:

export KUBECONFIG=~/.kube/config-truenas

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

kubectl get nodes

Вывод покажет один узел с именем вашего TrueNAS-сервера в статусе Ready. Если kubeconfig был скопирован на другую машину, проверьте, что адрес API-сервера в файле доступен с этой рабочей станции.

Интеграция k3s с хранилищем ZFS

По умолчанию k3s использует local-path provisioner, который создаёт тома на локальном диске. Для ZFS нужен CSI-драйвер, который умеет создавать dataset и управлять ими динамически.

Установка CSI-драйвера для ZFS

Проект democratic-csi поддерживает ZFS и работает с TrueNAS Scale. Установите его через Helm:

helm repo add democratic-csi https://democratic-csi.github.io/charts/
helm repo update
helm install zfs-nfs democratic-csi/democratic-csi --namespace democratic-csi --create-namespace

После установки проверьте, что компоненты CSI запущены:

kubectl get pods -n democratic-csi

Альтернатива - zfs-localpv от OpenEBS. Он проще в настройке, но менее гибок при работе с NFS. Для любого варианта заранее определите dataset, сетевой адрес TrueNAS и права доступа к хранилищу.

Создание StorageClass и проверка PVC

Создайте StorageClass для ZFS. Пример манифеста:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: zfs-nfs
provisioner: org.democratic-csi.nfs
parameters:
  server: IP_АДРЕС_TRUENAS
  share: /mnt/ваш_пул/ваш_dataset
  mountPermissions: "0777"
reclaimPolicy: Delete
volumeBindingMode: Immediate

Примените манифест:

kubectl apply -f storageclass.yaml

Создайте тестовый PVC:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  storageClassName: zfs-nfs
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Проверьте статус PVC:

kubectl get pvc

Статус должен быть Bound. Это значит, что CSI-драйвер создал dataset в ZFS и привязал его к PVC. Если PVC остаётся в статусе pending PVC, проверьте имя StorageClass, состояние CSI-компонентов и доступность сетевого ресурса.

Развертывание первого приложения в Kubernetes-кластере

Для проверки кластера разверните Nginx с персистентным хранилищем. Это базовый пример, который подтверждает работоспособность всех компонентов: Kubernetes, PVC, ZFS и внешнего доступа через NodePort.

Создание Deployment и Service типа NodePort

Создайте файл nginx.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80
        volumeMounts:
        - name: data
          mountPath: /usr/share/nginx/html
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: test-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30080

Примените манифест:

kubectl apply -f nginx.yaml

Ключевые поля: replicas задаёт количество экземпляров, volumeMounts подключает PVC к контейнеру, nodePort открывает доступ на порту 30080.

Проверка работы приложения и доступ извне

Проверьте статус подов:

kubectl get pods

Под nginx должен быть в статусе Running. Проверьте сервис:

kubectl get svc

Откройте браузер и перейдите по адресу http://IP_АДРЕС_TRUENAS:30080. Вы увидите стандартную страницу Nginx. Это подтверждает, что приложение работает и доступно извне. При проверке из другой подсети дополнительно убедитесь, что межсетевой экран разрешает TCP-подключения к порту 30080.

Типичные проблемы и их решение

При установке и эксплуатации k3s на TrueNAS Scale возникают типовые ошибки. Ниже - причины, быстрые проверки и способы их устранения.

Ошибка: k3s не может запуститься

Симптом: служба имеет статус failed, а узел не появляется в выводе kubectl get nodes. Проверьте логи службы:

journalctl -u k3s -n 50

Частая причина - занятый порт 6443. k3s использует его для API-сервера. Проверьте, какой процесс слушает порт:

ss -ltnp | grep 6443

Если порт занят другим процессом, измените его через флаг:

curl -sfL https://get.k3s.io | sh -s - --https-listen-port 6444

Другая причина - недостаточно памяти. Убедитесь, что на сервере свободно минимум 2 ГБ RAM перед запуском k3s. Также проверьте доступное место на системном диске и состояние службы:

df -h
systemctl status k3s

Проблемы с созданием PVC на ZFS

Симптом: PVC остаётся в статусе Pending, а приложение не запускается. Проверьте событие PVC и dataset ZFS. Dataset должен существовать и быть доступен для записи:

kubectl describe pvc test-pvc
ls -la /mnt/ваш_пул/ваш_dataset

Посмотрите логи CSI-драйвера:

kubectl logs -n democratic-csi -l app=democratic-csi

Ошибка «dataset not found» указывает на неверное имя dataset в StorageClass. Убедитесь, что путь указан точно, включая регистр символов. Если StorageClass не найден, проверьте его имя командой:

kubectl get storageclass

Безопасность и рекомендации по эксплуатации k3s

Базовая установка k3s не предназначена для продакшена. Настройте минимальный уровень безопасности перед запуском рабочих нагрузок.

TrueNAS Scale и k3s на одном сервере используют общие CPU, RAM, сеть и диски. Резервное копирование данных не заменяет резервную копию конфигурации кластера, а одиночный узел не защищает приложения от отказа хоста. Для критичных нагрузок используйте отдельные узлы Kubernetes или управляемую инфраструктуру.

Настройка RBAC и сетевых политик

Создайте отдельные ServiceAccount для приложений и ограничьте их права. Пример RoleBinding для чтения:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-sa
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: default
subjects:
- kind: ServiceAccount
  name: app-sa
  namespace: default
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Включите NetworkPolicy для изоляции подов. k3s по умолчанию использует Flannel, который поддерживает NetworkPolicy.

Обновление k3s и TrueNAS Scale

Перед обновлением проверьте целевые версии k3s и TrueNAS Scale, совместимость CSI-драйвера и наличие резервной копии. k3s обновляется через тот же скрипт установки:

curl -sfL https://get.k3s.io | sh

Перед обновлением создайте резервную копию данных и конфигурации. TrueNAS Scale обновляется через веб-интерфейс: System Settings -> Update. Подробная процедура описана в руководстве по обновлению TrueNAS.

Заключение: дальнейшие шаги после установки k3s

Вы развернули k3s на TrueNAS Scale, настроили интеграцию с ZFS и запустили первое приложение через NodePort. Это рабочая основа для домашнего Kubernetes-кластера и тестирования контейнерных нагрузок.

Дальнейшие шаги:

  • Установите Helm для управления чартами;
  • Настройте мониторинг через Prometheus и Grafana;
  • Добавьте дополнительные узлы для масштабирования;
  • Настройте ingress-контроллер для маршрутизации HTTP-трафика;
  • Проверьте резервное копирование данных и конфигурации перед запуском постоянных нагрузок.

Для продакшена и серьёзных нагрузок рассмотрите облачные решения. Timeweb Cloud предоставляет управляемый Kubernetes с автоматическим масштабированием и резервным копированием.

Экспериментируйте с кластером и тестируйте конфигурации на отдельном стенде перед переносом рабочих нагрузок. Практика - самый быстрый способ освоить Kubernetes.

Поделиться: