Коллекции Galaxy Part 2: Автоматически обновлять свою коллекцию с действиями GitHub

Работа с Galaxy Collections (3 часть серии)

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

Мы будем построить пользовательский плагин поиска, который мы создали в Часть 1 этой серии. Окончательная установка для коллекции мы будем строить на Github Отказ

Часто при работе с большими неблагоприятными плейборами вы столкнулись с необходимостью дублировать несколько задач с слегка модифицированными параметрами, отформатировать данные аналогичным образом в разделе дискретных задач или импортировать те же роли в нескольких разных играх. Anbible 2.9, выпущенный 31 октября 2019 года, представил Коллекции которые могут быть установлены через Обязательная галактика Отказ

Коллекции — это формат распространения для любого контента, который может включать в себя PlayBooks, роли, модули и плагины.

Ранее Аналимая Galaxy была концентратором для разработанных сообществ ролей — дискретный игровой книг задач для повторного использования общих шагов конфигурации. Роль выполняет все задачи внутри нее. Теперь сообщество может загрузить коллекцию ролей, плейбов, модулей или плагинов и вызывать каждый индивидуально в своем собственном платежем, как им нравится.

• Собрание коллекции
• Файл Galaxy.yml.
• Развертывание айсовной галактики (ручной)
• Развертывание на несбетую галактику (автоматизировано)
  • Строить действие GitHub
    • Разница между приложениями GitHub и действиями GitHub
    • Как построить действие JavaScript
    • Примечание о Node_Modules
  • Использование действия GitHub
• Заворачивать

Собрание коллекции

Коллекция имеет определенную установку файлов. Ни один из этих каталогов не требуется, однако вы Должен включить Galaxy.yml файл. Anbible только принимает * .YML для Galaxy.yml файлы. Мы обсудим, что нужно вдаваться в этот файл в данный момент. Вы можете вилочную коллекцию шаблон репо здесь на Github Отказ Вы также можете генерировать структуру скелетной коллекции через команду Ansible-Galaxy Collection init Отказ Все Коллекция Ansible-Galaxy Команды требуют неизбежного 2.9+.

collection/
├── docs/
├── galaxy.yml
├── plugins/
│   ├── modules/
│   │   └── module1.py
│   ├── inventory/
│   └── .../
├── README.md
├── roles/
│   ├── role1/
│   ├── role2/
│   └── .../
├── playbooks/
│   ├── files/
│   ├── vars/
│   ├── templates/
│   └── tasks/
└── tests/

Коллекция/ Охватывает каталог, в котором мы создаем нашу коллекцию. Вы можете создать каталог внутри вашего Git Repo, но я просто позволил My Directory Director — имя верхнего уровня, поэтому все файлы внутри этой папки находятся в корневом корне. Так что мой каталог выглядит как:

docs/
galaxy.yml
plugins/
├── modules/
│   └── module1.py
├── inventory/
└── .../
README.md
roles/
├── role1/
├── role2/
└── .../
playbooks/
├── files/
├── vars/
├── templates/
└── tasks/
tests/

За исключением, нам нужно только включить файлы, которые мы используем. Мы не добавляем никаких пользовательских ролей или плейгонов к этой коллекции, просто мой обычный пользовательский github_version Плагин поиска. Итак, моя структура каталогов на самом деле должна быть только:

docs/
galaxy.yml
plugins/
├── lookup/
│   └── github_version.py
README.md
tests/

Точно так же я решим поставить всю мою документацию в readme.md, поэтому мне не нужно ничего добавлять к Документы/ каталог.

galaxy.yml
plugins/
├── lookup/
│   └── github_version.py
README.md
tests/

Файл Galaxy.yml.

Galaxy.yml Содержит всю необходимую информационную аналимую галактику для обработки, расслоения и публиковать коллекцию. Структура файла описана здесь И я рекомендую вам прочитать эту относительно короткую страницу, чтобы понять, как настроить свою коллекцию.

