Ir al contenido
Instalar

volant galaxy

Las opciones de ansible-galaxy, comprobadas por el propio Volant, mientras sus subcomandos se vuelven nativos uno a uno.

volant galaxy acepta los subcomandos y opciones de ansible-galaxy de ansible-core 2.19.12, así que los scripts y trabajos de CI escritos para él conservan sus líneas de comandos. Se está reescribiendo en Volant, sin el runtime de Python. Hoy lee las opciones y hace las comprobaciones que ansible-galaxy hace primero, y luego rechaza el subcomando hasta que llegue su versión nativa.

Ventana de terminal
volant galaxy collection <download|init|build|publish|install|list|verify> [OPTIONS]
volant galaxy role <init|remove|delete|list|search|import|setup|info|install> [OPTIONS]

Todos los subcomandos aceptan -s/--server, --token/--api-key, -c/--ignore-certs, --timeout y -v, que se puede repetir. collection download y collection install aceptan además --clear-response-cache y --no-cache. Una opción desconocida, o un valor del tipo equivocado, sale con 2 e imprime el uso. volant galaxy --version imprime el bloque de versión de ansible-galaxy.

Van antes de cualquier trabajo, con los mensajes y códigos de salida de ansible-galaxy:

Caso Mensaje Salida
collection install con nombres y -r [ERROR]: The positional collection_name arg and --requirements-file are mutually exclusive. 1
collection install o download sin ninguno de los dos [ERROR]: You must specify a collection name or a requirements file. 1
-r nombra un archivo que no existe [ERROR]: The requirements file '<path>' does not exist. 1
role install sin nombre ni -r [ERROR]: - you must specify a user/role name or a roles file 5
role install -r con un archivo que no termina en .yml o .yaml [ERROR]: Invalid role requirements file, it must end with a .yml or .yaml extension 1
role list sin ninguna ruta de roles existente [WARNING]: - the configured path <path> does not exist. por cada ruta, y después [ERROR]: - None of the provided paths were usable. Please specify a valid path with --roles-path 5

Cuando ninguna ruta de colecciones configurada está bajo el PATH de collection install -p PATH, el comando imprime primero el aviso de ansible-galaxy: [WARNING]: The specified collections path '<PATH>' is not part of the configured Ansible collections paths '<paths>'. The installed collection will not be picked up in an Ansible run, unless within a playbook-adjacent collections directory. El directorio collections/ del runtime, que Volant añade al final de la ruta de colecciones, no aparece en <paths>.

collection install instala de forma nativa un tarball de colección: volant galaxy collection install acme-demo-1.0.0.tar.gz -p DIR. El nombre y la versión vienen del MANIFEST.json del tarball, no del nombre del archivo. La colección va bajo DIR/ansible_collections/<namespace>/<name>, o bajo la primera ruta de colecciones sin -p. Solo se escriben los archivos que lista FILES.json, cada uno comprobado antes contra su SHA-256. Un archivo queda en 0644, o en 0755 cuando el archivo comprimido lo marca como ejecutable. Una entrada que acabaría fuera de la colección se rechaza, igual que un enlace que apunta fuera de ella. Una instalación que falla no deja ninguna colección a medio escribir. La salida, los mensajes y los códigos de salida son los de ansible-galaxy. Una colección ya instalada en la misma versión da Nothing to do. All requested collections are already installed. If you want to reinstall them, consider using –force., y --force la vuelve a instalar sobre el árbol anterior. Cuando PATH/ansible_collections ya existe, el aviso de -p dice que la ruta appears to be part of the pip Ansible package, como lo dice ansible-galaxy.

