Ansible Generator

生成遵循当前最佳实践、命名约定和安全标准的生产就绪Ansible资源（剧本、角色、任务和清单文件）。所有生成的资源都使用devops-skills:ansible-validator技能自动验证，确保语法正确和lint合规。

核心能力

生成Ansible剧本

创建具有适当结构、错误处理和幂等性的完整、生产就绪剧本。

何时使用：

用户请求：“创建一个剧本以…”，“构建一个剧本用于…”，“生成剧本以…”
场景：应用部署、系统配置、备份自动化、服务管理

流程：

理解用户的需求（需要自动化的内容）
确定目标主机、所需权限和操作系统
使用assets/templates/playbook/basic_playbook.yml作为结构基础
参考references/best-practices.md以实现模式
参考references/module-patterns.md以正确使用模块
遵循这些原则生成剧本：
- 所有模块使用完全限定集合名称（FQCN）
- 确保幂等性（所有任务可以安全地多次运行）
- 包括适当的错误处理和条件语句
- 添加有意义的任务名称，以动词开头
- 使用适当的标签对任务进行分类
- 包括文档头，带有使用说明
- 在适用的情况下，在post_tasks中添加健康检查
始终验证生成的剧本是否使用devops-skills:ansible-validator技能
如果验证失败，修复问题并重新验证

示例结构：

---
# 剧本：部署Web应用程序
# 描述：使用SSL部署nginx Web服务器
# 要求：
#   - Ansible 2.10+
#   - 目标主机：Ubuntu 20.04+
# 变量：
#   - app_port：应用程序端口（默认：8080）
# 使用方法：
#   ansible-playbook -i inventory/production deploy_web.yml

- name: 部署和配置Web服务器
  hosts: webservers
  become: true
  gather_facts: true

  vars:
    app_port: 8080
    nginx_version: latest

  pre_tasks:
    - name: 更新软件包缓存
      ansible.builtin.apt：
        update_cache: true
        cache_valid_time: 3600
      当：ansible_os_family == "Debian"

  tasks:
    - name: 确保nginx已安装
      ansible.builtin.package：
        name: nginx
        state: present
      标签：
        - install
        - nginx

    - name: 部署nginx配置
      ansible.builtin.template：
        src: templates/nginx.conf.j2
        dest: /etc/nginx/nginx.conf
        mode: '0644'
        backup: true
        validate: 'nginx -t -c %s'
      通知：Reload nginx
      标签：
        - configure

  post_tasks:
    - name: 验证nginx是否响应
      ansible.builtin.uri：
        url: "http://localhost:{{ app_port }}/health"
        status_code: 200
      注册：health_check
      直到：health_check.status == 200
      重试：5
      延迟：10

  handlers:
    - name: Reload nginx
      ansible.builtin.service：
        name: nginx
        state: reloaded

生成Ansible角色

创建完整的角色结构，所有必需的组件都按照Ansible Galaxy约定组织。

何时使用：

用户请求：“为…创建一个角色”，“生成一个角色以…”，“构建角色以…”
场景：可重用组件创建、复杂服务设置、多环境部署

流程：

理解角色的目的和范围
从assets/templates/role/复制和自定义完整角色结构：
- tasks/main.yml - 主要任务执行逻辑
- handlers/main.yml - 事件处理程序（服务重启、重新加载）
- templates/ - Jinja2配置模板
- files/ - 要复制的静态文件
- vars/main.yml - 角色特定变量（高优先级）
- vars/Debian.yml和vars/RedHat.yml - 操作系统特定变量
- defaults/main.yml - 默认变量（易于覆盖）
- meta/main.yml - 角色元数据和依赖项
- README.md - 角色文档
用实际值替换所有[PLACEHOLDERS]：
- [ROLE_NAME] - 角色名称（小写，下划线）
- [role_name] - 角色变量的变量前缀
- [PLAYBOOK_DESCRIPTION] - 角色的作用描述
- [package_name]，[service_name] - 实际的软件包/服务名称
- [default_port] - 默认端口号
- 根据需要替换所有其他占位符
按照最佳实践实现角色特定逻辑：
- 使用include_vars使用操作系统特定变量
- 所有角色变量都以前缀角色名称
- 为所有服务更改创建处理程序
- 在模板任务中包含验证
- 添加全面的标签
在README.md中创建适当角色文档
始终验证角色是否使用devops-skills:ansible-validator技能
修复任何验证错误并重新验证

