volant galaxy
ansible-galaxy 的选项由 Volant 自己检查,其子命令正逐个改为原生实现。
volant galaxy 接受 ansible-core 2.19.12 中 ansible-galaxy 的子命令和选项,为它编写的脚本和 CI 任务无需修改命令行。它正在 Volant 中重写,不再依赖 Python 运行时。目前它解析选项并完成 ansible-galaxy 最先做的检查,然后在子命令的原生版本完成之前拒绝执行。
volant galaxy collection <download|init|build|publish|install|list|verify> [OPTIONS]volant galaxy role <init|remove|delete|list|search|import|setup|info|install> [OPTIONS]每个子命令都接受 -s/--server、--token/--api-key、-c/--ignore-certs、--timeout 和可重复的 -v。collection download 和 collection install 还接受 --clear-response-cache 和 --no-cache。未知选项或类型错误的值以 2 退出并打印用法。volant galaxy --version 打印 ansible-galaxy 的版本信息。
最先进行的检查
Section titled “最先进行的检查”它们在任何实际工作之前进行,消息和退出码与 ansible-galaxy 相同:
| 情况 | 消息 | 退出码 |
|---|---|---|
collection install 同时给出名称和 -r |
[ERROR]: The positional collection_name arg and --requirements-file are mutually exclusive. |
1 |
collection install 或 download 两者都没有 |
[ERROR]: You must specify a collection name or a requirements file. |
1 |
-r 指向不存在的文件 |
[ERROR]: The requirements file '<path>' does not exist. |
1 |
role install 既没有名称也没有 -r |
[ERROR]: - you must specify a user/role name or a roles file |
5 |
role install -r 的文件不以 .yml 或 .yaml 结尾 |
[ERROR]: Invalid role requirements file, it must end with a .yml or .yaml extension |
1 |
role list 时没有任何角色路径存在 |
[WARNING]: - the configured path <path> does not exist. 每个路径一条,然后 [ERROR]: - None of the provided paths were usable. Please specify a valid path with --roles-path |
5 |
当 collection install -p PATH 的 PATH 之下没有任何已配置的集合路径时,命令先打印 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. Volant 追加在集合路径末尾的运行时自己的 collections/ 目录不会出现在 <paths> 中。
从 tar 包安装
Section titled “从 tar 包安装”collection install 原生安装集合 tar 包:volant galaxy collection install acme-demo-1.0.0.tar.gz -p DIR。名称和版本取自 tar 包中的 MANIFEST.json,而不是文件名。集合安装到 DIR/ansible_collections/<namespace>/<name>,没有 -p 时安装到第一个集合路径下。只写入 FILES.json 列出的文件,每个文件先与其 SHA-256 比对。文件权限为 0644,归档标记为可执行时为 0755。会落到集合之外的条目会被拒绝,指向集合之外的链接也会被拒绝。安装失败不会留下写了一半的集合。输出、消息和退出码与 ansible-galaxy 相同。已安装相同版本的集合会得到 Nothing to do. All requested collections are already installed. If you want to reinstall them, consider using –force.,--force 会覆盖旧目录重新安装。PATH/ansible_collections 已存在时,-p 的警告会说该路径 appears to be part of the pip Ansible package,与 ansible-galaxy 一致。
collection install 也接受 git 仓库:git+<url>,可用 ,<ref> 指定分支、标签或提交(默认 HEAD),用 #/<subdir> 指定不在仓库根目录的集合,例如 git+https://host/org/repo.git,v1.0.0 或 git+file:///work/mono/.git#/collections/demo。在依赖文件中写作带 type: git 的条目,其 version 即引用。Volant 调用系统的 git:HEAD 时浅克隆,否则完整克隆后检出,然后把检出的目录当作源码目录安装。仓库根目录没有集合时,安装其直接子目录中的每个集合。集合依赖 git+ URL 时,也会克隆该仓库,除非指定 --no-deps。来自仓库的内容没有可比较的版本,因此每次运行都会重新安装。不符合 SemVer 的版本会使安装以 Invalid version found for the collection 失败,退出码 1。git 自身的消息会输出到终端,与 ansible-galaxy 相同。URL 中的密码在所有消息中都替换为 ********。PATH 中没有 git 时,命令以 Could not find git executable to extract the collection from the Git repository 失败,退出码 1。
tar 包 URL、命名空间目录和签名在原生实现之前都会被拒绝:[ERROR]: volant galaxy collection install from a URL or a namespace directory is not supported yet,或 with signatures,退出码 1。
collection init <namespace>.<name> [--init-path DIR] [--collection-skeleton DIR] [-e VARS] [-f] 在 DIR/<namespace>/<name> 下写入一个新集合(DIR 默认为 ./),并输出 - Collection <namespace>.<name> was created successfully。没有 skeleton 时,它写入 ansible-core 2.19.12 的默认 skeleton:galaxy.yml、README.md、meta/runtime.yml、plugins/README.md,以及空的 docs/ 和 roles/ 目录。--collection-skeleton 或 GALAXY_COLLECTION_SKELETON 指定一个改为复制的 skeleton 目录。其中的 .j2 文件用 --extra-vars 渲染并去掉扩展名,playbooks/*/templates 和 roles/*/templates 下的除外。链接仍然是链接,GALAXY_COLLECTION_SKELETON_IGNORE 匹配的内容会被跳过。集合目录已存在时会报错,除非给出 -f,它会先清空该目录。消息和退出码与 ansible-galaxy 相同。
collection build [PATH] [--output-path DIR] [-f] 把带有 galaxy.yml 的源码目录(默认 .)构建成 DIR(默认 ./)下的 <namespace>-<name>-<version>.tar.gz,并打印 Created collection for <namespace>.<name> at <path>。galaxy.yml 必须包含 namespace、name、version、readme 和 authors;缺少键或缺少 galaxy.yml 时以 ansible-galaxy 的消息失败。tar 包包含 MANIFEST.json、FILES.json 和源码目录,但不包含 ansible-galaxy 排除的内容:galaxy.yml、.git 及其他版本控制目录、__pycache__、*.pyc、*.retry、tests/output、该集合以前的构建产物,以及 build_ignore 列出的内容。文件权限为 0644,属主可执行时为 0755;目录内部的链接保持为链接,指向外部目录的链接会被跳过并给出警告。已存在的构建产物会报错,除非给出 -f。Volant 把所有时间写为 0、所有属主写为 root,因此同一目录构建两次得到相同的字节;ansible-galaxy 写入当前时间。带有 manifest: 键的 galaxy.yml 暂时会被拒绝。
collection install DIR 以同样方式安装源码目录,不经过 tar 包,并在 Installing 和 installed successfully 两行之间打印 Created collection for <namespace>.<name>:<version> at <path>。collection download 会把源码目录构建到下载文件夹中。
从 Galaxy 服务器安装
Section titled “从 Galaxy 服务器安装”collection install 也接受名称,需要时可带版本范围:demo.base、demo.base:1.0.0、"demo.base:>=1.0.0,<2.0.0",以及 -r 中的条目。每个名称连同其依赖一起针对服务器解析,每个依赖取满足所有所需范围的最高版本,两个范围冲突时回溯。预发布版本只在使用 --pre 或被精确指定时才计入。每个 tar 包先下载,再与服务器给出的 SHA-256 比对,然后按上文解包。从服务器安装的集合还会得到 ansible_collections/<namespace>.<name>-<version>.info/GALAXY.yml,记录其来源。已安装且版本合适的集合会被保留:'<name>:<version>' is already installed, skipping.
-n 跳过依赖,-U 把已安装的集合升级到范围内的最新版本,-f 重新安装所请求的集合,--force-with-deps 连同其依赖一起重装,-i 在安装失败后给出警告并继续,--offline 不访问任何服务器。当没有一组版本能满足所有范围时,命令以 ansible-galaxy 的消息失败,该消息列出各个范围,并以关于 --pre 的提示结尾;ansible-galaxy 在提示之后打印的 Python 对象被省略。
下载以便离线安装
Section titled “下载以便离线安装”collection download 像 install 一样连同依赖解析所请求的集合,并把每个 tar 包保存到 -p 指定的文件夹,默认是 ./collections。然后在其中写入一个 requirements.yml,按文件名列出这些 tar 包及其版本。在没有网络的机器上,从该文件夹运行 volant galaxy collection install --offline -r requirements.yml 即可安装,不访问任何服务器。文件名相对于工作目录读取,与 ansible-galaxy 一致。-n 不包含依赖,-r 和 --pre 与 install 中的作用相同。使用 --offline 时,没有 tar 包提供的名称或未安装的依赖会以解析器的消息失败。
列出和校验集合
Section titled “列出和校验集合”collection list [NAME] [-p PATH]... [--format human|json|yaml] 对 -p 和集合路径中每个含有集合的目录,打印一个 # <path>/ansible_collections 块,列出每个集合的名称和版本;集合没有 MANIFEST.json 时版本为 *。列宽等于最长的名称和版本,与 ansible-galaxy 的填充方式一致。--format json 在一行中打印 {"<path>": {"<namespace>.<name>": {"version": "<version>"}}},--format yaml 以 YAML 打印相同内容。不存在的 -p 会给出警告;没有任何可读路径时命令以退出码 5 失败。ansible-galaxy 还会列出 ansible-core 放在自身 Python 包中的集合 ansible._protomatter;Volant 没有这样的包,不列出它。
collection verify NAME... [-p PATH] [--offline] 校验每个已安装的集合:先是 MANIFEST.json,再按清单给出的哈希校验 FILES.json,再逐个校验每个文件,最后在目录树中查找 FILES.json 未列出的文件和目录(*.pyc 除外)。每处差异列在 Collection <name> contains modified content in the following files: 之下,命令以 1 退出。不带 --offline 时会下载服务器上同一版本的 tar 包,以其 MANIFEST.json 为准;带上时以已安装的为准。集合未安装或没有 MANIFEST.json 时报错;-i 把错误变为警告。
安装和管理角色
Section titled “安装和管理角色”role install NAME... [-p PATH] [-r FILE] 把每个角色安装到第一个角色路径:-p,或配置中的第一个。名称写作 owner.role[,version[,name]],通过第一个服务器的 API v1 查找;不指定版本时取服务器列出的最高版本,其次是仓库的分支,再次是 master。tar 包路径、URL 和 git+ 源同样可以安装;tar 包或 git 源的角色名取自该行的第三个字段,该字段为空时取自路径。归档的顶层目录会被去掉,meta/.galaxy_install_info 记录版本和安装日期。已安装且版本相同的角色会被跳过;版本不同时给出警告并保留,除非 --force 替换它。随后安装 meta/main.yml 和 meta/requirements.yml 中的依赖,带 -n 时不安装;--force-with-deps 会替换已安装的依赖。安装失败的角色给出警告,命令以 1 退出,除非 -i 让它继续。-g 保留 git 角色的 .git 目录。
role list [NAME] [-p PATH] 以 # <path> 打印每个角色路径,再对其中每个角色打印 - <role>, <version>,角色没有安装信息时版本为 (unknown version)。role remove NAME... [-p PATH] 从第一个角色路径删除每个角色,目录中没有角色时打印 - <role> is not installed, skipping.。
Galaxy 服务器
Section titled “Galaxy 服务器”服务器取自 -s,否则取自 ansible.cfg 的 [galaxy] server_list 和 [galaxy_server.<name>] 节,再否则取自 GALAXY_SERVER,默认是 https://galaxy.ansible.com。每个 ANSIBLE_GALAXY_* 环境变量优先于文件。每个服务器接受 url、token、validate_certs 和 timeout。--token 优先于文件中的令牌,-c 关闭证书校验,--timeout 设置等待时间,默认 60 秒。无法访问的服务器会以 ansible-galaxy 的警告跳过,并询问下一个服务器。
令牌以 Authorization: Token <token> 发送,从不打印。没有令牌时会读取令牌文件 GALAXY_TOKEN_PATH,默认是 <ANSIBLE_HOME>/galaxy_token,缺失时以 0600 权限创建空文件。代理取自 https_proxy、http_proxy、all_proxy 和 no_proxy;ansible-galaxy 按 URL 的协议选择变量,而 Volant 对所有 URL 使用第一个已设置的变量。响应在 <ANSIBLE_HOME>/galaxy_cache/api.json 中保留一天,与 ansible-galaxy 使用同一个文件。--no-cache 不使用它,--clear-response-cache 清空它。不读取 username、password 和 auth_url。
-r 按 ansible-galaxy 的方式读取依赖文件:同一个文件中的 collections: 和 roles:,或旧式的纯角色列表(只有 role install 接受)。include: 条目引入另一个文件中的角色,其路径相对于工作目录。-r 给出两次时以最后一次为准。文件中没有该命令的条目时,collection install 和 role install 打印 Skipping install, no requirements found 并以 0 退出。-vvv 会先打印 Reading requirement file at '<path>'。格式错误的文件以 ansible-galaxy 的消息失败,退出码 1:没有条目、出现 collections 和 roles 以外的键、角色条目既无 name 也无 src、集合名不是 namespace.name 且不指向任何内容,或 type 未知。集合条目的 source 指定从哪个服务器安装:服务器列表中的名称或其 URL;其他 URL 会被当作单独的服务器访问。两者都不是的 source 会以 Collections requirement 'source' entry should contain a valid Galaxy API URL but it does not: <source> is not an HTTP URL. 失败。
-v 在子命令之后计数,与 ansible-galaxy 一致;ansible-galaxy 会忽略写在子命令之前的 -v,Volant 则会计入。
| 级别 | 增加的内容 |
|---|---|
-v |
Using <path> as config file,或 No config file found; using defaults。 |
-vv |
在该行之前打印 --version 的块:ansible-galaxy [core <version>]、config file、configured module search path、ansible collection location、executable location。只有控制节点的解释器有响应时才会出现 Python、Jinja 和 PyYAML 这几行,与 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> 或 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。ansible-galaxy 的其他 HTTP 行(Calling Galaxy at、Found API version、响应缓存)不会打印。 |
ansible-galaxy 还会报告 ansible._protomatter,即 ansible-core 放在自身 Python 包中的集合;Volant 没有这样的包,从不报告它。role remove 在删除前会向默认 Galaxy 服务器询问其 API,因此在 -vvv 时打印 Opened <token file>;Volant 删除角色时不联系任何服务器。
被拒绝的子命令
Section titled “被拒绝的子命令”尚未原生实现的子命令以 [ERROR]: volant galaxy <subcommand> is not supported yet 失败,退出码 1。collection publish 以及 role delete、search、import、setup 和 info 需要 Galaxy 账号或服务器的角色数据库,会一直被拒绝:[ERROR]: volant galaxy <subcommand> is not supported,退出码 1。
volant runtime install --collections 仍使用运行时自带的 ansible-galaxy 安装集合。