collection install acepta también un repositorio git: git+<url>, con ,<ref> para una rama, una etiqueta o un commit, HEAD por defecto, y #/<subdir> para una colección que no está en la raíz del repositorio, como git+https://host/org/repo.git,v1.0.0 o git+file:///work/mono/.git#/collections/demo. En un archivo de requisitos es una entrada con type: git, cuya version es la referencia. Volant ejecuta el git del sistema: un clon superficial para HEAD, uno completo con checkout si no, y luego instala el checkout como un árbol de código. Un repositorio sin colección en la raíz instala cada colección de sus subdirectorios directos. Si una colección depende de una URL git+, ese repositorio también se clona, salvo con --no-deps. Lo que viene de un repositorio no tiene versión que comparar, así que se reinstala en cada ejecución. Una versión que no sigue SemVer detiene la instalación con Invalid version found for the collection, salida 1. Los mensajes de git llegan a la terminal, como con ansible-galaxy. Una contraseña en la URL se sustituye por ******** en todos los mensajes. Sin git en el PATH, el comando falla con Could not find git executable to extract the collection from the Git repository, salida 1.

Las URL de tarballs, los directorios de espacio de nombres y las firmas se rechazan hasta que sean nativos: [ERROR]: volant galaxy collection install from a URL or a namespace directory is not supported yet, o with signatures, salida 1.

collection init <namespace>.<name> [--init-path DIR] [--collection-skeleton DIR] [-e VARS] [-f] escribe una colección nueva en DIR/<namespace>/<name>, ./ por defecto, e imprime - Collection <namespace>.<name> was created successfully. Sin esqueleto, escribe el esqueleto por defecto de ansible-core 2.19.12: galaxy.yml, README.md, meta/runtime.yml, plugins/README.md y los directorios vacíos docs/ y roles/. --collection-skeleton, o GALAXY_COLLECTION_SKELETON, indica en su lugar un directorio de esqueleto que copiar. Sus archivos .j2 se renderizan con --extra-vars y pierden la extensión, salvo bajo playbooks/*/templates y roles/*/templates. Sus enlaces siguen siendo enlaces, y lo que coincide con GALAXY_COLLECTION_SKELETON_IGNORE se omite. Un directorio de colección que ya existe es un error salvo con -f, que primero lo vacía. Los mensajes y los códigos de salida son los de ansible-galaxy.

collection build [PATH] [--output-path DIR] [-f] convierte un árbol de código con un galaxy.yml, . por defecto, en <namespace>-<name>-<version>.tar.gz dentro de DIR, ./ por defecto, e imprime Created collection for <namespace>.<name> at <path>. galaxy.yml necesita namespace, name, version, readme y authors; una clave que falta, o un galaxy.yml ausente, falla con el mensaje de ansible-galaxy. El tarball contiene MANIFEST.json, FILES.json y el árbol, sin lo que ansible-galaxy deja fuera: galaxy.yml, .git y los demás directorios de control de versiones, __pycache__, *.pyc, *.retry, tests/output, los artefactos anteriores de la colección y lo que lista build_ignore. Un archivo queda en 0644, o en 0755 cuando su propietario puede ejecutarlo; un enlace dentro del árbol sigue siendo un enlace, y uno a un directorio de fuera se salta con un aviso. Un artefacto existente es un error salvo con -f. Volant escribe todas las horas como 0 y todos los propietarios como root, así que construir dos veces el mismo árbol da los mismos bytes; ansible-galaxy pone la hora actual. Un galaxy.yml con una clave manifest: se rechaza por ahora.

collection install DIR instala un árbol de código del mismo modo, sin tarball, e imprime Created collection for <namespace>.<name>:<version> at <path> entre sus líneas Installing e installed successfully. collection download construye un árbol de código en la carpeta de descarga.

collection install acepta también nombres, con un rango si hace falta: demo.base, demo.base:1.0.0, "demo.base:>=1.0.0,<2.0.0", y las entradas de -r. Cada nombre se resuelve contra los servidores con sus dependencias, cada una en la versión más alta que cumple todos los rangos pedidos, retrocediendo cuando dos rangos chocan. Las versiones preliminares solo cuentan con --pre o cuando se nombran exactamente. Cada tarball se descarga, se comprueba contra el SHA-256 que da el servidor y se desempaqueta como arriba. Una colección instalada desde un servidor recibe también ansible_collections/<namespace>.<name>-<version>.info/GALAXY.yml, que anota su origen. Una colección ya instalada en una versión que encaja se conserva: '<name>:<version>' is already installed, skipping.