Давайте посмотрим, как мы настроим Galaxy.yml Для нашего github_version Коллекция плагинов:

---

# The Ansible Galaxy namespace under which this collection will be published.
# This can be a company/brand/organization or product namespace under which all content lives.
# I use my Github username.
namespace: artis3n
# The name of this collection.
name: github_version
# The current version of the collection. Update this each time you want to release a new version to Galaxy.
version: 1.0.2
# The markdown README file for the collection. Galaxy displays this on your collection page.
readme: README.md
# A list of authors who contributed to this collection. Similar to the list inside the custom plugin.
authors:
  - Ari Kalfus (@artis3n) 
# Self-explanatory. This should be a short (1-2 sentence) summary.
description: "This lookup returns the latest tagged release version of a Github repository."
# Either a single file or a list of license files.
# Note that Ansible Galaxy currently only accepts SPDX licenses - https://spdx.org/licenses/
license_file: LICENSE
# List any collections that this collection requires to be installed for it to be usable.
dependencies: { }
# Add the tags you'd like Ansible Galaxy to associate to your collection.
tags:
  - github
  - repository
  - version
# The URL to your project repository. Galaxy will link to this location.
repository: https://github.com/artis3n/github_version-ansible_plugin
# The URL to your project's documentation. Galaxy will link to this location.
documentation: https://github.com/artis3n/github_version-ansible_plugin
# The URL to your project's issue intake. Galaxy will link to this location.
issues: https://github.com/artis3n/github_version-ansible_plugin/issues

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

---

namespace: artis3n
name: github_version
version: 1.0.2
readme: README.md
authors:
  - Ari Kalfus (@artis3n) 
description: This lookup returns the latest tagged release version of a Github repository.
license_file: LICENSE
dependencies: { }
tags:
  - github
  - repository
  - version
repository: https://github.com/artis3n/github_version-ansible_plugin
documentation: https://github.com/artis3n/github_version-ansible_plugin
issues: https://github.com/artis3n/github_version-ansible_plugin/issues

Развертывание айсовной галактики (ручной)

Теперь, когда мы организовали наш плагин в коллекцию, мы можем подключить его и загрузить в галактику. Для ролей Galaxy поддерживает автоматическое импорт из репозитория GitHUB, но не для коллекций. Более того, кажется, что Galaxy предпочитает роли в комплекте в коллекцию, поскольку импорт прямой ролью теперь имеет сообщение для подшучивания для подсказки, говоря, что это устаревшая функция.

Импорт роли от GitHub: Наследие роль импорта. Не поддерживает формат коллекции. Загрузить новую коллекцию: используется для распространения размещенных галактических ролей, модулей и плагинов Galaxy.

Вместо этого мы используем Ansible-Galaxy CLI Tool для подключения нашей коллекции в архив .tar.gz, который мы загружаем в галактику. Мы можем загрузить через интерфейс UI как на скриншоте выше, но мы будем использовать инструмент CLI:).

Чтобы объединить нашу коллекцию в подготовке к загрузке, запустить:

ansible-galaxy collection build

У нашей коллекции Root Coot. Если вы успешны, вы увидите сообщение:

Created collection for artis3n.github_version at //github_version-ansible_plugin/artis3n-github_version-1.0.2.tar.gz

Обратите внимание, что версия, которую вы устанавливаете в свой Galaxy.yml включен во имя архива. Вы не должны менять название архива.

Теперь, чтобы загрузить наш пакет до аварийного Galaxy Run:

ansible-galaxy collection publish artis3n-github_version-1.0.2.tar.gz --api-key=

Ключ API можно найти в https://galaxy.ansable.com/me/preferences Отказ

В этот момент ваша коллекция опубликована и доступна на айной галактике.

Развертывание на несбетую галактику (автоматизировано)