角色变量命名约定：

前缀：{{ role_name }}_
示例：nginx_port，nginx_worker_processes，postgres_max_connections

生成任务文件

创建针对特定操作的专注任务文件，这些文件可以包含在剧本或角色中。

何时使用：

用户请求：“创建任务以…”，“为…生成任务文件”
场景：可重用任务序列、复杂操作、条件包含

流程：

定义要自动化的特定操作
参考references/module-patterns.md以正确使用模块
生成任务文件：
- 描述性任务名称（动词优先）
- 所有模块使用FQCN
- 适当的错误处理
- 幂等性检查
- 适当的标签
- 需要时条件执行
始终验证使用devops-skills:ansible-validator技能

示例：

---
# 任务：数据库备份操作

- name: 创建备份目录
  ansible.builtin.file：
    path: "{{ backup_dir }}"
    state: directory
    mode: '0755'
    owner: postgres
    group: postgres

- name: 转储PostgreSQL数据库
  ansible.builtin.command：>
    pg_dump -h {{ db_host }} -U {{ db_user }} -d {{ db_name }}
    -f {{ backup_dir }}/{{ db_name }}_{{ ansible_date_time.date }}.sql
  环境：
    PGPASSWORD: "{{ db_password }}"
  无日志：true
  何时更改：true

- name: 压缩备份文件
  ansible.builtin.archive：
    path: "{{ backup_dir }}/{{ db_name }}_{{ ansible_date_time.date }}.sql"
    dest: "{{ backup_dir }}/{{ db_name }}_{{ ansible_date_time.date }}.sql.gz"
    格式：gz
    移除：true

- name: 删除旧备份
  ansible.builtin.find：
    paths: "{{ backup_dir }}"
    模式："*.sql.gz"
    年龄："{{ backup_retention_days }}d"
  注册：old_backups

- name: 删除旧备份文件
  ansible.builtin.file：
    path: "{{ item.path }}"
    state: absent
  循环："{{ old_backups.files }}"

生成清单文件

创建清单配置，具有适当的主机组织、组层次结构和变量管理。

何时使用：

用户请求：“为…创建清单”，“生成清单文件…”
场景：环境设置、主机组织、多层架构

流程：

理解基础设施拓扑
使用assets/templates/inventory/作为基础：
- hosts - 主清单文件（INI或YAML格式）
- group_vars/all.yml - 所有主机的全局变量
- group_vars/[groupname].yml - 组特定变量
- host_vars/[hostname].yml - 主机特定变量
将主机组织成逻辑组：
- 功能组：webservers，databases，loadbalancers
- 环境组：production，staging，development
- 地理组：us-east，eu-west
使用[group:children]创建组层次结构
在适当级别定义变量（全部 → 组 → 主机）
文档化连接设置和要求

清单格式偏好：

对于简单、扁平的清单，使用INI格式
对于复杂、分层的清单，使用YAML格式

动态清单（云环境）： 对于AWS、Azure、GCP和其他云提供商，使用动态清单插件：

AWS EC2：plugin: amazon.aws.aws_ec2带有过滤器和keyed_groups
Azure：plugin: azure.azcollection.azure_rm带有资源组过滤器
根据标签、区域和资源组自动发现主机
参考references/module-patterns.md以获取详细示例

生成项目配置文件

何时使用：

用户请求：“设置Ansible项目”，“初始化Ansible配置”
场景：新项目初始化、标准化项目结构

流程：

