managing-configuration

配置管理

目的

本技能介绍如何使用 Ansible 和相关工具自动化服务器及应用程序配置。内容涵盖 playbook 创建、角色结构、清单管理（静态和动态）、机密管理、测试模式和幂等性最佳实践，确保配置部署安全且可重复。

何时使用此技能

在以下情况下调用此技能：

• 创建 Ansible playbook 来配置服务器或部署应用程序
• 设计可复用的 Ansible 角色，并采用合适的目录结构
• 管理清单（静态文件或基于云的动态清单）
• 使用 ansible-vault 或 HashiCorp Vault 集成来保护机密
• 在生产部署前使用 Molecule 测试角色
• 确保 playbook 具备幂等性，可安全地多次运行
• 从 Chef 或 Puppet 迁移到 Ansible
• 实现配置即代码的 GitOps 工作流
• 调试 playbook 故障或处理程序问题

快速入门

基本 Playbook 示例

---
# site.yml
- name: Configure web servers
  hosts: webservers
  become: yes

  tasks:
    - name: Ensure nginx is installed
      apt:
        name: nginx
        state: present
      notify: Restart nginx

    - name: Start nginx service
      service:
        name: nginx
        state: started
        enabled: yes

  handlers:
    - name: Restart nginx
      service:
        name: nginx
        state: restarted

运行命令：

ansible-playbook -i inventory/production site.yml

核心概念

1. 幂等性

多次运行 playbook，不会产生意外副作用。使用基于状态的模块（present、started、latest），而不是命令式命令。

具备幂等性（推荐）：

- name: Ensure package installed
  apt:
    name: nginx
    state: present

不具备幂等性（避免使用）：

- name: Install package
  command: apt-get install -y nginx

详细模式请参阅 references/idempotency-guide.md。

2. 清单管理

静态清单： 用于稳定环境的 INI 或 YAML 文件。 动态清单： 用于云环境（AWS、Azure、GCP）的脚本或插件。

静态清单示例（INI）：

[webservers]
web1.example.com ansible_host=10.0.1.10
web2.example.com ansible_host=10.0.1.11

[webservers:vars]
nginx_worker_processes=4

动态清单设置请参阅 references/inventory-management.md。

3. 角色与 Playbook

Playbook： 编排多个任务和角色，以完成特定部署。 角色： 可复用、独立封装的配置单元，采用标准化目录结构。

标准角色结构：

roles/nginx/
├── defaults/     # Default variables
├── tasks/        # Task files
├── handlers/     # Change handlers
├── templates/    # Jinja2 templates
├── files/        # Static files
└── meta/         # Dependencies

完整的角色模式请参阅 references/role-structure.md。

4. 机密管理

ansible-vault： 用于加密敏感数据的内置工具。 HashiCorp Vault： 企业级机密管理工具，支持动态凭据。

加密机密：

ansible-vault create group_vars/all/vault.yml
ansible-playbook site.yml --ask-vault-pass

Vault 集成请参阅 references/secrets-management.md。

常见工作流

工作流 1：创建新 Playbook

步骤 1： 定义清单

# inventory/production
[webservers]
web1.example.com
web2.example.com

步骤 2： 创建 playbook 结构

---
- name: Configure application
  hosts: webservers
  become: yes

  pre_tasks:
    - name: Update package cache
      apt:
        update_cache: yes

  roles:
    - common
    - application

  post_tasks:
    - name: Verify service
      uri:
        url: http://localhost:8080/health
        status_code: 200

步骤 3： 使用检查模式进行测试

ansible-playbook -i inventory/production site.yml --check --diff

步骤 4： 执行 playbook

ansible-playbook -i inventory/production site.yml

高级模式请参阅 references/playbook-patterns.md。

工作流 2：创建并测试角色

步骤 1： 初始化角色结构

ansible-galaxy init roles/myapp

步骤 2： 定义任务

# roles/myapp/tasks/main.yml
---
- name: Install application dependencies
  apt:
    name: "{{ item }}"
    state: present
  loop: "{{ myapp_dependencies }}"

- name: Deploy application
  template:
    src: app.conf.j2
    dest: /etc/myapp/app.conf
  notify: Restart myapp

步骤 3： 添加处理程序

# roles/myapp/handlers/main.yml
---
- name: Restart myapp
  service:
    name: myapp
    state: restarted

步骤 4： 初始化 Molecule 测试

cd roles/myapp
molecule init scenario default --driver-name docker

步骤 5： 运行测试

molecule test

全面的测试模式请参阅 references/testing-guide.md。

工作流 3：设置动态清单（AWS）

步骤 1： 安装 AWS 集合

ansible-galaxy collection install amazon.aws

步骤 2： 配置动态清单

# inventory/aws_ec2.yml
plugin: aws_ec2
regions:
  - us-east-1
filters:
  tag:Environment: production
  instance-state-name: running
keyed_groups:
  - key: tags.Role
    prefix: role
hostnames:
  - tag:Name
compose:
  ansible_host: private_ip_address

步骤 3： 验证清单

ansible-inventory -i inventory/aws_ec2.yml --list

步骤 4： 运行 playbook

ansible-playbook -i inventory/aws_ec2.yml site.yml

多云模式请参阅 references/inventory-management.md。

工作流 4：使用 ansible-vault 保护机密

步骤 1： 创建加密的 vault 文件

ansible-vault create group_vars/all/vault.yml

步骤 2： 添加机密

