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 ansible-packaging en sí está disponible allí.

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:

  1. Los archivos no ejecutables no deberían tener travesuras

  2. 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 ›