安装和使用

ansible-creator 提供两个主要功能：init 和 add。init 命令允许您初始化 Ansible 项目，而 add 命令允许您向现有的 Ansible 项目添加资源。

安装

推荐

安装 ansible-creator 的推荐方法是使用 ansible-dev-tools 包。Ansible 开发工具旨在简化创建Ansible内容所需的一些工具的设置和使用。它将关键的 Ansible 开发包组合到一个统一的 Python 包中。

# This also installs ansible-core if it is not already installed
pip3 install ansible-dev-tools

要安装 ansible-creator，请使用以下 pip 命令

$ pip install ansible-creator

CLI 使用

ansible-creator 的命令行界面 (CLI) 提供了一种直接有效的方式与该工具进行交互。用户可以通过简洁的命令启动操作，例如初始化 Ansible 集合。CLI 旨在简化操作，使用户能够轻松执行操作，而无需深入了解工具的复杂性。对于喜欢命令行工作流程的用户来说，它是一个灵活而强大的选项，使用户能够将 ansible-creator 无缝集成到他们的开发流程中。

如果您不喜欢命令行，您也可以利用 VS Code 的 Ansible 扩展中的 GUI 界面，该界面提供了更直观的 ansible-creator 体验。请参见此处。

命令行补全

ansible-creator 具有针对常用 shell 的实验性命令行补全功能。请确保您已安装并配置了 argcomplete 包。

$ pip install argcomplete --user
$ activate-global-python-argcomplete --user

一般用法

通过运行以下命令可以获取可用命令和选项的概述

$ ansible-creator --help

初始化 Ansible 集合项目

init collection 命令允许您初始化 Ansible 集合项目。使用以下命令模板

$ ansible-creator init collection <collection-name> <path>

位置参数

参数	描述
collection-name	格式为 '.'.
path	集合项目的目标目录。

可选参数

短标志	长标志	标志参数	描述
-f	--force		强制将指定的目录重新初始化为 Ansible 集合。此标志已弃用，并将很快移除。(默认值：False)
-o	--overwrite		覆盖现有文件或目录。(默认值：False)
-no	--no-overwrite		限制文件或目录的覆盖操作。(默认值：False)
	--json		以 JSON 格式输出消息 (默认值：False)
--la	--log-append	bool	追加到日志文件。(选项：true, false) (默认值：true)
--lf	--log-file	file	要写入的日志文件。(默认值：./ansible-creator.log)
--ll	--log-level	level	文件输出的日志级别。(选项：notset, debug, info, warning, error, critical) (默认值：notset)
--na	--no-ansi		禁用终端颜色的 ANSI 代码。(默认值：False)
-h	--help		显示此帮助消息并退出
-v	--verbosity		提供更多 CLI 输出。选项是累加的，最多可以使用 3 次。(默认值：0)

示例

$ ansible-creator init collection testns.testname $HOME/collections/ansible_collections

此命令将在 /home/ansible-dev/collections/ansible_collections/testns/testname 中搭建 testns.testname 集合。

生成的 Ansible 集合结构

运行 init collection 命令将生成一个具有全面目录结构的 Ansible 集合项目。使用以下命令浏览它

$ tree -lla /home/ansible-dev/collections/ansible_collections/testns/testname
.
├── CHANGELOG.rst
├── changelogs
│   └── config.yaml
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING
├── .devcontainer
│   ├── devcontainer.json
│   ├── docker
│   │   └── devcontainer.json
│   └── podman
│       └── devcontainer.json
├── devfile.yaml
├── docs
│   ├── docsite
│   │   └── links.yml
│   └── .keep
├── extensions
│   ├── eda
│   │   └── rulebooks
│   │       └── rulebook.yml
│   └── molecule
│       ├── integration_hello_world
│       │   └── molecule.yml
│       └── utils
│           ├── playbooks
│           │   ├── converge.yml
│           │   └── noop.yml
│           └── vars
│               └── vars.yml
├── galaxy.yml
├── .github
│   └── workflows
│       ├── release.yml
│       └── test.yml
├── .isort.cfg
├── LICENSE
├── MAINTAINERS
├── meta
│   └── runtime.yml
├── plugins
│   ├── action
│   │   └── __init__.py
│   ├── cache
│   │   └── __init__.py
│   ├── filter
│   │   ├── hello_world.py
│   │   └── __init__.py
│   ├── inventory
│   │   └── __init__.py
│   ├── modules
│   │   └── __init__.py
│   ├── module_utils
│   │   └── __init__.py
│   ├── plugin_utils
│   │   └── __init__.py
│   ├── sub_plugins
│   │   └── __init__.py
│   └── test
│       └── __init__.py
├── .pre-commit-config.yaml
├── .prettierignore
├── pyproject.toml
├── README.md
├── roles
│   └── run
│       ├── defaults
│       │   └── main.yml
│       ├── files
│       │   └── .keep
│       ├── handlers
│       │   └── main.yaml
│       ├── meta
│       │   └── main.yml
│       ├── README.md
│       ├── tasks
│       │   └── main.yml
│       ├── templates
│       │   └── .keep
│       ├── tests
│       │   └── inventory
│       ├── vars
│       │   └── main.yml
├── tests
│   ├── .gitignore
│   ├── integration
│   │   ├── __init__.py
│   │   ├── targets
│   │   │   └── hello_world
│   │   │       └── tasks
│   │   │           └── main.yml
│   │   └── test_integration.py
│   └── unit
│       └── .keep
└── .vscode
    └── extensions.json

