k3s

Ansible Роль: k3s (v3.x)

Ansible роль для установки K3S ("Легковесный Kubernetes") как на отдельном сервере, так и в кластере.

Нужна помощь!

Привет! :wave: @xanmanning ищет нового поддерживающего разработчика для этой Ansible роли. Это связано с тем, что у меня больше нет свободного времени, и я больше не пишу Ansible регулярно в рамках своей работы. Если вы заинтересованы, свяжитесь со мной.

Примечания к релизу

Пожалуйста, смотрите Релизы и CHANGELOG.md.

Требования

Хост, с которого вы запускаете Ansible, требует следующие зависимости Python:

python >= 3.6.0 - Смотрите примечания ниже.
ansible >= 2.9.16 или ansible-base >= 2.10.4

Вы можете установить зависимости, используя файл requirements.txt в этом репозитории: pip3 install -r requirements.txt.

Эта роль была протестирована на следующих дистрибутивах Linux:

Alpine Linux
Amazon Linux 2
Archlinux
CentOS 8
Debian 11
Fedora 31
Fedora 32
Fedora 33
openSUSE Leap 15
RockyLinux 8
Ubuntu 20.04 LTS

:warning: Релизы версии v3 этой роли поддерживают только k3s >= v1.19. Для k3s < v1.19 пожалуйста, подумайте о том, чтобы обновиться, или используйте релизы v1.x этой роли.

Перед обновлением, смотрите CHANGELOG для уведомлений о критических изменениях.

Переменные роли

Начиная с K3s v1.19.1+k3s1, вы можете теперь настраивать K3s с помощью конфигурационного файла, а не с использованием переменных окружения или аргументов командной строки. Релиз v2 этой роли перешел на метод конфигурационного файла, вместо заполнения файла юнита systemd аргументами командной строки. Однако могут быть исключения, определенные в Глобальных/Кластерных переменных, в остальном вы будете настраивать k3s с помощью конфигурационных файлов, используя переменные k3s_server и k3s_agent.

Смотрите "Конфигурация сервера (Управляющая плоскость)" и "Конфигурация агента (Рабочий узел)" ниже.

Глобальные/Кластерные переменные

Ниже перечислены переменные, которые устанавливаются для всех игровых хостов для согласованности окружения. Обычно это конфигурация на уровне кластера.

Переменная	Описание	Значение по умолчанию
`k3s_state`	Состояние k3s: установлен, запущен, остановлен, загружен, удалён, валидирован.	установлен
`k3s_release_version`	Использовать конкретную версию k3s, например, `v0.2.0`. Установите `false` для стабильной версии.	`false`
`k3s_airgap`	Булевый флаг для включения установки в изолированном режиме	`false`
`k3s_config_file`	Местоположение конфигурационного файла k3s.	`/etc/rancher/k3s/config.yaml`
`k3s_build_cluster`	При наличии нескольких игровых хостов, попытка объединить их в кластер. Смотрите примечания ниже.	`true`
`k3s_registration_address`	Фиксированный адрес регистрации для узлов. IP или FQDN.	NULL
`k3s_github_url`	Установить URL GitHub для установки k3s.	https://github.com/k3s-io/k3s
`k3s_api_url`	URL для API обновлений K3S.	https://update.k3s.io
`k3s_install_dir`	Каталог установки для k3s.	`/usr/local/bin`
`k3s_install_hard_links`	Установка с использованием жестких ссылок вместо символических.	`false`
`k3s_server_config_yaml_d_files`	Плоский список шаблонов для дополнения конфигурации `k3s_server`.	[]
`k3s_agent_config_yaml_d_files`	Плоский список шаблонов для дополнения конфигурации `k3s_agent`.	[]
`k3s_server_manifests_urls`	Список URL для развертывания на основной управляющей плоскости. Смотрите примечания ниже.	[]
`k3s_server_manifests_templates`	Плоский список шаблонов для развертывания на основной управляющей плоскости.	[]
`k3s_server_pod_manifests_urls`	Список URL для установки статических манифестов подов на управляющей плоскости. Смотрите примечания ниже.	[]
`k3s_server_pod_manifests_templates`	Плоский список шаблонов для установки статических манифестов подов на управляющей плоскости.	[]
`k3s_use_experimental`	Разрешить использование экспериментальных функций в k3s.	`false`
`k3s_use_unsupported_config`	Разрешить использование неподдерживаемых конфигураций в k3s.	`false`
`k3s_etcd_datastore`	Включить встроенное хранилище etcd (смотрите примечания ниже).	`false`
`k3s_debug`	Включить ведение журнала отладки службы k3s.	`false`
`k3s_registries`	Содержание файла конфигурации реестров.	`{ mirrors: {}, configs:{} }`