Публикация через CLI отлично и все, но мы хотели бы автоматизировать это. В частности, при публикации нового выпуска на моем REPO GitHub, я хотел бы автоматически создавать и загружать новую версию моей коллекции до аварийной галактики. Я написал Действие GitHub сделать только это.

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

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

Действия GitHub — это рабочий процесс автоматизации, построенный непосредственно на платформу GitHub. В настоящее время они в общественной бета-версии и в целом выпускают 13 ноября 2019 года. Есть все много документации О том, как использовать действия GitHub. Существует несколько основных концепций, которые мы должны исследовать в этой статье, но вы, вероятно, придется часто ссылаться на эту документацию, при создании ваших первых нескольких действий. Есть также Github Labout Lab Для действий GitHub, который приличный. Я прошел через лабораторию обучения дважды, но заканчивался со ссылкой на всю документацию, чтобы на самом деле понять, как создать свое действие. Мы вернемся к своему действию в следующих двух разделах, что является На Github здесь Отказ

Строить действие GitHub

Мы хотим взять Ansible-Galaxy Команды из ручного раздела и запустить их автоматически в наших действиях. Вы можете создать действие GitHub в Контейнер докеров или Как JavaScript Отказ

Docker Conticers Actions Пакет вашей среды с кодом действия, создавая более последовательную и надежную единицу работы. Потребители действия не нужно беспокоиться о инструментах или зависимостях. Действия контейнера Docker выполняются только в средней среде Linux Github.

Действия JavaScript, с другой стороны, могут работать непосредственно на любом из виртуальных машин для размещенных GitHub (Linux, Windows и OSX) и отделяет код действий из среды, используемой для запуска кода. Действия JavaScript проще и выполняются быстрее, чем докеренные контейнерные действия.

Я решил написать действие JavaScript, потому что я не хотел изолировать свой код действия из среды, где он работает. Примечательно, что мне нужно прочитать в репозитории Galaxy.yml Файл для правильной упаковки и загрузки коллекции в Galaxy, и я не хочу беспокоить с динамическим монтажом этих данных в действие докера. Более того, как только Github Action выпустит 13 ноября 2019 года, пользователи будут платить за минуту времени выполнения. В каждом месяце есть щедрый свободный уровень минут в месяц, что я не ожидаю, что многие люди пойдут, но наращивают действие, которое проходит быстрее, чем он, когда контейнер казался еще одним преимуществом.

Разница между приложениями GitHub и действиями GitHub

Вы можете читать это и думать, «Действия GitHub звучат очень похоже на приложения GitHub. «Они похожи, но имеют определенные сильные стороны, которые делают друг друга лучше для разных сценариев. Взяты прямо из Документация :

Приложения GitHub:

• Пробежать настойчиво и быстро реагировать на события
• Отлично работать, когда необходимо постоянные данные
• Работать лучше всего с запросами API, которые не трудоемки
• Запустить на сервере или вычислить инфраструктуру, которую вы предоставляете

Действия GitHub:

• Обеспечить автоматизацию, которая может выполнять непрерывную интеграцию и постоянное развертывание
• Может работать прямо на виртуальной машине или в контейнерах докеров
• Может включать доступ к клону вашего репозитория, включать в себя инструменты развертывания и публикации, форматтеров кода и инструменты командной строки для доступа к вашему коду
• Не требуйте, чтобы вы развернули код или служите приложение
• Иметь простой интерфейс для создания и использования секретов, что позволяет действиям взаимодействовать с сторонним сервисами без необходимости хранить учетные данные человека, используя действие

Если вы спросите меня, Github пытается продать вам действия над приложениями, но их точки стойки. Если вы работаете на CI/CD, выбросьте свой сервер Jenkins и начните писать действия GitHub!

Как построить действие JavaScript

Действия GitHub JavaScript в настоящее время используют узел 12.x и должны быть созданы в выделенном репозитории на действие. На корне проекта создайте Action.yml и index.js файлы. Action.yml будет содержать метаданные конфигурации для этого действия, пока index.js будет выходом для кода нашего действия.