-n omite las dependencias, -U lleva las colecciones instaladas a la versión más nueva del rango, -f reinstala las colecciones pedidas y --force-with-deps también sus dependencias, -i sigue tras una instalación fallida con un aviso, y --offline no consulta ningún servidor. Cuando ningún conjunto de versiones cumple todos los rangos, el comando falla con el mensaje de ansible-galaxy, que lista los rangos y termina con una pista sobre --pre; los objetos de Python que ansible-galaxy imprime después de esa pista se omiten.

Descargar para una instalación sin conexión

Sección titulada «Descargar para una instalación sin conexión»

collection download resuelve las colecciones pedidas con sus dependencias, como install, y guarda cada tarball en la carpeta que nombra -p, ./collections por defecto. Después escribe allí un requirements.yml que lista los tarballs por nombre de archivo, con sus versiones. En una máquina sin red, volant galaxy collection install --offline -r requirements.yml ejecutado desde esa carpeta los instala sin consultar ningún servidor. Los nombres de archivo se leen desde el directorio de trabajo, como los lee ansible-galaxy. -n deja fuera las dependencias, y -r y --pre funcionan como en install. Con --offline, un nombre que ningún tarball aporta, o una dependencia que no está instalada, falla con el mensaje del resolvedor.

collection list [NAME] [-p PATH]... [--format human|json|yaml] imprime, por cada directorio de -p y de la ruta de colecciones que contiene colecciones, un bloque # <path>/ansible_collections con el nombre y la versión de cada colección, siendo la versión * cuando la colección no tiene MANIFEST.json. Las columnas son tan anchas como el nombre y la versión más largos, como las rellena ansible-galaxy. --format json imprime {"<path>": {"<namespace>.<name>": {"version": "<version>"}}} en una línea, y --format yaml lo mismo en YAML. Un -p que no existe da un aviso; cuando ninguna ruta se puede leer, el comando falla con la salida 5. ansible-galaxy lista también la colección que ansible-core guarda en su propio paquete de Python, ansible._protomatter; Volant, que no tiene ese paquete, no la lista.

collection verify NAME... [-p PATH] [--offline] comprueba cada colección instalada: MANIFEST.json, luego FILES.json contra el hash que da el manifiesto, luego cada archivo contra el suyo, y luego el árbol en busca de archivos y directorios que FILES.json no lista, salvo *.pyc. Cada diferencia se lista bajo Collection <name> contains modified content in the following files:, y el comando sale con 1. Sin --offline se descarga el tarball del servidor de la misma versión y su MANIFEST.json es la referencia; con él, lo es el instalado. Una colección no instalada, o sin MANIFEST.json, es un error; -i convierte los errores en avisos.

role install NAME... [-p PATH] [-r FILE] instala cada rol en la primera ruta de roles: -p, o la primera configurada. Un nombre tiene la forma owner.role[,version[,name]] y se busca con la API v1 del primer servidor; sin versión, se toma la más alta que lista el servidor, luego la rama del repositorio, luego master. También se instalan una ruta a un tarball, una URL y una fuente git+; un tarball o una fuente git toma el nombre del rol del tercer campo de la línea, o de la ruta cuando ese campo está vacío. Se quita el directorio superior del archivo, y meta/.galaxy_install_info guarda la versión y la fecha de instalación. Un rol ya instalado en la misma versión se salta; en otra versión, da un aviso y se queda, salvo que --force lo reemplace. Siguen las dependencias de meta/main.yml y meta/requirements.yml, salvo con -n; --force-with-deps reemplaza las ya instaladas. Un rol que falla da un aviso, y el comando sale con 1 salvo que -i lo deje seguir. -g conserva el directorio .git de un rol git.

role list [NAME] [-p PATH] imprime cada ruta de roles como # <path>, y luego - <role>, <version> por cada rol que contiene, (unknown version) cuando el rol no tiene información de instalación. role remove NAME... [-p PATH] borra cada rol de la primera ruta de roles, con - <role> is not installed, skipping. para un directorio que no contiene ningún rol.