Конфигурация службы K3S

Ниже перечислены переменные, которые изменяют, как и когда исполняется файл юнита службы systemd для K3S. Использовать с осторожностью, пожалуйста, обратитесь к документации systemd для получения дополнительной информации.

Переменная	Описание	Значение по умолчанию
`k3s_start_on_boot`	Запускать k3s при загрузке.	`true`
`k3s_service_requires`	Список необходимых юнитов systemd для юнита службы k3s.	[]
`k3s_service_wants`	Список "желаемых" юнитов systemd для k3s (слабее, чем "требуется").	[]*
`k3s_service_before`	Запускать k3s до определённого списка юнитов systemd.	[]
`k3s_service_after`	Запускать k3s после определённого списка юнитов systemd.	[]*
`k3s_service_env_vars`	Словарь переменных окружения для использования в файле юнита systemd.	{}
`k3s_service_env_file`	Местоположение файла окружения на хосте.	`false`**

* Шаблон юнита systemd всегда указывает network-online.target для "желаемых" и "после".

** Файл должен уже существовать на целевом хосте, эта роль не создаёт и не управляет файлом. Вы можете управлять этим файлом вне роли с помощью предварительных задач в вашем Ansible playbook.

Групповые/Хостовые переменные

Ниже перечислены переменные, которые устанавливаются для отдельных или групп игровых хостов. Обычно вы устанавливаете их на уровне группы для управляющей плоскости или рабочих узлов.

Переменная	Описание	Значение по умолчанию
`k3s_control_node`	Указывает, является ли хост (или группа хостов) частью управляющей плоскости.	`false` (роль автоматически делегирует узел)
`k3s_server`	Конфигурация сервера (управляющая плоскость), смотрите примечания ниже.	`{}`
`k3s_agent`	Конфигурация агента (работающий узел), смотрите примечания ниже.	`{}`

Конфигурация сервера (Управляющая плоскость)

Управляющая плоскость настраивается с помощью переменной словаря k3s_server. Пожалуйста, обратитесь к нижеуказанной документации для параметров конфигурации:

https://rancher.com/docs/k3s/latest/en/installation/install-options/server-config/

Переменная словаря k3s_server будет содержать флаги из вышеуказанного (удалив префикс --). Ниже приведен пример:

k3s_server:
  datastore-endpoint: postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable
  cluster-cidr: 172.20.0.0/16
  flannel-backend: 'none'  # Это должно быть в кавычках
  disable:
    - traefik
    - coredns

Или вы можете создать файл .yaml и читать его в переменную k3s_server, как в примере ниже:

k3s_server: "{{ lookup('file', 'path/to/k3s_server.yml') | from_yaml }}"

Смотрите Документацию для примеров конфигурации.

Конфигурация агента (Рабочий узел)

Рабочие узлы настраиваются с помощью переменной словаря k3s_agent. Пожалуйста, обратитесь к нижеуказанной документации для параметров конфигурации:

https://rancher.com/docs/k3s/latest/en/installation/install-options/agent-config

Переменная словаря k3s_agent будет содержать флаги из вышеуказанного (удалив префикс --). Ниже приведен пример:

k3s_agent:
  with-node-id: true
  node-label:
    - "foo=bar"
    - "hello=world"

Или вы можете создать файл .yaml и читать его в переменную k3s_agent, как в примере ниже:

k3s_agent: "{{ lookup('file', 'path/to/k3s_agent.yml') | from_yaml }}"

Смотрите Документацию для примеров конфигурации.

Переменные конфигурации контроллера Ansible

Ниже перечислены переменные, которые используются для изменения способа выполнения роли в Ansible, особенно в отношении повышения привилегий.

Переменная	Описание	Значение по умолчанию
`k3s_skip_validation`	Пропустить все задачи, которые проверяют конфигурацию.	`false`
`k3s_skip_env_checks`	Пропустить все задачи, которые проверяют конфигурацию окружения.	`false`
`k3s_skip_post_checks`	Пропустить все задачи, которые проверяют состояние после выполнения.	`false`
`k3s_become`	Повышение привилегий пользователя для задач, которые требуют прав root.	`false`

Важная заметка о Python

С версии v3 этой роли требуется Python 3 как на целевой системе, так и на контроллере Ansible. Это необходимо для обеспечения согласованного поведения задач Ansible, так как Python 2 сейчас не поддерживается.