Ваш Action.yml отформатирован следующим образом:

--------
# The name of your action. This is listed on the GitHub Actions Marketplace.
name: 'Deploy Ansible Galaxy Collection'
# A description of what your action does.
description: 'Builds and deploys a Collection to Ansible Galaxy'
# Your GitHub username and, optionally, email
author: 'Artis3n '
# A map of any input parameters used by your action.
inputs:
  # The name of your input parameter.
  api_key:
    # Describe the input parameter.
    description: |
      Ansible Galaxy API key. This should be stored in a Secret on Github.
      See https://help.github.com/en/github/automating-your-workflow-with-github-actions/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables.
    # Mark whether consumers of your action must supply this parameter.
    required: true
  # A second input parameter.
  galaxy_config_file:
    description: 'A collection must have a galaxy.yml file that contains the necessary information to build a collection artifact. Defaults to "galaxy.yml" in the project root.'
    # Mutually exclusive with 'required.' Set a default value for this parameter if it is not supplied.
    default: 'galaxy.yml'
# For JavaScript actions, identify how this action should be run.
runs:
  # What Node version the action should use. As of publication, the only option is 'node12.'
  using: 'node12'
  # Point to your action's entrypoint file. I have modified it from `index.js` to `dist/index.js`. I will describe why shortly.
  main: 'dist/index.js'
# Some configurations to set for your GitHub Action Marketplace's display.
branding:
  icon: 'box'
  color: 'purple'

Мы доберемся до dist/index.js немного в мгновение. Давайте сначала создам наше index.js файл. Начнем, как с любым JavaScript с импортом для нашего файла. Обязательно Установка NPM Что вам нужно. Кроме того, вы должны NPM установить Некоторое количество библиотек действий GitHub, доступно в Действия Toolkit Отказ Это набор библиотек, предоставленных GitHub, чтобы облегчить работу с действиями.

Скорее всего, вы всегда будете работать NPM Установите @ Действия/CORE для Основная библиотека :

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

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

const core = require('@actions/core');

const apiKey = core.getInput('api_key', { required: true });
const galaxy_config_file = core.getInput('galaxy_config_file') || 'galaxy.yml';

Вы также будете использовать Core потерпеть неудачу на работу по ошибкам:

const core = require('@actions/core');

try {
  // Stuff
} catch (error) {
  core.setFailed(error.message);
}

В инструментарии действий много полезных библиотек, поэтому я рекомендую вам просматривать этот репозиторий. Другая библиотека действий, которую нам нужна для нашей Galaxy Raphload, является Действия/Exec библиотека:

Обеспечивает функции для инструментов CLI и вывода процесса.

Мы используем эту библиотеку, чтобы вызвать нашу Ansible-Galaxy Команды:

const exec = require('@actions/exec');

async function buildCollection(namespace, name, version, apiKey) {
    await exec.exec('ansible-galaxy collection build');
    await exec.exec(`ansible-galaxy collection publish ${namespace}-${name}-${version}.tar.gz --api-key=${apiKey}`)
}

Если вам нужно, вы также можете Вывод команды Capture EXEC Отказ Я решил, чтобы Действие не удалось, если эти команды ошибки:

buildCollection(namespace, name, version, apiKey)
    .then(() => { })
    .catch(err => core.setFailed(err.message));

У нас есть все вещи наших действий, давайте поставим его вместе. Когда это действие срабатывает, я хочу прочитать репозиторий Galaxy.yml Файл, извещайте пространство имен коллекции, имя и версию и версию и используйте ключ API Galaxy Poverizer, чтобы объединить и опубликовать эту версию на аварийную галактику. С нашими библиотеками действия это выглядит:

const core = require('@actions/core');
const exec = require('@actions/exec');
const yaml = require('js-yaml');
const fs = require('fs');

