Guía de Empaquetado de Colección Ansible
Adelante
Colecciones Ansible son unidades empaquetadas del contenido Ansible, incluyendo módulos y otros tipos de complementos. Muchos Complementos Ansible están escritos en Python o Powershell.
Algunas colecciones además están incluidas en la colección ansible
de la Comunidad Ansible, lo cual está empaquetado en Fedora. Todas las colecciones, sin embargo o no están incluidas en el paquete ansible
, PUEDE estar empaquetado en Fedora.
ansible
depende de ansible-core
, que contiene el motor central y los programas CLI (por ejemplo, ansible
, ansible-playbook
). El paquete ansible
tiene un ciclo de publicación diferente al de las colecciones individuales, y puede contener versiones antiguas de los componentes individuales. ansible
instala las colecciones en un espacio de nombres diferente y se puede instalar en paralelo con las colecciones individuales. El motor de Ansible busca primero las colecciones en el directorio de colecciones independientes.
Consulta Changes/Ansible5 para obtener más información sobre la división entre ansible
y ansible-core
.
Nombrando
Los paquetes de colección DEBEN llamarse ansible-collection-NAMESPACE-NAME
. Por ejemplo, el paquete de la colección community.general
se llama ansible-collection-community-general
.
Fuente de la colección
El código fuente de la colección DEBE descargarse de la forja Git respectiva de la colección/otro repositorio SCM. Aunque los archivos tar publicados en Ansible Galaxy contienen todo el código fuente Python/Powershell de la colección, así como algunos archivos de desarrollo, no incluyen la configuración de compilación galaxy.yml
ni los archivos de desarrollo (por ejemplo, pruebas unitarias) que el autor decida eliminar. Tenga en cuenta que los requisitos de la colección de la Comunidad Ansible exigen que las colecciones etiqueten las versiones en un repositorio SCM público.
Los paquetes de colecciones DEBERÍAN utilizar %{ansible_collection_url NAMESPACE NAME}
como URL:
del paquete. Esto apunta a la página de inicio de la colección en Ansible Galaxy.
Dependencias
Construido
Las colecciones DEBEN tener BuildRequires: ansible-packaging
. ansible-packaging
proporciona macros y un generador de dependencias para empaquetar las colecciones de Ansible. También incluye ansible-core
, por lo que BuildRequires: ansible-core
NO DEBE añadirse manualmente.
Tiempo de ejecución
El generador de dependencias generará la dependencia apropiada del motor de Ansible. Esto garantiza la compatibilidad con Fedora 35, que contiene el paquete clásico ansible
2.9 (en lugar del paquete de colecciones) y ansible-core
. Ambas versiones del motor Ansible soportan colecciones, pero no son instalables en paralelo. Los paquetes NO DEBEN Requerir
ansible-core
o ansible
manualmente, a menos que se sepa que requieren una versión específica, en cuyo caso se deben usar las restricciones de versión apropiadas.
El generador de dependencias también gestiona las dependencias entre colecciones.
Dependencias externas de los plugins
Las colecciones de Ansible pueden contener varios plugins que tienen varias dependencias externas. La guía de desarrollo de Ansible https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code [ordena] que los plugins fallen limpiamente si estas dependencias no están instaladas. Muchas veces, las dependencias externas sólo son necesarias para un pequeño subconjunto de la colección que puede o no ser ampliamente utilizado. Por lo tanto, los paquetes de la colección DEBERÍAN depender débilmente de estas bibliotecas externas, es decir, utilizar Recommends en lugar de Requires.
Las dependencias de módulos sólo son necesarias en el nodo destino, no en el nodo controlador. Por lo tanto, los paquetes de recolección NO DEBERÍAN depender de estas dependencias en absoluto, ni débil ni fuertemente. Los usuarios son responsables de instalar estas dependencias en el host de destino. Los módulos destinados a ser utilizados con delegate_to: localhost
son una excepción a esta regla.
La situación es un poco diferente para los plugins de controlador, como los plugins de filtro, los plugins de búsqueda, los plugins de conexión o los plugins de inventario. Las colecciones PUEDEN añadir Recommends
para las dependencias de los plugins controladores. Sin embargo, los empaquetadores deben ser discretos a la hora de añadir cualquier tipo de dependencia y sólo hacerlo cuando sea necesario para la funcionalidad central de la colección. Por ejemplo, tiene sentido que ansible-collection-community-docker
recomiende python3-docker
, pero no tiene sentido que la colección ansible-collection-community-general, más amplia y general, recomiende python3-redis
para el complemento de búsqueda redis
. Esta directriz pretende evitar que se amplíen los paquetes de la colección. ansible-core
y ansible
siguen este mismo principio.
Construcción e instalación
Para construir el artefacto de colección, los paquetes DEBEN usar %ansible_collection_build
en %build
. Para instalar el artefacto, se DEBE utilizar %ansible_collection_install
en %install
.
Los empaquetadores DEBERÍAN utilizar %files -f %{ansible_collection_filelist}
para instalar la colección. La %{ansible_collection_filelist}
se rellena con %ansible_collection_install
.
Pruebas Unitarias
Según las Directrices generales de empaquetado de Fedora, los paquetes de recolección DEBERÍAN ejecutar pruebas unitarias ascendentes en %check
si es práctico. Las pruebas de integración son imposibles de ejecutar en el entorno de compilación RPM. Para ejecutar pruebas unitarias, las colecciones DEBEN BuildRequire
ansible-packaging-tests
, que extrae las dependencias necesarias. Algunas colecciones tienen otras dependencias de pruebas, que normalmente se especifican en tests/unit/requirements.txt
. Hay que añadirlas manualmente. La macro %ansible_test_unit
DEBE utilizarse para ejecutar pruebas.
Compatibilidad EPEL
Actualmente es imposible ejecutar pruebas unitarias en EPEL 8 y 9. ansible-core en RHEL 8 y 9 se construyen contra pilas python alternativas para las que no están disponibles las dependencias de prueba necesarias. El resto de estas directrices son aplicables a EPEL 8 y 9, y |
Archivos innecesarios
Por defecto, las colecciones se envían con todos los archivos de la raíz del repositorio, a menos que se excluyan manualmente. Por lo tanto, muchas colecciones contienen archivos de desarrollo no deseados por los usuarios.
Los empaquetadores DEBERÍAN excluir estos archivos, lo que debería hacerse parcheando el galaxy.yml
de la colección para añadir estos archivos a la configuración build_ignore
. Estos archivos NO DEBERÍAN eliminarse con rm
. Consulte documentación de Ansible para obtener más información sobre la sintaxis de galaxy.yml
.
Los archivos de desarrollo más comunes son:
-
El directorio
tests
que contiene las pruebas unitarias y de integración -
Configuración del SCM, como los archivos
.gitignore
y.keep
-
Los directorios
.azure-pipelines
y.github
que contienen la configuración de IC
Estos archivos a menudo tienen que ser eliminados, ya que hay algunos problemas no resueltos con el envío de estos cambios a las colecciones de la comunidad. Estos problemas son irrelevantes en el contexto de Fedora.
Travesuras
Los complementos de Ansible no son ejecutables. Sin embargo, muchos de ellos tienen travesuras #!/usr/bin/python
por razones de legado. Estas travesuras DEBEN ser eliminados por las siguientes razones:
-
Los archivos no ejecutables no deberían tener travesuras
-
Mantener las travesuras resulta en una dependencia innecesaria en
python-unversioned-command
.
NO DEBE utilizarse %py3_shebang_fix
, ya que romperá la compatibilidad con ciertos nodos destino de Ansible. Tampoco solucionará el tema de los archivos no ejecutables.
Las travesuras se pueden quitar con:
find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' +
Documentación y Archivos de Licencia
Los archivos de licencia y documentación para las colecciones se instalan en el directorio de la colección en /usr/share/ansible
, por defecto. Los empaquetadores PUEDEN elegir entre marcar los archivos de licencia y documentación en este directorio con %license
y %doc
o añadir las rutas correctas a build_ignore
en galaxy.yml
e instalarlos en los directorios estándar. Evite duplicar estos archivos en ambos lugares.
Tenga en cuenta que algunas colecciones multi-licencia almacenan las licencias en un directorio +LICENSES
. Todo este directorio DEBE estar marcado con %license
.
Consulte en Legal docs las normas sobre licencias permitidas y la determinación del campo License:
.
Ejemplo de archivo de especificaciones
# Ejecutar pruebas sólo cuando las dependencias estén disponibles
%if %{defined fedora}
%bcond_without tests
%else
%bcond_with tests
%endif
Name: ansible-collection-community-rabbitmq
Version: 1.2.2
Release: 1%{?dist}
Summary: Colección RabbitMQ para Ansible
# plugins/module_utils/_version.py: Licencia de la Python Software Foundation versión 2
License: GPL-3.0-or-later and PSF-2.0
URL: %{ansible_collection_url community rabbitmq}
%global forgeurl https://github.com/ansible-collections/community.rabbitmq
Source0: %{forgeurl}/archive/%{version}/%{name}-%{version}.tar.gz
# Parchea galaxy.yml para excluir archivos innecesarios de la colección creada.
# Se trata de un parche sólo para versiones posteriores.
Patch0: build_ignore.patch
BuildRequires: ansible-packaging
%if %{with tests}
BuildRequires: ansible-packaging-tests
# Dependencia de test específico de colección
BuildRequires: glibc-all-langpacks
%endif
BuildArch: noarch
%description
%{summary}.
%prep
%autosetup -n community.rabbitmq-%{version} -p1
find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' +
%build
%ansible_collection_build
%install
%ansible_collection_install
%if %{with tests}
%check
%ansible_test_unit
%endif
%files -f %{ansible_collection_filelist}
%license COPYING PSF-license.txt
%doc README.md CHANGELOG.rst
%changelog
build_ignore.patch:
diff --git a/galaxy.yml b/galaxy.yml
index 0b37162..acd029a 100644
--- a/galaxy.yml
+++ b/galaxy.yml
@@ -13,3 +13,13 @@ repository: https://github.com/ansible-collections/community.rabbitmq
documentation: https://docs.ansible.com/ansible/latest/collections/community/rabbitmq/
homepage: https://github.com/ansible-collections/community.rabbitmq
issues: https://github.com/ansible-collections/community.rabbitmq/issues
+build_ignore:
+ # Remove unnecessary development files from the built package.
+ - tests
+ - .azure-pipelines
+ - .gitignore
+ # Licenses and docs are installed with %%doc and %%license
+ - PSF-license.txt
+ - COPYING
+ - README.md
+ - CHANGELOG.rst
Desglosar Macro
He aquí un breve desglose de lo que hace exactamente cada macro incluida en ansible-packaging
.
%ansible_collection_url
Utilización:
URL: %{ansible_collection_url NAMESPACE NAME}
Esta macro apunta a la página Ansible Galaxy de una colección. Se utiliza para la etiqueta URL:
en el preámbulo del archivo de especificaciones. Toma como argumentos el espacio de nombres de la colección y el nombre de la colección.
Si no se pasan argumentos a esta macro, se vuelve a los valores de %{collection_namespace}
y %{collection_name}
si están definidos en el fichero de especificaciones. Los nuevos paquetes DEBERÍAN pasar explícitamente el espacio de nombres y el nombre como argumentos. La recuperación puede ser eliminada en el futuro. Consulte la sección Legacy Macros para obtener más información.
%ansible_collection_build
Utilización:
%build
%ansible_collection_build
Esta macro simplemente ejecuta ansible-galaxy collection build
.
%ansible_collection_install
Utilización:
%install
%ansible_collection_install
Esta macro extrae el espacio de nombres de la colección, el nombre y la versión de galaxy.yml
y luego lo utiliza para ejecutar ansible-galaxy collection install
. Después de eso, se escribe %{ansible_collection_filelist}
basado en los metadatos que previamente extraído
%ansible_test_unit
Utilización:
%check
%ansible_test_unit
Esta macro analiza galaxy.yml para determinar el espacio de nombres de la colección y el nombre que se necesita para crear la estructura de directorios que ansible-test espera. Después de crear un directorio de construcción temporal con la estructura necesaria, el script ejecuta las unidades ansible-test con los argumentos proporcionados.
%{ansible_collection_filelist}
Utilización:
%files -f %{ansible_collection_filelist}
%doc ...
%license ...
Esta macro apunta a una lista de archivos que es escrita por %ansible_collection_install
. Actualmente, sólo contiene una única entrada para poseer el directorio completo de la colección en %{ansible_collections_dir}
Esta macro expande a %{_datadir}/ansible/collections/ansible_collections
. Es utilizado internamente por las otras macros. Paquetes son esperados a utilizar %ansible_collection_install
y %ansible_collection_filelist
en vez de referenciar directamente este directorio.
Macros heredadas
%{collection_namepsace}
Utilización:
%global collection_namespace NAMESPACE
Las macros ansible-packaging anteriormente requirió paquetes para establecer manualmente %collection_namespace
en especificaciones. Ahora, las macros extraen la colección de espacio de nombre desde el galaxt.yml
.
%{collection_name}
Utilización:
%global collection_name NOMBRE
Anteriormente, las macros de ansible-packaging requerían que los empaquetadores establecieran manualmente %collection_name
en los archivos de especificaciones. Ahora, las macros extraen el nombre de la colección del archivo galaxy.yml
.
%{ansible_collection_files}
Utilización:
%files
%doc ...
%license ...
%{ansible_collection_files}
Los nuevos archivos de especificaciones deben utilizar %files -f %{ansible_collection_filelist}
en lugar de esta macro. %{ansible_collection_files}
requiere configurar %collection_namespace
y %collection_name
.
Want to help? Learn how to contribute to Fedora Docs ›