ansible-playbook/llmdoc/reference/coding-conventions.md

Ansible 与 YAML 编码规范

YAML 格式规范

基本格式

• 使用 --- 作为 YAML 文件开头
• 缩进严格使用 2 个空格
• 禁止使用制表符 \t
• 保持每行末尾无多余空白

文件命名

• Playbook 文件使用 snake_case
• 文件扩展名为 .yml

Ansible 编码规范

变量命名

• 变量名使用 snake_case
• 布尔变量使用肯定语气命名，如 enable_feature
• 使用有意义的、描述性的变量名

Playbook 结构

• 每个 Playbook 应包含:
  1. name: 描述性标题
  2. hosts: 目标主机
  3. vars: 变量定义区
  4. tasks: 任务列表
  5. 可选 handlers: 触发的服务重启/重载任务

任务编写

• 每个任务使用 name 描述具体操作
• 优先使用 ansible.builtin 模块
• 添加 when 条件控制任务执行
• 使用 register 捕获任务输出
• 通过 changed_when: false 控制任务变更状态

注释规范

• 使用 # 添加注释
• 注释应解释"为什么"，而非"做什么"
• 在复杂配置处添加必要的注释说明

安全与最佳实践

• 使用 become: yes 控制权限提升
• 避免硬编码敏感信息
• 使用 no_log: true 隐藏敏感输出
• 合理使用 backup: yes 保护现有配置

示例代码风格

---
- name: 配置服务
  hosts: servers
  become: yes

  vars:
    service_port: 8080
    enable_monitoring: true

  tasks:
    - name: 部署服务配置
      ansible.builtin.template:
        src: config.j2
        dest: /etc/service/config.yml
      when: enable_monitoring