Если на целевых системах установлены обе версии Python 2 и Python 3, вероятнее всего, по умолчанию будет выбрана версия Python 2. Чтобы убедиться, что используется Python 3 на целевой системе с обеими версиями, убедитесь, что для ansible_python_interpreter установлен правильный путь в вашем инвентаре. Ниже приведен пример инвентаря:

---

k3s_cluster:
  hosts:
    kube-0:
      ansible_user: ansible
      ansible_host: 10.10.9.2
      ansible_python_interpreter: /usr/bin/python3
    kube-1:
      ansible_user: ansible
      ansible_host: 10.10.9.3
      ansible_python_interpreter: /usr/bin/python3
    kube-2:
      ansible_user: ansible
      ansible_host: 10.10.9.4
      ansible_python_interpreter: /usr/bin/python3

Важная заметка о `k3s_release_version`

Если вы не установите k3s_release_version, будет установлена последняя версия из стабильного канала k3s. Если вы разрабатываете с использованием конкретной версии k3s, вы должны убедиться, что это значение установлено в вашей конфигурации Ansible, например:

k3s_release_version: v1.19.3+k3s1

Также возможно установить конкретные "Каналы" k3s, ниже приведены некоторые примеры для k3s_release_version:

k3s_release_version: false             # по умолчанию 'stable' канал
k3s_release_version: stable            # последняя 'stable' версия
k3s_release_version: testing           # последняя 'testing' версия
k3s_release_version: v1.19             # последняя 'v1.19' версия
k3s_release_version: v1.19.3+k3s3      # конкретная версия

# Конкретный коммит
# ОСТОРОЖНО - используется только для тестирования - должен быть 40 символов
k3s_release_version: 48ed47c4a3e420fa71c18b2ec97f13dc0659778b

Важная заметка о `k3s_install_hard_links`

Если вы используете system-upgrade-controller, вам нужно будет использовать жесткие ссылки вместо символических, так как контроллер не сможет следовать за символическими ссылками. Эта опция добавлена, но по умолчанию не включена, чтобы избежать поломки существующих установок.

Чтобы включить использование жестких ссылок, установите k3s_install_hard_links в true.

k3s_install_hard_links: true

Результат этого можно увидеть, выполнив следующую команду в k3s_install_dir:

Символические ссылки:

