deploy

Ansistrano

ansistrano.deploy и ansistrano.rollback — это роли Ansible, которые позволяют легко управлять процессом развертывания приложений, таких как PHP, Python и Ruby. Это порт Capistrano для Ansible.

Ansistrano

История

Capistrano — это инструмент автоматизации удаленных серверов, и сейчас он находится на версии 3. Изначально версия 2.0 была задумана для развертывания приложений RoR. С дополнительными плагинами вы могли развертывать не Rails приложения, такие как PHP и Python, с различными стратегиями развертывания и многое другое. Я любил Capistrano v2 и много его использовал, даже разработал для него плагин.

Capistrano 2 был отличным инструментом и до сих пор работает хорошо. Однако его больше не поддерживают, так как оригинальная команда работает над версией 3. Эта новая версия не имеет такого же набора функций, поэтому она менее мощная и гибкая. Кроме того, появляются новые инструменты, которые легче использовать для развертывания приложений, такие как Ansible.

Поэтому я решил прекратить использование Capistrano, потому что v2 больше не поддерживается, v3 не имеет достаточно функций, и я могу сделать все, что делал Capistrano, с помощью Ansible. Если вы ищете альтернативы, посмотрите на Fabric или Chef Solo.

Имя проекта

Ansistrano — это сочетание Ansible и Capistrano, просто, не правда ли?

Статистика анонимного использования Ansistrano

В Ansistrano есть необязательный шаг, который отправляет HTTP-запрос на наши серверы. К сожалению, метрики, которые мы получаем из Ansible Galaxy, ограничены, поэтому это один из немногих способов измерить, сколько активных пользователей у нас действительно есть.

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

Кто использует Ansistrano?

Ansistrano готов к использованию? Вот некоторые компании, которые его используют:

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

Требования

Чтобы развернуть ваши приложения с помощью Ansistrano, вам потребуется:

Ansible на вашей машине развертывания
rsync на целевой машине, если вы используете стратегию развертывания rsync, rsync_direct или git, или если вы используете ansistrano_current_via = rsync

Установка

Ansistrano — это роль Ansible, распространяемая по всему миру с использованием Ansible Galaxy. Чтобы установить роль Ansistrano, вы можете использовать следующую команду.

$ ansible-galaxy install ansistrano.deploy ansistrano.rollback

Обновление

Если вы хотите обновить роль, вам нужно передать параметр --force при установке. Пожалуйста, проверьте следующую команду:

$ ansible-galaxy install --force ansistrano.deploy ansistrano.rollback

Особенности

Откат за считанные секунды (с помощью роли ansistrano.rollback)
Настройте ваше развертывание с помощью хуков до и после критических шагов
Экономьте место на диске, сохраняя фиксированное количество релизов на ваших хостах
Выберите среди стратегий развертывания SCP, RSYNC, GIT, SVN, HG, HTTP Download или S3 GET (добавлен необязательный шаг разархивации)

Основной рабочий процесс

Ansistrano разворачивает приложения, следуя потоку Capistrano.

Фаза настройки: Создает структуру папок для хранения ваших релизов
Фаза обновления кода: Загружает новый релиз на ваши хосты
Фаза создания символической ссылки: После развертывания нового релиза на ваших хостах этот шаг меняет символическую ссылку current на новый релиз
Фаза очистки: Удаляет любые старые версии в соответствии с параметром ansistrano_keep_releases (см. "Переменные роли")

Поток Ansistrano

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