try {
    const apiKey = core.getInput('api_key', { required: true });
    const galaxy_config_file = core.getInput('galaxy_config_file') || 'galaxy.yml';
    const galaxy_config = yaml.safeLoad(fs.readFileSync(galaxy_config_file, 'utf8'));

    const namespace = galaxy_config.namespace;
    const name = galaxy_config.name;
    const version = galaxy_config.version;

    if (namespace === undefined || name === undefined || version === undefined) {
        const error = new Error("Missing require namespace, name, or version fields in galaxy.yml");
        core.error(error.message);
        core.setFailed(error.message);
    }

    core.debug(`Building collection ${namespace}-${name}-${version}`);
    buildCollection(namespace, name, version, apiKey)
        .then(() => core.debug(`Successfully published ${namespace}-${name} v${version} to Ansible Galaxy.`))
        .catch(err => core.setFailed(err.message));
} catch (error) {
    core.setFailed(error.message);
}

async function buildCollection(namespace, name, version, apiKey) {
    await exec.exec('ansible-galaxy collection build');
    await exec.exec(`ansible-galaxy collection publish ${namespace}-${name}-${version}.tar.gz --api-key=${apiKey}`)
}

Вы можете увидеть, что я добавил дополнительную проверку ошибок. Кроме того, все следует объяснить предыдущими пунктами.

С этим мы можем объединить наш код для освоения и публиковать выпуск. Когда есть репозиторий имеет Action.yml Файл, Github добавит новый контент в форму публикации.

Примечание о Node_Modules

Важно : GitHub загружает каждое действие в рабочем процессе во время выполнения и выполняет его в качестве полного пакета кода, прежде чем вы сможете использовать команды Workflow, такие как Беги Взаимодействовать с виртуальной машиной. Это означает, что вы должны включить любые пакетные зависимости, такие как @ Действия/ядро или что-нибудь еще NPM установить Эд, в вашем репозитории. У вас есть два варианта:

1. Включить Node_Modules в вашем репозитории.
2. Использовать Zeit/NCC Чтобы подключить свой код и укажите свой Action.yml Выходная точка в подключенный файл.

Я выбрал последнее. Я добавил Zeit/NCC к моему package.json :

"devDependencies": {
    "@zeit/ncc": "^0.20.5"
  }

и добавил команду для моих сценариев:

"scripts": {
    "build": "ncc build index.js -o dist"
  },

NPM запустить сборку Теперь упадет мои зависимости и index.js Файл и напишите файл в dist/index.js Отказ В моем Action.yml Я установил свой GitHub Action для использования в комплекте:

runs:
  using: 'node12'
  main: 'dist/index.js'

Использование действия GitHub

В то время как рабочие процессы действий написаны на YAML и могут быть созданы в местном текстовом редакторе, я рекомендую построить рабочие процессы на GitHub. Редактор GitHub предоставляет автоматически полные опции и документацию на боковую панель, которые я нашел очень полезно, чтобы обратиться во время работы над рабочим процессом. Чтобы запустить рабочий процесс действий GitHub в вашем репозитории, вы должны создать рабочий процесс под ..Github/Workflows/ Отказ Вы начинаете рабочий процесс, давая ему имя. Это то, что появится на вкладке «Действия вашего репозитория», когда рабочий процесс срабатывает:

name: Ansible Galaxy

Далее давайте укажем, когда этот рабочий процесс должен быть запущен. Мы используем на Ключевое слово, которое занимает почти все событие, которое происходит на Github. Вы можете вызвать действия на основе толчок ES, по созданию pull_request S, и больше. Вы также можете условно запускать рабочий процесс на основе определенного поведения мероприятия, например, Только когда создается запрос на тягу, но не при редактировании, объединении или закрыто.

Мы хотим, чтобы этот рабочий процесс запущен только тогда, когда новые выпуски публикуются, что выглядит как:

on:
  release:
    types:
      - published

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

jobs:
  deploy:

