Автоматизированная установка с Ansible

Ansible collection cozystack.installer автоматизирует весь pipeline развертывания: подготовку ОС, bootstrap кластера k3s и установку Cozystack. Она подходит для развертывания Cozystack на bare-metal серверах или ВМ со стандартным дистрибутивом Linux.

Когда использовать Ansible

Рассмотрите этот подход, если:

• Вам нужно полностью автоматизированное, повторяемое развертывание от чистой ОС до работающего Cozystack
• Вы развертываете платформу на generic Linux (Ubuntu, Debian, RHEL, Rocky, openSUSE), а не на Talos Linux
• Вы хотите управлять несколькими узлами через один inventory-файл

Шаги ручной установки без Ansible см. в руководстве Generic Kubernetes.

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

Controller Machine

• Python >= 3.9
• Ansible >= 2.15

Target Nodes

• Операционная система: Ubuntu/Debian, RHEL 8+/CentOS Stream 8+/Rocky/Alma или openSUSE/SLE
• Архитектура: amd64 или arm64
• SSH-доступ с passwordless sudo
• Требования к CPU, RAM и дискам см. в требованиях к оборудованию

Установка

1. Установка Ansible Collection

ansible-galaxy collection install git+https://github.com/cozystack/ansible-cozystack.git

Установите необходимые dependency collections. Файл requirements.yml не включен в packaged collection, поэтому скачайте его из репозитория:

curl --silent --location --output /tmp/requirements.yml \
  https://raw.githubusercontent.com/cozystack/ansible-cozystack/main/requirements.yml
ansible-galaxy collection install --requirements-file /tmp/requirements.yml

Это установит следующие зависимости:

• ansible.posix, community.general, kubernetes.core — из Ansible Galaxy
• k3s.orchestration — collection для развертывания k3s, устанавливается из Git

2. Создание Inventory

Создайте файл inventory.yml. Внутренний (private) IP каждого узла должен использоваться как host key, потому что KubeOVN проверяет IP хостов через NODE_IPS. Public IP, если он отличается, указывается в ansible_host.

cluster:
  children:
    server:
      hosts:
        10.0.0.10:
          ansible_host: 203.0.113.10
    agent:
      hosts:
        10.0.0.11:
          ansible_host: 203.0.113.11
        10.0.0.12:
          ansible_host: 203.0.113.12

  vars:
    ansible_port: 22
    ansible_user: ubuntu

    # настройки k3s — доступные версии см. на https://github.com/k3s-io/k3s/releases
    k3s_version: v1.35.0+k3s3
    token: "CHANGE_ME"  # ЗАМЕНИТЕ на надежный случайный secret
    api_endpoint: "10.0.0.10"
    cluster_context: my-cluster

    # настройки Cozystack
    cozystack_api_server_host: "10.0.0.10"
    cozystack_root_host: "cozy.example.com"
    cozystack_platform_variant: "isp-full-generic"
    # cozystack_k3s_extra_args: "--tls-san=203.0.113.10"  # добавьте public IP, если узлы находятся за NAT

cozystack_chart_version: "1.0.0-rc.2"

3. Создание Playbook

Создайте файл site.yml, который последовательно запускает подготовку ОС, развертывание k3s и установку Cozystack.

Репозиторий collection содержит примеры prepare playbooks для каждого поддерживаемого семейства ОС в каталоге examples/. Скопируйте подходящий для вашей целевой ОС файл в каталог проекта, затем подключите его как локальный файл:

• Ubuntu / Debian
• RHEL / Rocky / Alma
• openSUSE / SLE

- name: Prepare nodes
  ansible.builtin.import_playbook: prepare-ubuntu.yml

- name: Deploy k3s cluster
  ansible.builtin.import_playbook: k3s.orchestration.site

- name: Install Cozystack
  ansible.builtin.import_playbook: cozystack.installer.site

- name: Prepare nodes
  ansible.builtin.import_playbook: prepare-rhel.yml

- name: Deploy k3s cluster
  ansible.builtin.import_playbook: k3s.orchestration.site

- name: Install Cozystack
  ansible.builtin.import_playbook: cozystack.installer.site

- name: Prepare nodes
  ansible.builtin.import_playbook: prepare-suse.yml

- name: Deploy k3s cluster
  ansible.builtin.import_playbook: k3s.orchestration.site

- name: Install Cozystack
  ansible.builtin.import_playbook: cozystack.installer.site

4. Запуск Playbook

ansible-playbook --inventory inventory.yml site.yml

Playbook автоматически выполняет следующие шаги:

1. Prepare nodes — устанавливает необходимые пакеты (nfs-common, open-iscsi, multipath-tools), настраивает sysctl, включает storage services
2. Deploy k3s — выполняет bootstrap кластера k3s с настройками, совместимыми с Cozystack (отключает встроенные Traefik, ServiceLB, kube-proxy, Flannel; задает cluster-domain=cozy.local)
3. Install Cozystack — устанавливает Helm и plugin helm-diff (используется для идемпотентных обновлений), развертывает chart cozy-installer, ожидает operator и CRD, затем создает Platform Package

Справочник конфигурации

Основные переменные

Networking

Advanced

Переменные Prepare Playbook

Примерные prepare playbooks (скопированные из каталога examples/) поддерживают дополнительные переменные:

Проверка

После завершения playbook проверьте развертывание с первого server-узла:

# Проверить operator
kubectl get deployment cozystack-operator --namespace cozy-system

# Проверить Platform Package
kubectl get packages.cozystack.io cozystack.cozystack-platform

# Проверить все pods
kubectl get pods --all-namespaces

Идемпотентность

Playbook идемпотентен: повторный запуск не будет повторно применять ресурсы, которые не изменились. Platform Package применяется только при обнаружении diff через kubectl diff.