vars:
  ansistrano_deploy_from: "{{ playbook_dir }}/" # Где находится мой локальный проект (относительный или абсолютный путь)
  ansistrano_deploy_to: "/var/www/my-app" # Основной путь для развертывания.
  ansistrano_version_dir: "releases" # Имя папки для релизов
  ansistrano_shared_dir: "shared" # Имя общей папки
  ansistrano_current_dir: "current" # Имя символической ссылки. Обычно вам не нужно его изменять.
  ansistrano_current_via: "symlink" # Стратегия развертывания, с которой код должен развертываться в текущий путь. Опции: symlink или rsync
  ansistrano_keep_releases: 0 # Релизы, которые нужно сохранить после нового развертывания. См. "Удаление старых релизов".

  # Массивы директорий и файлов, которые будут совместно использоваться.
  # Следующие массивы директорий и файлов будут связаны с текущей директорией релиза после шага 'update-code' и его обратных вызовов
  # Примечания:
  # * Пути относительные к общей директории (без начала /)
  # * Если ваши элементы находятся в подпапке, укажите полный путь к каждой общей директории
  #
  # Пример:
  # ansistrano_shared_paths:
  #   - path/to/first-dir
  #   - path/next-dir
  # ansistrano_shared_files:
  #   - my-file.txt
  #   - path/to/file.txt
  ansistrano_shared_paths: []
  ansistrano_shared_files: []

  # Создание общих путей и базовых директорий для общих файлов.
  # По умолчанию директории общих путей и базовые директории для общих файлов создаются автоматически, если они не существуют. Но в некоторых сценариях эти пути могут быть символическими ссылками на другие директории в файловой системе, и процесс развертывания может завершиться неудачно. С помощью этих переменных вы можете отключить соответствующие задачи. Если у вас есть две или три общих директории, и вы не хотите создавать их только для некоторых из них, вы всегда можете отключить автоматическое создание и добавить пользовательскую задачу в хуке.
  ansistrano_ensure_shared_paths_exist: yes
  ansistrano_ensure_basedirs_shared_files_exist: yes
  
  # Стратегия развертывания - метод, используемый для доставки кода. Опции: copy, download, git, rsync, rsync_direct, svn или s3. 
  ansistrano_deploy_via: rsync 
  # Copy, download и s3 имеют необязательный шаг для разархивации загруженного файла, который можно использовать, добавив _unarchive. 
  # Стратегия rsync_direct пропускает копирование файла на целевом сервере, предлагая небольшое увеличение скорости, если вы развертываете на совместимых хостах, испытываете плохую производительность файлов или обслуживаете статические ресурсы с того же хоста, на который вы развертываете свое приложение и rsync много файлов.
  # Вы можете проверить все опции в папке tasks/update-code!
  
  ansistrano_allow_anonymous_stats: yes

  # Переменные, используемые в стратегии развертывания rsync/rsync_direct
  ansistrano_rsync_extra_params: "" # Дополнительные параметры, используемые при развертывании с rsync в виде одной строки. Хотя Ansible позволяет использовать массив, это может вызвать проблемы, если мы попробуем добавить несколько аргументов --include, как было сообщено в https://github.com/ansistrano/deploy/commit/e98942dc969d4e620313f00f003a7ea2eab67e86
  ansistrano_rsync_set_remote_user: yes # См. [модуль синхронизации ansible](http://docs.ansible.com/ansible/synchronize_module.html). Опции: yes, no.
  ansistrano_rsync_path: "" # См. [модуль синхронизации ansible](http://docs.ansible.com/ansible/synchronize_module.html). По умолчанию это "sudo rsync", его можно переопределить (например): "sudo -u user rsync".
  ansistrano_rsync_use_ssh_args: no # См. [модуль синхронизации ansible](http://docs.ansible.com/ansible/synchronize_module.html). Если установлено yes, используются ssh_args, указанные в ansible.cfg.

  # Переменные, используемые в стратегии развертывания Git
  ansistrano_git_repo: [email protected]:USERNAME/REPO.git # Путь к репозиторию git
  ansistrano_git_branch: master # Какую версию репозитория развернуть. Это может быть полный 40-символьный SHA-1 хэш, явная строка HEAD, имя ветки или имя тега
  ansistrano_git_repo_tree: "" # Если указано, поддерево репозитория для развертывания
  ansistrano_git_identity_key_path: "" # Если указано, этот файл копируется и используется в качестве ключа идентификации для команд git, путь относительный к плейбуку, в котором он используется
  ansistrano_git_identity_key_remote_path: "" # Если указано, этот файл на удаленном сервере используется в качестве ключа идентификации для команд git, удаленный путь абсолютный
  ansistrano_git_identity_key_shred: true # По умолчанию шредирует ключ идентификации, но может быть перегружен в false, если вы столкнетесь со следующей проблемой (https://github.com/ansistrano/deploy/issues/357)
  # Необязательные переменные, по умолчанию опускаются
  ansistrano_git_refspec: ADDITIONAL_GIT_REFSPEC # Дополнительный refspec, используемый модулем 'git'. Использует тот же синтаксис, что и команда 'git fetch'.
  ansistrano_git_ssh_opts: "-o StrictHostKeyChecking=no" # Дополнительные ssh параметры, которые будут использоваться в Git
  ansistrano_git_depth: 1 # Дополнительная история сокращена до указанного числа изменений
  ansistrano_git_executable: /opt/local/bin/git # Путь к исполняемому файлу git. Если не указан, будет использоваться обычный механизм для разрешения бинарных путей.

  # Переменные, используемые в стратегии развертывания SVN
  # Обратите внимание, что в модуле subversion в серии Ansible 1.8.x была ошибка (https://github.com/ansible/ansible-modules-core/issues/370), поэтому он поддерживается только с Ansible 1.9
  ansistrano_svn_repo: https://svn.company.com/project # Путь к репозиторию svn
  ansistrano_svn_branch: trunk # Какую ветку из репозитория развернуть.
  ansistrano_svn_revision: HEAD # Какую ревизию из репозитория развернуть.
  ansistrano_svn_username: user # Имя пользователя для аутентификации SVN
  ansistrano_svn_password: Pa$$word # Пароль для аутентификации SVN
  ansistrano_svn_environment: {} # Словарь с переменными окружения для svn задач (https://docs.ansible.com/ansible/playbooks_environment.html)

  # Переменные, используемые в стратегии развертывания HG
  ansistrano_hg_repo: https://[email protected]/USERNAME/REPO # Путь к репозиторию hg
  ansistrano_hg_branch: default # Любой идентификатор ветки, который работает с hg -r, например, имя ветки, закладка, хэш коммита...

  # Переменные, используемые в стратегии развертывания загрузки
  ansistrano_get_url: https://github.com/someproject/somearchive.tar.gz
  ansistrano_download_force_basic_auth: false # нет значения по умолчанию, так как это поддерживается только с Ansible 2.0
  ansistrano_download_headers: "" # нет значения по умолчанию, так как это поддерживается только с Ansible 2.0

  # Переменные, используемые в стратегии развертывания S3
  ansistrano_s3_bucket: s3bucket
  ansistrano_s3_object: s3object.tgz # Добавьте суффикс _unarchive к ansistrano_deploy_via, если ваш объект является пакетом (например, s3_unarchive)
  ansistrano_s3_region: eu-west-1
  ansistrano_s3_rgw: false # должен быть Ansible >= 2.2. используйте Ceph RGW для облачных поставщиков, совместимых с S3
  ansistrano_s3_url: http://rgw.example.com # когда используете Ceph RGW, укажите url
  # Необязательные переменные, по умолчанию опускаются
  ansistrano_s3_aws_access_key: YOUR_AWS_ACCESS_KEY
  ansistrano_s3_aws_secret_key: YOUR_AWS_SECRET_KEY
  ansistrano_s3_ignore_nonexistent_bucket: false
  
  # Переменные, используемые в стратегии GCS
  ansistrano_gcs_bucket: gcsbucket
  ansistrano_gcs_object: gcsobject.tgz # Добавьте суффикс _unarchive к ansistrano_deploy_via, если ваш объект является пакетом (например, s3_unarchive)
  ansistrano_gcs_region: eu-west-1 # https://cloud.google.com/storage/docs/bucket-locations
  # Необязательные переменные, по умолчанию опускаются
  ansistrano_gcs_access_key: YOUR_GCS_ACCESS_KEY # перейдите в облачную консоль > Хранение > Настройки > Совместимость
  ansistrano_gcs_secret_key: YOUR_GCS_SECRET_KEY

  # Хуки: пользовательские задачи, если они вам нужны
  ansistrano_before_setup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-before-setup-tasks.yml"
  ansistrano_after_setup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-after-setup-tasks.yml"
  ansistrano_before_update_code_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-before-update-code-tasks.yml"
  ansistrano_after_update_code_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-after-update-code-tasks.yml"
  ansistrano_before_symlink_shared_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-before-symlink-shared-tasks.yml"
  ansistrano_after_symlink_shared_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-after-symlink-shared-tasks.yml"
  ansistrano_before_symlink_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-before-symlink-tasks.yml"
  ansistrano_after_symlink_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-after-symlink-tasks.yml"
  ansistrano_before_cleanup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-before-cleanup-tasks.yml"
  ansistrano_after_cleanup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-after-cleanup-tasks.yml"

