ansible_role_shipyard

ansible-role-shipyard

О Shipyard

Shipyard — это инструмент для управления кластерами Docker Swarm и стеков с помощью Ansible плейбуков.

Он вдохновлён Helm и helmfile и предлагает те же концепции в среде Swarm, но не требуя Kubernetes.

Концепции:

Shipyard Chart: Пакет, определяющий стек docker compose и все его связанные файлы (конфигурационные файлы, переменные окружения и т. д.), аналогично Helm Chart, yum RPM файлу или формуле Homebrew. Chart содержит все определения ресурсов, необходимые для развертывания и запуска приложения в виде стека Docker Swarm, размещённых в определённом порядке. Chart может использоваться для развертывания простого приложения или полного веб-приложения с несколькими зависимостями, такими как HTTP-серверы, базы данных, кэши и так далее. (аналогично Helm Chart)
Shipyard Stack: экземпляр Shipyard Chart, настроенный с помощью файла values.yaml. (аналогично Helm Release)
shipyard.yaml: файл, определяющий, какие Charts создавать, используя какие значения на каких хостах Docker. (аналогично helmfile.yaml)

Как вы видите, концепции очень похожи на Helm и helmfile. Главное отличие состоит в том, что Shipyard не привязан к Kubernetes и не требует кластер Kubernetes для работы. Вместо этого он использует Docker Swarm для развертывания стеков.

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

Ansible роль предполагает, что вы предварительно настроили целевые хосты с:

Docker Swarm (т.е. docker swarm deploy работает)
Docker Compose (т.е. docker-compose работает)
Аутентификация для получения Docker изображений (т.е. docker pull my-image работает)

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

Роль может быть настроена с помощью некоторых дополнительных переменных:

shipyard_filename: Путь к вашему файлу shipyard.yaml. По умолчанию: {{inventory_path}}/shipyard.yaml. Этот файл может быть шаблоном Jinja2.
shipyard_charts_path: Путь к вашему каталогу charts. По умолчанию: {{inventory_path}}/shipyard/charts
shipyard_stacks_path: Путь к вашему каталогу стеков (values.yaml / values.sops.yaml). По умолчанию: {{inventory_path}}/shipyard/stacks
shipyard_stacks_docker_secrets: Список Docker Secrets. По умолчанию []
shipyard_tag: по желанию развёртывать только стеки с этой меткой. По умолчанию: пусто

Использование

Получение роли из Ansible galaxy

Настройте ваш файл requirements.yml, чтобы включить роль:

roles:
  - name: linkorb.shipyard

Затем выполните ansible-galaxy install -r requirements.yml, чтобы установить роль.

Создание файла shipyard.yaml:

Файл shipyard.yaml определяет, какие стеки развёртываются на каких хостах. Он аналогичен файлу helmfile.yaml.

# shipyard.yaml
stacks:
  - name: my-traefik
    chart: traefik
    host: swarm-host-a
    values: my-traefik/values.yaml
    tag: lb

  - name: my-whoami
    chart: whoami
    host: swarm-host-a
    values: my-whoami/values.yaml
    tag: apps

  - name: my-mariadb
    chart: mariadb
    host: swarm-host-a
    values: my-mariadb/values.yaml
    tag: db

  - name: my-whoami-b
    chart: whoami
    host: swarm-host-b
    values: my-whoami-b/values.yaml
    tag: apps

Добавление роли shipyard в ваш Ansible плейбук

В вашем Ansible плейбуке (обычно site.yml) добавьте следующее:

- name: Конфигурация хоста Docker shipyard
  hosts: my-swarm-hosts # или группа хостов - ожидаются менеджеры docker swarm с настроенной аутентификацией для получения изображений docker
  tags:
    - shipyard # или любая другая метка, которую вы хотите использовать для запуска этого плейбука
  roles:
    - role: linkorb.shipyard # роль из Ansible Galaxy
      vars:
        shipyard_tag: apps

Это будет искать файл shipyard.yml в корне директории плейбук. Он развернёт на управляемых хостах стеки, отмеченные меткой apps, указанные в нем.

Создание Shipyard Chart

Структура директории Shipyard Chart:

my-shipyard-chart/
  Chart.yaml # метаданные чарта
  LICENSE # лицензия для этого чарта
  README.md # инструкция для этого чарта
  values.yaml # значения по умолчанию для этого чарта
  templates/ # шаблоны jinja2 для этого чарта
    docker-compose.yml # шаблон файла docker compose для этого чарта
    example.conf # шаблон конфигурационного файла для этого чарта
    env.example # другой шаблон конфигурационного файла для этого чарта
    a-directory/ # каталог, который будет скопирован на целевой хост

Роль Shipyard скопирует все файлы и папки из директории templates/ на целевой хост и затем отрендерит файлы, используя значения Chart и Stack (см. следующий раздел для получения дополнительной информации об этом).

values.yaml / values.sops.yaml и значения по умолчанию для чарта

Каждый стек (один экземпляр чарта) принимает файл значений, содержащий значения для этого экземпляра чарта. Значения загружаются из {{shipyard_stacks_path}}/{{stack_name}}/values.yaml. Если обнаружен файл values.sops.yaml, он также загружается и автоматически расшифровывается (на основе .sops.yaml в корне вашего репозитория).

Каждый чарт также предоставляет значения по умолчанию в values.yaml. Любое значение на уровне стека, которое остаётся неопределённым, будет установлено в значение по умолчанию чарта.

Порядок загрузки (и приоритета переопределения) следующий:

значения по умолчанию из чарта
values.yaml из стека
values.sops.yaml из стека

Специальные значения

primed_volumes: список объектов информации о том, какие docker volume будут созданы для стека.

Это значение имеет смысл только тогда, когда чарт его поддерживает.

Каждый объект информации о volume имеет следующие свойства:
- name: Имя volume
- target: Место в контейнере, где монтируется volume
- path: Путь, под стеке на удалённом хосте, который нужно рекурсивно скопировать в volume.
Например, volume, содержащий скрипты инициализации базы данных MariaDB, можно создать так:
```
# my-stack/values.yaml
primed_volumes:
- name: mariadb_init_data
  target: /docker-entrypoint-initdb.d # это то место, где контейнер MariaDB ищет данные инициализации
  path: docker-entrypoint-initdb.d # этот каталог присутствует в каталоге шаблонов Chart
```

Структура директорий целевого хоста

На целевых хостах (менеджерах Docker Swarm) роль создаст следующую структуру директорий:

/opt/shipyard/stacks/
  my-shipyard-stack/
    docker-compose.yml # отрендеренный файл docker compose
    example.conf # отрендеренный пример конфигурационного файла
    # ... и так далее

Развёртывание стеков в Docker Swarm

После того как шаблоны отрендерены и записаны на хост, роль выполнит docker stack deploy на целевом хосте для развёртывания стека Docker Swarm.

Пример Shipyard Chart

Смотрите директорию example/shipyard/charts/whoami для примера Shipyard Chart.

Участие

Мы приветствуем участие, чтобы сделать этот репозиторий ещё лучше. Будь то исправление ошибки, добавление функции или улучшение документации, ваша помощь будет очень ценна. Чтобы начать, сделайте форк этого репозитория, затем клонируйте ваш форк.

Обязательно ознакомьтесь с Руководством по вкладам LinkORB для наших стандартов по коммитам, веткам и pull-запросам, а также с нашим кодом поведения перед тем, как вносить изменения.

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