Ansible Galaxy

Реестр Ansible Galaxy предоставляет прозрачный кеширующий прокси для galaxy.ansible.com. Метаданные коллекций проксируются с перезаписью URL, а тарболы коллекций иммутабельно кешируются при первом скачивании.

Настройка клиента

Установка коллекции через NORA:

ansible-galaxy collection install community.general \
  --server http://nora.example.com:4000/ansible/

Установка конкретной версии:

ansible-galaxy collection install community.general:==12.2.0 \
  --server http://nora.example.com:4000/ansible/

В файле ansible.cfg:

[galaxy]
server_list = nora

[galaxy_server.nora]
url = http://nora.example.com:4000/ansible/

Для AWX / Ansible Automation Platform укажите URL Galaxy-сервера http://nora.example.com:4000/ansible/ в настройках организации или проекта.

Проксирование upstream

По умолчанию NORA проксирует к публичному Ansible Galaxy (https://galaxy.ansible.com). Для использования приватного Galaxy-сервера (Automation Hub, Pulp):

export NORA_ANSIBLE_PROXY=https://hub.internal.example.com
export NORA_ANSIBLE_PROXY_AUTH=user:password

NORA перезаписывает все upstream URL в ответах метаданных, чтобы они указывали через прокси. Клиенты всегда скачивают через NORA.

config.toml:

[ansible]
enabled = true
proxy = "https://galaxy.ansible.com"
# proxy_auth = "user:pass"
proxy_timeout = 30

Переменные окружения:

Переменная	Описание	По умолчанию
NORA_ANSIBLE_ENABLED	Включить реестр Ansible Galaxy	false
NORA_ANSIBLE_PROXY	URL upstream-сервера Galaxy	https://galaxy.ansible.com
NORA_ANSIBLE_PROXY_AUTH	Аутентификация upstream (user:pass)	(нет)
NORA_ANSIBLE_PROXY_TIMEOUT	Таймаут прокси в секундах	30
NORA_ANSIBLE_METADATA_TTL	Сколько секунд закешированные метаданные считаются свежими (0 — ревалидировать всегда, -1 — не истекают)	3600
NORA_ANSIBLE_SERVE_STALE	Отдавать устаревшие метаданные из кеша, когда upstream недоступен	true
NORA_ANSIBLE_REVALIDATE	При ревалидации устаревших метаданных слать upstream условный запрос (304)	true

Возможности

Функция	Статус	Примечание
Обнаружение API	Полная	/ansible/ и /ansible/api/
Список коллекций	Полная	Короткие v3 и Pulp-пути
Детали коллекции	Полная	Перезапись URL
Список версий	Полная	С пагинацией
Детали версии	Полная	Проверки курирования
Скачивание тарбола	Полная	Иммутабельный кеш, пути /download/ и /artifacts/
Курирование тарболов	Полная	Чёрный/белый списки с проверкой целостности
Публикация коллекции	—	Только прокси (чтение)

Эндпоинты

Путь	Метод	Описание
/ansible/	GET	Обнаружение API (available_versions)
/ansible/v3/collections/	GET	Список коллекций
/ansible/v3/collections/{ns}/{name}/	GET	Детали коллекции
/ansible/v3/collections/{ns}/{name}/versions/	GET	Список версий (с пагинацией)
/ansible/v3/collections/{ns}/{name}/versions/{ver}/	GET	Детали версии с download_url
/ansible/download/{ns}-{name}-{ver}.tar.gz	GET	Скачивание тарбола коллекции

Полные Pulp-пути (/ansible/api/v3/plugin/ansible/content/published/collections/index/...) также поддерживаются как алиасы.

Поведение кеширования

• Метаданные (список коллекций, детали, версии): кешируются по TTL (NORA_ANSIBLE_METADATA_TTL, по умолчанию 3600 секунд). Пока кеш свежий — отдаются из локального хранилища, при устаревании ревалидируются с upstream (условным запросом, если включён NORA_ANSIBLE_REVALIDATE), а не запрашиваются при каждом запросе. Ответы несут Cache-Control: public, max-age=60, must-revalidate.
• Тарболы: кешируются при первом скачивании с Cache-Control: public, max-age=31536000, immutable. Последующие запросы обслуживаются из локального хранилища без обращения к upstream.

Ограничения именования

Имена пространств имён и коллекций Ansible Galaxy соответствуют шаблону [a-z0-9_]+ — только буквенно-цифровые символы и подчёркивания. Дефисы не допускаются в именах (они используются как разделители в именах файлов тарболов).

Формат имени тарбола: {namespace}-{name}-{version}.tar.gz, например community-general-12.2.0.tar.gz.

Известные ограничения

• Только прокси: публикация коллекций через NORA не поддерживается. Используйте ansible-galaxy collection publish напрямую с Galaxy или Automation Hub.
• Отключён по умолчанию. Установите NORA_ANSIBLE_ENABLED=true для активации.
• Офлайн-режим для метаданных работает по принципу best-effort: если upstream недоступен, но метаданные есть в кеше, NORA отдаёт устаревшую копию (HTTP 200 с заголовком X-Nora-Stale: true) — включено по умолчанию (serve_stale, NORA_ANSIBLE_SERVE_STALE). Код 502 возвращается, только если кеша нет вовсе или serve_stale отключён.
• Тарболы кешируются навсегда после первого скачивания. Для принудительного обновления удалите файл из хранилища (ansible/download/{filename}).