{{ playbook_dir }} — это переменная Ansible, которая хранит путь к текущему плейбуку.

Развертывание

Чтобы развернуть с помощью Ansistrano, вам нужно выполнить несколько шагов:

Создайте новый файл hosts. Проверьте документацию по инвентарю Ansible для получения помощи. Этот файл идентифицирует все хосты для развертывания. Для многоэтапных сред проверьте Многоэтапные среды.
Создайте новый плейбук для развертывания вашего приложения, например, deploy.yml
Настройте переменные роли (см. Переменные роли)
Включите роль ansistrano.deploy как часть плей
Запустите плейбук развертывания

ansible-playbook -i hosts deploy.yml

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

-- /var/www/my-app.com
|-- current -> /var/www/my-app.com/releases/20100509145325
|-- releases
|   |-- 20100509145325
|-- shared

-- /var/www/my-app.com
|-- current -> /var/www/my-app.com/releases/20100509150741
|-- releases
|   |-- 20100509150741
|   |-- 20100509145325
|-- shared

-- /var/www/my-app.com
|-- current -> /var/www/my-app.com/releases/20100512131539
|-- releases
|   |-- 20100512131539
|   |-- 20100509150741
|   |-- 20100509145325
|-- shared

Параллельные развертывания

Чтобы предотвратить разные временные метки, когда вы развертываете на нескольких серверах, используя опцию serial, вам нужно установить переменную ansistrano_release_version.