注意

搭建的集合包含一个 hello_world 过滤器插件，以及一个 molecule 场景和它的集成测试目标，可以使用 pytest 运行。这可以作为您编写 Ansible 插件测试时的参考示例，在不再需要时可以将其删除。

要运行 hello_world 集成测试，请按照以下步骤操作

• 使用 git init 初始化包含搭建的集合的存储库。
• pip install ansible-dev-tools.
• 从集合根目录调用 pytest。

初始化 Ansible playbook 项目

init playbook 命令允许您初始化 Ansible playbook 项目。使用以下命令模板

$ ansible-creator init playbook <collection-name> <path>

位置参数

参数	描述
collection-name	playbook 邻接集合的名称，格式为 '.'.
path	playbook 项目的目标目录。

可选参数

短标志	长标志	标志参数	描述
-f	--force		强制将指定的目录重新初始化为 Ansible 集合。此标志已弃用，并将很快移除。(默认值：False)
-o	--overwrite		覆盖现有文件或目录。(默认值：False)
-no	--no-overwrite		限制文件或目录的覆盖操作。(默认值：False)
	--json		以 JSON 格式输出消息 (默认值：False)
--la	--log-append	bool	追加到日志文件。(选项：true, false) (默认值：true)
--lf	--log-file	file	要写入的日志文件。(默认值：./ansible-creator.log)
--ll	--log-level	level	文件输出的日志级别。(选项：notset, debug, info, warning, error, critical) (默认值：notset)
--na	--no-ansi		禁用终端颜色的 ANSI 代码。(默认值：False)
-h	--help		显示此帮助消息并退出
-v	--verbosity		提供更多 CLI 输出。选项是累加的，最多可以使用 3 次。(默认值：0)

示例

$ ansible-creator init playbook myorg.myproject $HOME/ansible-projects/playbook-project

此命令将在 /home/user/ansible-projects/playbook-project 中搭建新的 Ansible playbook 项目。

生成的 Ansible playbook 项目结构

运行 init playbook 命令将生成一个具有全面目录结构的 Ansible playbook 项目。使用以下命令浏览它

$ tree -la /home/user/ansible-projects/playbook-project
.
├── ansible.cfg
├── ansible-navigator.yml
├── collections
│   ├── ansible_collections
│   │   └── myorg
│   │       └── myproject
│   │           ├── README.md
│   │           └── roles
│   │               └── run
│   │                   ├── README.md
│   │                   └── tasks
│   │                       └── main.yml
│   └── requirements.yml
├── .devcontainer
│   ├── devcontainer.json
│   ├── docker
│   │   └── devcontainer.json
│   └── podman
│       └── devcontainer.json
├── devfile.yaml
├── .github
│   ├── ansible-code-bot.yml
│   └── workflows
│       └── tests.yml
├── inventory
│   ├── group_vars
│   │   ├── all.yml
│   │   └── web_servers.yml
│   ├── hosts.yml
│   └── host_vars
│       ├── server1.yml
│       ├── server2.yml
│       ├── server3.yml
│       ├── switch1.yml
│       └── switch2.yml
├── linux_playbook.yml
├── network_playbook.yml
├── README.md
├── site.yml
└── .vscode
    └── extensions.json

它还配备了使用 ansible-content-actions 进行集合测试和发布的 Github Action 工作流程。有关如何使用这些工作流程的详细信息，请参考以下内容：

• 使用测试工作流程
• 使用发布工作流程

请确保您检查搭建的内容中任何潜在的 TO-DO 项目，并根据您的需求进行必要的修改。

向现有项目添加支持

add 子命令允许用户将资源和插件等内容类型搭建到现有项目中。此功能旨在通过自动生成必要的配置文件来简化开发环境的设置。

一般用法

通过运行以下命令可以获取可用命令和选项的概述

$ ansible-creator add --help

位置参数

参数	描述
resource	向现有的 Ansible 项目添加资源。
plugin	向 Ansible 集合添加插件。

可选参数

短标志	长标志	标志参数	描述
-h	--help		显示此帮助消息并退出。

向现有项目添加搭建资源的支持

add resource 命令允许您向现有项目添加资源。使用以下命令模板

$ ansible-creator add resource <resource-type> <path>

位置参数

参数	描述
devcontainer	向现有的 Ansible 项目添加 devcontainer 文件。
devfile	向现有的 Ansible 项目添加 devfile 文件。
role	向现有的 Ansible 集合添加角色。

示例

$ ansible-creator add resource devfile /home/user/..path/to/your/existing_project

此命令将在 /home/user/..path/to/your/existing_project 中搭建 devfile.yaml 文件。