使用assets/templates/project/中的模板：
- ansible.cfg - 项目配置（forks，timeout，paths）
- requirements.yml - 集合和角色依赖项
- .ansible-lint - 代码质量的lint规则
根据项目需求定制
文档化使用说明
角色参数规范（Ansible 2.11+）

生成角色时，包括meta/argument_specs.yml以自动验证变量：

定义必需和可选变量
指定类型（str，int，bool，list，dict，path）
设置默认值和选项
在角色执行前启用自动验证
assets/templates/role/meta/argument_specs.yml中有模板

处理自定义模块和集合

生成需要自定义模块、集合或提供程序的Ansible资源时，这些不在ansible.builtin中：

检测：

用户提到特定集合（例如，“kubernetes.core”，“amazon.aws”，“community.docker”）
用户请求与外部工具/平台集成
任务需要不在ansible.builtin命名空间中的模块

流程：

确定集合/模块：
- 提取集合名称和模块名称
- 确定是否需要版本特定信息

使用WebSearch搜索当前文档：

搜索查询模式："ansible [collection.name] [module] [version] documentation examples"
示例：
- "ansible kubernetes.core k8s module latest documentation"
- "ansible amazon.aws ec2_instance 2024 examples"
- "ansible community.docker docker_container latest documentation"

分析搜索结果以获取：
- 当前模块参数及其类型
- 必需与可选参数
- 版本兼容性和弃用通知
- 工作示例和最佳实践
- 集合安装要求
如果Context7 MCP可用：
- 首先尝试使用mcp__context7__resolve-library-id解析库ID
- 然后使用mcp__context7__get-library-docs获取文档
- 提供更结构化、可靠的文档
使用发现的信息生成资源：
- 使用正确的FQCN（例如，kubernetes.core.k8s，不仅仅是k8s）
- 应用当前参数名称和值
- 在注释中包括集合安装说明
- 添加版本兼容性说明

包括安装说明：

# 要求：
#   - ansible-galaxy collection install kubernetes.core:2.4.0
# 或在requirements.yml中：
# ---
# collections:
#   - name: kubernetes.core
#     version: "2.4.0"

示例，使用自定义集合：

---
# 剧本：部署Kubernetes资源
# 要求：
#   - Ansible 2.10+
#   - 集合：kubernetes.core >= 2.4.0
#   - 安装：ansible-galaxy collection install kubernetes.core
# 变量：
#   - k8s_namespace：目标命名空间（默认：default）
#   - k8s_kubeconfig：kubeconfig路径（默认：~/.kube/config）

- name: 将应用程序部署到Kubernetes
  hosts: localhost
  gather_facts: false
  vars:
    k8s_namespace: production
    k8s_kubeconfig: ~/.kube/config

  tasks:
    - name: 创建命名空间
      kubernetes.core.k8s：
        kubeconfig: "{{ k8s_kubeconfig }}"
        state: present
        定义：
          apiVersion: v1
          kind: Namespace
          metadata:
            name: "{{ k8s_namespace }}"
      标签：
        - namespace

    - name: 部署应用程序
      kubernetes.core.k8s：
        kubeconfig: "{{ k8s_kubeconfig }}"
        state: present
        命名空间："{{ k8s_namespace }}"
        定义：
          apiVersion: apps/v1
          kind: Deployment
          metadata:
            name: myapp
          spec:
            replicas: 3
            selector:
              matchLabels:
                app: myapp
            template:
              metadata:
                labels:
                  app: myapp
              spec:
                containers:
                  - name: myapp
                    image: myapp:1.0.0
                    ports:
                      - containerPort: 8080
      标签：
        - deployment

验证工作流程

**关键：**在向用户呈现之前，每个生成的Ansible资源都必须经过验证。

验证流程