# group_vars/all/vault.yml (encrypted)
vault_db_password: "SuperSecretPassword"
vault_api_key: "sk-1234567890"

步骤 3： 在变量中引用

# group_vars/all/vars.yml (unencrypted)
db_password: "{{ vault_db_password }}"
api_key: "{{ vault_api_key }}"

步骤 4： 在 playbook 中使用

- name: Configure database
  template:
    src: db.conf.j2
    dest: /etc/app/db.conf
  vars:
    database_password: "{{ db_password }}"

步骤 5： 使用 vault 密码运行

ansible-playbook site.yml --vault-password-file ~/.vault_pass

HashiCorp Vault 集成请参阅 references/secrets-management.md。

工具选择

何时使用 Ansible

• 在预配服务器/虚拟机后对其进行配置
• 将应用程序部署到现有基础设施
• 管理操作系统级设置（用户、软件包、服务）
• 编排跨主机的多步骤工作流
• 云原生环境（无 Agent 的 SSH/WinRM）
• 配置管理入门团队（学习曲线最平缓）

何时选择替代方案

基础设施即代码（Terraform）： 创建云基础设施资源。 Kubernetes： 容器编排与配置。 Chef/Puppet： 迁移成本高的现有部署。

Ansible 与 IaC 集成

最佳实践：Terraform 负责资源调配，Ansible 负责配置。

工作流：

1. Terraform 创建 AWS EC2 实例、安全组和负载均衡器
2. Terraform 将实例 IP 输出到 Ansible 清单
3. Ansible 配置操作系统、安装软件包并部署应用
4. Ansible 设置监控、备份和运维任务

详细的决策树请参阅 references/decision-framework.md。

测试与质量

部署前验证

步骤 1： 检查 Playbook 语法

ansible-lint playbooks/

步骤 2： 检查模式（试运行）

ansible-playbook site.yml --check --diff

步骤 3： 使用 Molecule 测试角色

cd roles/myapp
molecule test

步骤 4： 验证幂等性

molecule idempotence

配置文件

.ansible-lint：

---
exclude_paths:
  - molecule/
  - venv/
skip_list:
  - name[casing]
warn_list:
  - experimental

molecule.yml：

---
driver:
  name: docker
platforms:
  - name: instance
    image: ubuntu:22.04
    pre_build_image: true
provisioner:
  name: ansible
verifier:
  name: ansible

完整的测试策略请参阅 references/testing-guide.md。

故障排除

常见问题

连接失败：

• 验证 SSH 访问：ansible all -i inventory -m ping
• 检查 SSH 密钥：ssh -vvv user@host
• 使用密码测试：ansible-playbook site.yml --ask-pass

处理器未触发：

• 处理器仅在发生更改时运行（检查任务的 changed 状态）
• 处理器在 Playbook 末尾运行（使用 meta: flush_handlers 强制提前运行）
• 处理器名称必须完全匹配

变量未定义：

• 检查变量优先级（命令行 > Playbook > 清单 > 默认值）
• 使用 debug 模块：- debug: var=myvar
• 验证变量文件是否已加载：ansible-playbook site.yml -v

幂等性违规：

• 连续运行两次 Playbook，并比较输出
• 检查每次运行是否都显示 changed
• 使用基于状态的模块，而不是 command/shell

全面的调试指南请参阅 references/troubleshooting.md。

与其他技能集成

infrastructure-as-code：

• Terraform 调配基础设施
• Ansible 负责资源调配后的配置
• Terraform 的输出会传入 Ansible 清单

kubernetes-operations：

• Ansible 部署 K8s 集群（kubespray）
• Kubernetes 负责容器编排
• Ansible 管理节点级配置

building-ci-pipelines：

• CI/CD 运行 ansible-lint 进行质量检查
• Molecule 测试在流水线中执行
• 部署阶段运行 Playbook

secret-management：

• 简单场景使用 ansible-vault
• 企业级密钥使用 HashiCorp Vault
• 通过 Vault 查询获取动态凭据

security-hardening：

• Ansible 应用 CIS 基准
• 安全角色强制执行合规要求
• Molecule 验证安全加固效果

testing-strategies：

• 使用 Molecule 测试角色
• 使用 Testinfra 进行验证
• 集成测试套件

参考文档

• references/playbook-patterns.md - Playbook 结构、处理器、标签和变量
• references/role-structure.md - 角色目录布局、最佳实践和集合
• references/inventory-management.md - 静态、动态和混合清单模式
• references/secrets-management.md - ansible-vault 和 HashiCorp Vault 集成
• references/testing-guide.md - Molecule、ansible-lint、检查模式和验证
• references/idempotency-guide.md - 确保执行安全且可重复
• references/decision-framework.md - 工具选择和工作流设计
• references/chef-puppet-migration.md - 从旧版工具迁移到 Ansible
• references/troubleshooting.md - 常见问题和调试技巧

示例代码

• examples/playbooks/ - 完整的 Playbook 示例
• examples/roles/ - 可用于生产环境的角色模板
• examples/inventory/ - 静态和动态清单配置
• examples/molecule/ - Molecule 测试场景

实用脚本

• scripts/validate-playbook.py - 验证 playbook 语法和结构
• scripts/generate-inventory.py - 根据云服务提供商生成清单
• scripts/ansible-vault-helper.sh - Vault 管理工具
• scripts/molecule-runner.sh - 自动执行 Molecule 测试