ansible-playbook -i hosts -e "ansistrano_release_version=`date -u +%Y%m%d%H%M%SZ`" deploy.yml

Откат

Чтобы откатиться с Ansistrano, вам нужно настроить развертывание и запустить плейбук отката.

ansible-playbook -i hosts rollback.yml

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

Переменные, которые вы можете настраивать в роли отката, меньше, чем в роли развертывания:

vars:
  ansistrano_deploy_to: "/var/www/my-app" # Основной путь для развертывания.
  ansistrano_version_dir: "releases" # Имя папки для релизов
  ansistrano_current_dir: "current" # Имя символической ссылки. Обычно вам не нужно его изменять.
  ansistrano_rollback_to_release: "" # Если указано, приложение будет откатано к этой версии релиза; иначе к предыдущему релизу.
  ansistrano_remove_rolled_back: yes # Вы можете изменить эту настройку, чтобы оставить откатный релиз на сервере для дальнейшей проверки
  ansistrano_allow_anonymous_stats: yes

  # Хуки: пользовательские задачи, если они вам нужны
  ansistrano_rollback_before_setup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-rollback-before-setup-tasks.yml"
  ansistrano_rollback_after_setup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-rollback-after-setup-tasks.yml"
  ansistrano_rollback_before_symlink_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-rollback-before-symlink-tasks.yml"
  ansistrano_rollback_after_symlink_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-rollback-after-symlink-tasks.yml"
  ansistrano_rollback_before_cleanup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-rollback-before-cleanup-tasks.yml"
  ansistrano_rollback_after_cleanup_tasks_file: "{{ playbook_dir }}/<your-deployment-config>/my-rollback-after-cleanup-tasks.yml"

Многоэтапная среда (devel, preprod, prod и т. д.)

Если вы хотите развернуть в разные среды, такие как devel, preprod и prod, рекомендуется создать разные файлы хостов. Когда вы это сделаете, вы можете указать другой файл хостов при запуске плейбука развертывания, используя параметр -i. В каждом файле хостов вы можете указать разных пользователей, пароли, параметры подключения и т.д.

ansible-playbook -i hosts_devel deploy.yml

ansible-playbook -i hosts_preprod deploy.yml

ansible-playbook -i hosts_prod deploy.yml

Хуки: пользовательские задачи

Вам обычно нужно перезагрузить ваш веб-сервер после шага Symlink, загрузить ваши зависимости перед Code update или даже сделать это в производственной среде перед Symlink. Поэтому, чтобы выполнить ваши пользовательские задачи, у вас есть хуки, которые Ansistrano выполнит до и после каждого из трех основных шагов. Это главное преимущество перед другими аналогичными ролями развертывания.

-- /my-local-machine/my-app.com
|-- hosts
|-- deploy.yml
|-- my-custom-tasks
|   |-- before-code-update.yml
|   |-- after-code-update.yml
|   |-- before-symlink.yml
|   |-- after-symlink.yml
|   |-- before-cleanup.yml
|   |-- after-cleanup.yml

Например, чтобы перезапустить apache после шага Symlink, мы добавим в after-symlink.yml

- name: Перезагрузка Apache
  service: name=httpd state=reloaded