生成任何Ansible文件后，立即调用devops-skills:ansible-validator技能：
```
技能：devops-skills:ansible-validator
```
devops-skills:ansible-validator技能将：
- 验证YAML语法
- 运行ansible-lint以获得最佳实践
- 执行ansible-playbook --syntax-check
- 在适用时执行检查模式（dry-run）
- 报告任何错误、警告或问题
如果验证失败：
- 分析报告的错误
- 修复生成文件中的问题
- 重新验证直到所有检查通过

如果验证成功，正式向用户呈现结果：

所需呈现格式：

## 生成[资源类型]：[名称]

**验证状态：**✅所有检查通过
- YAML语法：通过
- Ansible语法：通过
- Ansible lint：通过

**摘要：**
- [简要描述生成的内容]
- [包括的关键功能/部分]
- [任何值得注意的实施决策]

**用法：**
```bash
[运行剧本/角色的确切命令]

先决条件：

[任何必需的集合或依赖项]
[目标系统要求]

这种正式的呈现确保用户清楚地理解：

验证已成功
生成了什么以及为什么
如何使用生成的资源
任何先决条件或依赖项

何时跳过验证

只有在以下情况下跳过验证：

生成部分代码片段（不是完整文件）
为文档目的创建示例
用户明确请求跳过验证

强制执行的最佳实践

参考references/best-practices.md以获得全面的指导。关键原则：

强制性标准

FQCN（完全限定集合名称）：
- ✅正确：ansible.builtin.copy，community.general.ufw
- ❌错误：copy，ufw
幂等性：
- 所有任务必须可以安全地多次运行
- 使用state: present/absent声明
- 避免使用command/shell，当存在内置模块时
- 当使用command/shell时，使用creates，removes或changed_when
命名：
- 任务名称：描述性，以动词开头（“Ensure”，“Create”，“Deploy”）
- 变量：snake_case，具有描述性名称
- 角色变量：以前缀角色名称
- 文件：小写，下划线
安全：
- 对敏感操作使用no_log: true
- 设置限制性文件权限（600用于机密，644用于配置）
- 永远不要以明文提交密码/机密
- 参考ansible-vault进行机密管理
错误处理：
- 包括when条件语句，用于操作系统特定任务
- 使用register捕获任务结果
- 为命令模块添加failed_when和changed_when
- 为配置文件包括validate参数
性能：
- 当不需要时禁用事实收集：gather_facts: false
- 使用update_cache与cache_valid_time用于包管理器
- 实施异步任务，用于长时间运行的操作
文档：
- 在剧本中添加带有要求和使用说明的头部注释
- 用描述和默认值记录所有变量
- 在角色README文件中包括示例

模块选择优先级

**重要：**尽可能优先选择内置模块而不是集合模块。这确保了：

更好的验证兼容性（验证环境可能没有安装集合）
较少的外部依赖项
Ansible剧本在各种环境中更可靠地执行

优先级顺序：

内置模块（ansible.builtin.*） - 始终首选
- 在使用集合之前检查references/module-patterns.md以获取内置替代品
- 示例：如果集合不是必需的，使用ansible.builtin.command和psql命令而不是community.postgresql.postgresql_db
官方集合模块（经过验证的集合） - 第二选择，仅当内置模块不存在时
社区模块（community.*） - 第三选择
自定义模块 - 最后的选择
避免command/shell - 仅当没有模块替代品时

处理验证中的集合依赖项

当验证因缺少集合（例如，“无法解析模块/操作”）而失败时：

首先，检查是否存在内置替代品：
- 许多集合模块都有ansible.builtin.*等效项
- 示例：而不是community.postgresql.postgresql_db，使用ansible.builtin.command和psql命令
- 示例：而不是community.docker.docker_container，使用ansible.builtin.command和docker CLI
如果需要集合（没有内置替代品）：
- 在剧本头部清楚地记录集合要求
- 在注释中添加安装说明
- 考虑提供两种方法（基于集合和内置回退）
如果验证环境缺少集合：
- 使用ansible.builtin.*模块和等效CLI命令重写任务
- 使用changed_when和creates/removes与命令模块实现幂等性
- 文档化，基于集合的方法在生产中更受青睐

示例 - PostgreSQL的内置回退：

# 首选（需要community.postgresql集合）：
# - name: 创建数据库
#   community.postgresql.postgresql_db：
#     name: mydb
#     state: present

# 内置回退（无需集合）：
- name: 检查数据库是否存在
  ansible.builtin.command：
    cmd: psql -tAc "SELECT 1 FROM pg_database WHERE datname='mydb'"
  成为：true
  成为用户：postgres
  注册：db_check
  何时更改：false

- name: 创建数据库
  ansible.builtin.command：
    cmd: psql -c "CREATE DATABASE mydb"
  成为：true
  成为用户：postgres
  当：db_check.stdout != "1"
  何时更改：true

资源

参考（技能调用时加载）

重要：这些参考文件应在生成任何Ansible资源之前阅读，以通知实施决策。不要仅仅依赖一般知识 - 明确阅读参考以确保应用当前最佳实践。

references/best-practices.md - 综合Ansible最佳实践指南
- 目录结构、命名约定、任务编写
- 变量、处理程序、模板、安全
- 测试、性能优化、常见陷阱
- **何时阅读：**在生成任何Ansible资源时
- **如何使用：**提取特定资源类型的相关模式
references/module-patterns.md - 常见模块使用模式和示例
- 所有常见ansible.builtin模块的完整示例
- 集合模块示例（docker，postgresql等）
- 可复制粘贴的代码片段
- **何时阅读：**在选择任务模块时
- **如何使用：**找到所需操作的正确模块和参数语法

资产（模板作为参考结构）

模板作为结构参考，显示预期的格式和组织。您不需要逐字复制和粘贴它们 - 将它们用作正确结构、部分和模式的指南。

assets/templates/playbook/basic_playbook.yml - 参考剧本结构
- 显示：pre_tasks，tasks，post_tasks，handlers组织
- 显示：文档头格式
- 显示：变量声明模式
assets/templates/role/* - 参考角色目录结构
- 显示：必需文件及其组织
- 显示：变量命名约定
- meta/argument_specs.yml - 角色变量验证（Ansible 2.11+）
assets/templates/inventory/* - 参考清单组织
- 显示：主机分组模式
- 显示：group_vars/host_vars结构
assets/templates/project/* - 参考项目配置
- ansible.cfg - 项目级Ansible配置
- requirements.yml - 集合和角色依赖项
- .ansible-lint - Linting规则配置

如何使用模板：

查看相关模板，了解预期的结构
生成内容，遵循相同的组织模式
替换所有[PLACEHOLDERS]为适用于任务的实际值
自定义基于用户要求的逻辑
移除不适用的不必要部分
验证使用devops-skills:ansible-validator技能的结果

典型工作流程示例

用户请求：“创建一个部署nginx并配置SSL的剧本”

流程：

✅理解需求：
- 部署nginx Web服务器
- 配置SSL/TLS
- 确保服务正在运行
- 目标：Linux服务器（Ubuntu/RHEL）
✅参考资源：
- 检查references/best-practices.md以获取剧本结构
- 检查references/module-patterns.md以获取nginx相关模块
- 使用assets/templates/playbook/basic_playbook.yml作为基础
✅生成剧本：
- 使用所有模块的FQCN
- 包括操作系统特定条件
- 添加SSL配置任务
- 包括验证和健康检查
- 添加适当的标签和处理程序
✅验证：
- 调用devops-skills:ansible-validator技能
- 修复任何报告的问题
- 如有需要，重新验证
✅向用户呈现：
- 显示经过验证的剧本
- 解释关键部分
- 提供使用说明
- 提及成功的验证

常见模式

多操作系统支持

- name: 在Debian/Ubuntu上安装nginx
  ansible.builtin.apt：
    name: nginx
    state: present
  当：ansible_os_family == "Debian"

# 注意：对于RHEL 8+，使用ansible.builtin.dnf而不是yum
# ansible.builtin.yum因现代RHEL/CentOS而弃用，转而使用dnf
- name: 在RHEL 8+/CentOS 8+上安装nginx
  ansible.builtin.dnf：
    name: nginx
    state: present
  当：ansible_os_family == "RedHat"

模板部署与验证

- name: 部署配置
  ansible.builtin.template：
    src: app_config.j2
    dest: /etc/app/config.yml
    mode: '0644'
    backup: true
    validate: '/usr/bin/app validate %s'
  通知：重启应用程序

异步长时间运行任务

- name: 运行数据库迁移
  ansible.builtin.command：/opt/app/migrate.sh
  异步：3600
  轮询：0
  注册：迁移

- name: 检查迁移状态
  ansible.builtin.async_status：
    jid: "{{ migration.ansible_job_id }}"
  注册：job_result
  直到：job_result.finished
  重试：360
  延迟：10

条件执行

- name: 配置生产设置
  ansible.builtin.template：
    src: production.j2
    dest: /etc/app/config.yml
  当：
    - env == "production"
    - ansible_distribution == "Ubuntu"

错误消息和故障排除

如果devops-skills:ansible-validator报告错误：

**语法错误：**修复YAML格式、缩进或结构
**Lint警告：**解决最佳实践违规（FQCN、命名等）
**未定义变量：**添加变量定义或默认值
**模块未找到：**检查FQCN或添加集合要求
**检查模式下的任务失败：**对于必须运行的任务，添加check_mode: no

如果找不到自定义模块/集合文档：

尝试使用不同版本的替代搜索查询
检查Ansible Galaxy中的集合
查看ansible-collections GitHub组织中的模块
考虑使用替代的内置模块
询问用户是否具有特定版本要求

最终检查表（MANDATORY）

在向用户呈现任何生成的Ansible资源之前，验证所有项目：

[ ] 参考文件已阅读 - 已咨询references/best-practices.md和references/module-patterns.md
[ ] 使用FQCN - 所有模块使用完全限定名称（ansible.builtin.*，而不是裸名称）
[ ] 布尔值正确 - 使用true/false（而不是yes/no）以通过ansible-lint
[ ] RHEL 8+ - 使用ansible.builtin.dnf（而不是ansible.builtin.yum）用于现代RHEL/CentOS
[ ] 幂等 - 所有任务可以安全地多次运行
[ ] 安全 - 对敏感任务使用no_log: true，适当的文件权限
[ ] 已验证 - 已调用并通过devops-skills:ansible-validator技能
[ ] 正式呈现 - 输出格式按照下面的模板

所需输出格式

验证通过后，始终以这种确切的格式呈现结果：

## 生成[资源类型]：[名称]

**验证状态：**✅所有检查通过
- YAML语法：通过
- Ansible语法：通过
- Ansible lint：通过

**摘要：**
- [简要描述生成的内容]
- [包括的关键功能/部分]
- [任何值得注意的实施决策]

**用法：**
```bash
[运行剧本/角色的确切命令]

先决条件：

[任何必需的集合或依赖项]
[目标系统要求]


---

## 总结

生成Ansible资源时，始终遵循这个顺序：

1. **理解** - 澄清用户需求
2. **参考** - 检查best-practices.md和module-patterns.md
3. **生成** - 使用模板并遵循标准（FQCN，幂等性，命名）
4. **搜索** - 对于自定义模块/集合，使用WebSearch获取当前文档
5. **验证** - 始终使用devops-skills:ansible-validator技能
6. **修复** - 解决任何验证错误
7. **呈现** - 提供经过验证的、生产就绪的Ansible代码

生成的Ansible资源应：
- ✅可以安全地多次运行且幂等
- ✅遵循当前最佳实践和命名约定
- ✅对所有模块使用FQCN
- ✅有文档化的使用说明
- ✅经过验证和lint清洁
- ✅生产就绪且可维护