[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort
3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1
3279565 lrwxrwxrwx 1 root root   31 Jul 25 12:52 k3s -> /usr/local/bin/k3s-v1.18.6+k3s1
3279644 -rwxr-xr-x 1 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1
3280079 lrwxrwxrwx 1 root root   31 Jul 25 12:52 ctr -> /usr/local/bin/k3s-v1.18.6+k3s1
3280080 lrwxrwxrwx 1 root root   31 Jul 25 12:52 crictl -> /usr/local/bin/k3s-v1.18.6+k3s1
3280081 lrwxrwxrwx 1 root root   31 Jul 25 12:52 kubectl -> /usr/local/bin/k3s-v1.18.6+k3s1

Жесткие ссылки:

[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort
3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 crictl
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 ctr
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 kubectl

Важная заметка о `k3s_build_cluster`

Если вы установите k3s_build_cluster в false, эта роль будет устанавливать каждый игровой хост как отдельный узел. Пример, когда вы можете использовать это, — это создание большого количества отдельных IoT-устройств, работающих на K3s. Ниже приведена гипотетическая ситуация, в которой мы собираемся развернуть 25 изменений Raspberry Pi, каждое отдельной системой, а не кластер из 25 узлов. Для этого мы бы использовали playbook, подобный приведенному ниже:

- hosts: k3s_nodes  # например, 25 RPi в нашем инвентаре.
  vars:
    k3s_build_cluster: false
  roles:
     - xanmanning.k3s

Важная заметка о `k3s_control_node` и высокой доступности (HA)

По умолчанию только один хост будет определён как управляющий узел в Ansible. Если вы не установите хост как управляющий узел, эта роль автоматически делегирует первый игровой хост как управляющий узел. Это не подходит для использования в рабочей нагрузке.

Если несколько хостов имеют k3s_control_node, установленное в true, вы также должны установить datastore-endpoint в k3s_server в качестве строки соединения к базе данных MySQL или PostgreSQL, или внешнему кластеру Etcd, в противном случае выполнение плей будет неудачным.

Если используется TLS, CA, сертификат и ключ должны быть уже доступны на игровых хостах.

Смотрите: Высокая доступность с внешней БД

Также возможно, хотя и не поддерживается, запустить один управляющий узел K3s с определенным datastore-endpoint. Поскольку это не обычно поддерживаемая конфигурация, вам нужно будет установить k3s_use_unsupported_config в true.

С версии K3s v1.19.1 возможно использовать встроенный Etcd как бэкенд для базы данных, и это делается установкой k3s_etcd_datastore в true. Лучшей практикой для Etcd является определение как минимум трех участников для обеспечения кворума. Кроме того, рекомендуется иметь нечетное количество участников, чтобы гарантировать большинство в случае сетевого разъединения. Если вы хотите использовать 2 участника или четное количество участников, пожалуйста, установите k3s_use_unsupported_config в true.

Важная заметка о `k3s_server_manifests_urls` и `k3s_server_pod_manifests_urls`

Чтобы развернуть серверные манифесты и манифесты подов сервера по URL, вам нужно указать url и, при необходимости, filename (если не указано, используется базовое имя). Ниже приведен пример, как развернуть оператора Tigera для Calico и kube-vip.

---

k3s_server_manifests_urls:
  - url: https://docs.projectcalico.org/archive/v3.19/manifests/tigera-operator.yaml
    filename: tigera-operator.yaml

k3s_server_pod_manifests_urls:
  - url: https://raw.githubusercontent.com/kube-vip/kube-vip/main/example/deploy/0.1.4.yaml
    filename: kube-vip.yaml

Важная заметка о `k3s_airgap`

При развертывании k3s в изолированной среде вы должны предоставить бинарный файл k3s в ./files/. Бинарный файл не будет загружен с GitHub и, следовательно, не будет проверен с использованием предоставленной контрольной суммы sha256, а также не сможет проверить версию, которую вы запускаете. Все риски и обязательства, связанные с этим, принимаются на себя пользователем в данной ситуации.

Зависимости

Нет зависимостей от других ролей.

Примеры Playbook

Пример playbook, один управляющий узел, работающий с testing канала k3s:

- hosts: k3s_nodes
  vars:
    k3s_release_version: testing
  roles:
     - role: xanmanning.k3s

Пример playbook, высокая доступность с базой данных PostgreSQL, работающий с последним стабильным релизом:

- hosts: k3s_nodes
  vars:
    k3s_registration_address: loadbalancer  # Обычно балансировщик нагрузки.
    k3s_server:
      datastore-endpoint: "postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable"
  pre_tasks:
    - name: Установить каждый узел как управляющий узел
      ansible.builtin.set_fact:
        k3s_control_node: true
      when: inventory_hostname in ['node2', 'node3']
  roles:
    - role: xanmanning.k3s

Лицензия

BSD 3-clause

Участники

Вклад от сообщества очень приветствуется, но пожалуйста, прочитайте руководство по вкладу перед тем, как это сделать, это поможет сделать все максимально гладко.

Также, пожалуйста, ознакомьтесь с замечательным списком участников.

Информация об авторе

Xan Manning

О проекте

Ansible role for installing k3s as either a standalone server or HA cluster

role k3s k8s kubernetes containerd cluster lightweight

Установить

ansible-galaxy install PyratLabs/ansible-role-k3s

GitHub репозиторий

626 звезд(ы)

136 форк(ов)

7 открытых задач

Лицензия

bsd-3-clause

Загрузки

948871

Владелец

PyratLabs

Deep in the lab...

Ansible Роль: k3s (v3.x)

Нужна помощь!

Примечания к релизу

Требования

Переменные роли

Глобальные/Кластерные переменные

Конфигурация службы K3S

Групповые/Хостовые переменные

Конфигурация сервера (Управляющая плоскость)

Конфигурация агента (Рабочий узел)

Переменные конфигурации контроллера Ansible

Важная заметка о Python

Важная заметка о k3s_release_version

Важная заметка о k3s_install_hard_links

Важная заметка о k3s_build_cluster

Важная заметка о k3s_control_node и высокой доступности (HA)

Важная заметка о k3s_server_manifests_urls и k3s_server_pod_manifests_urls

Важная заметка о k3s_airgap

Зависимости

Примеры Playbook

Лицензия

Участники

Информация об авторе

Ansible role for installing k3s as either a standalone server or HA cluster

Важная заметка о `k3s_release_version`

Важная заметка о `k3s_install_hard_links`

Важная заметка о `k3s_build_cluster`

Важная заметка о `k3s_control_node` и высокой доступности (HA)

Важная заметка о `k3s_server_manifests_urls` и `k3s_server_pod_manifests_urls`

Важная заметка о `k3s_airgap`