Вы должны указать, какой тип виртуальной машины для запуска задания. Вы делаете это с запускать на ключевое слово. Поддерживаемые операционные системы можно найти здесь Отказ Каждая задания работает со свежим экземпляром виртуальной среды.

runs-on: ubuntu-latest

Затем вы перечислите шаги, выполнит работу. GitHub предоставляет несколько шагов загрузки для общих языков программирования. Так как нам нужен python, мы вызываем Действия/Setup-Python действие. Если ваш рабочий процесс должен получить доступ к содержимому вашему репозиторию, вы можете использовать Действия/Оформить заказ действие. Вы вызываете еще одно действие в вашем рабочем процессе с использует ключевое слово. В противном случае вы можете запустить пользовательские команды оболочки с бегать ключевое слово. Здесь мы используем свое действие GitHub для развертывания на айсовную галактику.

steps:
    - uses: actions/checkout@v1
    - name: Set up Python 3
      uses: actions/setup-python@v1
      with:
        python-version: 3.6

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install --upgrade ansible
    - name: Report Ansible version
      run: ansible --version

    - name: Deploy the collection
      uses: artis3n/ansible_galaxy_collection@v1
      with:
        api_key: ${{ secrets.GALAXY_API_KEY }}

В приведенных выше шагах мы проверяем репозиторий и устанавливаю Python, Pip и Anbible. Затем мы призываем нашу действие GitHub, чтобы опубликовать галактику, artis3n/ansible_galaxy_collection. . Это действие принимает необходимый входной параметр, который мы указываем с с Отказ

Вы заметите, что я предоставляю переменную к API_KEY. Параметр из чего-то под названием «Секреты. «Это новая возможность в Github с внедрением действий. Вы можете Хранить зашифрованные секретные значения В вашем репо зашифровано через NaCl Отказ Наше ansible_galaxy_collection Действие требует вашей Ansible Galaxy API-ключ. Храните его в секретах репо и ссылайтесь на его рабочий процесс через $ {{Секреты. <Секретное имя>}} Отказ Секреты не передаются вилкам вашего репозитория.

Вы также заметите, что я запираю свои действия к определенной основной версии ( @ v1 ). Конвенция с действиями GitHub состоит в том, чтобы указать конкретную основную версию. Содержание действий опубликует несовершеннолетние и патч-обновления для своих действий, и ваш рабочий процесс будет использовать последнюю подходящую под одну и ту же основную версию. Сопровождающие несут ответственность за обновление своих тегов соответствующим образом.

Мы видим, что полный рабочий процесс, требующий понимания много документации и ключевых слов, довольно коротко, чтобы написать:

name: Ansible Galaxy

on:
  release:
    types:
      - published

jobs:
  deploy:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Set up Python 3
      uses: actions/setup-python@v1
      with:
        python-version: 3.6

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install --upgrade ansible
    - name: Report Ansible version
      run: ansible --version

    - name: Deploy the collection
      uses: artis3n/ansible_galaxy_collection@v1
      with:
        api_key: ${{ secrets.GALAXY_API_KEY }}

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

Заворачивать

Вы можете найти свои действия, чтобы развернуть коллекцию на несбетую галактику На Github Действия Marketplace Отказ Репозиторий для моего github_version коллекция здесь Отказ Вы можете использовать эту коллекцию в своих собственных плейбораторах по Установка его из айной галактики Отказ

Я также приветствую ваш вклад на Открытая проблема в моей коллекции. Использование пользовательской коллекции довольно многословна ( lookup ('artis3n.github_version.github_version) ). Anisible требует этого формата, так как я должен сделать это менее ужасно для чтения? Моя текущая мысль — переименовать мою коллекцию на Github а затем назовите этот плагин поиска Release_version. Так что это будет вызвано как Найти (artis3n.github.release_version ') . Как вы думаете?

Работа с Galaxy Collections (3 часть серии)

Оригинал: «https://dev.to/artis3n/galaxy-collections-part-2-automatically-update-your-collection-with-github-actions-8na»