Los servidores vienen de -s, si no de [galaxy] server_list y de las secciones [galaxy_server.<name>] de ansible.cfg, si no de GALAXY_SERVER, https://galaxy.ansible.com por defecto. Cada variable ANSIBLE_GALAXY_* va antes que el archivo. Cada servidor acepta url, token, validate_certs y timeout. --token gana al token del archivo, -c desactiva la comprobación de certificados, y --timeout fija la espera, 60 segundos por defecto. Un servidor inalcanzable se salta con el aviso de ansible-galaxy, y se consulta el siguiente.

El token va en Authorization: Token <token> y nunca se imprime. Sin token se lee el archivo de token, GALAXY_TOKEN_PATH, por defecto <ANSIBLE_HOME>/galaxy_token, que se crea vacío con modo 0600 si falta. Los proxies vienen de https_proxy, http_proxy, all_proxy y no_proxy; a diferencia de ansible-galaxy, que elige la variable según el esquema de la URL, la primera que está definida se aplica a todas las URL. Las respuestas se guardan un día en <ANSIBLE_HOME>/galaxy_cache/api.json, el mismo archivo que usa ansible-galaxy. --no-cache lo deja de lado y --clear-response-cache lo vacía. username, password y auth_url no se leen.

-r lee el archivo de requisitos como ansible-galaxy: collections: y roles: en un mismo archivo, o la antigua lista simple de roles, que solo acepta role install. Una entrada include: trae los roles de otro archivo, cuya ruta se toma desde el directorio de trabajo. Si -r se da dos veces, cuenta el último. Si el archivo no tiene ninguna entrada para el comando, collection install y role install imprimen Skipping install, no requirements found y salen con 0. -vvv imprime primero Reading requirement file at '<path>'. Un archivo mal formado falla con el mensaje de ansible-galaxy, salida 1: sin entradas, claves distintas de collections y roles, una entrada de rol sin name ni src, un nombre de colección que no es namespace.name y no apunta a nada, o un type desconocido. El source de una entrada de colección nombra el servidor desde el que se instala, por su nombre en la lista de servidores o por su URL; otra URL se consulta como un servidor propio. Un source que no es ninguna de las dos cosas falla con Collections requirement 'source' entry should contain a valid Galaxy API URL but it does not: <source> is not an HTTP URL.

-v cuenta después del subcomando, como en ansible-galaxy; ansible-galaxy ignora un -v escrito antes del subcomando, y Volant lo cuenta.

Nivel Qué se añade
-v Using <path> as config file, o No config file found; using defaults.
-vv Antes de esa línea, el bloque que imprime --version: ansible-galaxy [core <version>], config file, configured module search path, ansible collection location, executable location. Las líneas de Python, Jinja y PyYAML solo aparecen cuando responde el intérprete del controlador, como en volant adhoc.
-vvv Reading requirement file at '<file>', found role <dict> in yaml file, Processing role <name> , Found installed collection <name>:<version> at '<path>', Created <token file> o Opened <token file>, Collection '<name>:<version>' obtained from server <server> <url>, Remote collection cached as '<path>', Skipping '<path>' for collection build.
-vvvv Validating downloaded file hash. Las demás líneas HTTP de ansible-galaxy (Calling Galaxy at, Found API version, la caché de respuestas) no se imprimen.

ansible-galaxy también informa de ansible._protomatter, la colección que ansible-core guarda en su propio paquete de Python; Volant no tiene ese paquete y nunca la informa. role remove pregunta al servidor Galaxy por defecto por su API antes de borrar nada, lo que imprime Opened <token file> con -vvv; Volant quita el rol sin contactar con ningún servidor.

Un subcomando que aún no es nativo falla con [ERROR]: volant galaxy <subcommand> is not supported yet, salida 1. collection publish y role delete, search, import, setup e info necesitan una cuenta de Galaxy o la base de roles del servidor, y siguen rechazados: [ERROR]: volant galaxy <subcommand> is not supported, salida 1.

volant runtime install --collections sigue instalando colecciones con el ansible-galaxy del runtime.