Вопрос: Где вы добавите отправку уведомления по электронной почте после развертывания?
Вопрос: (для разработчиков PHP и Symfony) Где вы очистите кеш?

Вы можете указать файл пользовательских задач для до и после каждого шага, используя переменные роли ansistrano_before_*_tasks_file и ansistrano_after_*_tasks_file. См. "Переменные роли" для получения дополнительной информации.

Переменные в пользовательских задачах

При написании ваших файлов пользовательских задач вам могут понадобиться некоторые переменные, которые делает доступными Ansistrano:

{{ ansistrano_release_path.stdout }}: Путь к текущему развертыванию (вероятно, это то, что вы будете использовать чаще всего)
{{ ansistrano_releases_path }}: Путь к папке релизов
{{ ansistrano_shared_path }}: Путь к общей папке (где могут храниться общие активы релизов)
{{ ansistrano_release_version }}: Относительное имя директории для релиза (по умолчанию соответствует текущей метке времени в UTC)

Удаление старых релизов

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

После развертывания, если вы хотите удалить старые релизы, просто установите переменную ansistrano_keep_releases в общее количество релизов, которые вы хотите сохранить.

Давайте посмотрим на три развертывания с конфигурацией ansistrano_keep_releases: 2:

-- /var/www/my-app.com
|-- current -> /var/www/my-app.com/releases/20100509145325
|-- releases
|   |-- 20100509145325
|-- shared

-- /var/www/my-app.com
|-- current -> /var/www/my-app.com/releases/20100509150741
|-- releases
|   |-- 20100509150741
|   |-- 20100509145325
|-- shared

-- /var/www/my-app.com
|-- current -> /var/www/my-app.com/releases/20100512131539
|-- releases
|   |-- 20100512131539
|   |-- 20100509150741
|-- shared

Посмотрите, как релиз 20100509145325 был удален.

Пример плейбука

В папке example вы можете увидеть пример проекта, который показывает, как развернуть небольшое приложение с помощью Ansistrano.

Чтобы запустить его, вам нужно иметь Vagrant и установленные роли ansistrano. Пожалуйста, проверьте https://www.vagrantup.com для получения дополнительной информации о Vagrant и нашей разделе Установка.

$ cd example/my-playbook
$ vagrant up
$ ansible-playbook -i hosts deploy.yml

И после выполнения этих команд файл index.html, расположенный в папке my-app, будет развернут на обеих vagrant-боксах.

Чтобы протестировать плейбук для отката, вам нужно запустить deploy.yml как минимум дважды (чтобы было что откатывать). Как только это будет сделано, вам просто нужно выполнить

$ ansible-playbook -i hosts rollback.yml

Вы можете проверить более сложные примеры в папке test, которые выполняются против Travis-CI.

Примеры проектов

Мы добавили поддержку Ansistrano для других проектов, над которыми мы работаем.

LastWishes: Пример приложения на PHP с ориентированным на домен проектированием: https://github.com/dddinphp/last-wishes

В качестве примера посмотрите журнал выполнения развертывания LastWishes:

PLAY [Развертывание приложения последнего желания на мой сервер] ************************************

СБОР ФАКТОВ ***************************************************************
ok: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Убедитесь, что база развертывания существует] ***
ok: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Убедитесь, что папка релизов существует] ***
ok: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Убедитесь, что папка общих элементов существует] ***
ok: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Получить временную метку релиза] ***********
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Получить путь релиза] ****************
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Получить путь релизов] ***************
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Получить общий путь (в случае rsync)] ***
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Rsync файлы приложения на удаленную общую копию (в случае rsync)] ***
changed: [quepimquepam.com -> 127.0.0.1]

ЗАДАЧА: [ansistrano.deploy | Развертывание существующего кода на серверах] ***
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Развертывание существующего кода на удаленных серверах] ***
skipping: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Обновление удаленного репозитория] ********
skipping: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Экспорт копии репозитория] *******
skipping: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Развертывание кода на серверах] *****
skipping: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Копирование версии релиза в файл REVISION] ***
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Обновление кода релиза] *****
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Изменение символической ссылки на новый релиз] ***
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Перезагрузка Apache] *******************
changed: [quepimquepam.com]

ЗАДАЧА: [ansistrano.deploy | Очистка релизов] ***************
skipping: [quepimquepam.com]

ИТОГИ ИГР ************************************************************
quepimquepam.com           : ok=14   изменено=10   недоступно=0    неудачно=0