一、Ansible连接失败的那些坑

新手最容易栽跟头的地方就是连接问题。最常见的就是SSH连接失败，这通常发生在第一次使用Ansible的时候。比如你兴冲冲地写好了playbook，一运行却看到"UNREACHABLE"的错误提示。

让我们看一个典型的连接问题示例（技术栈：Ansible + Linux）：

# playbook示例：test_connect.yml
- hosts: web_servers  # 目标主机组
  become: yes         # 使用sudo权限
  tasks:
    - name: Test connection
      ping:           # 使用Ansible的ping模块测试连接

运行这个playbook时可能会遇到几种常见错误：

  1. 认证失败：通常是SSH密钥或密码不正确
  2. 主机不可达：可能是网络问题或主机名解析失败
  3. 权限不足：没有使用become或become_method设置正确

解决方案其实很简单，首先确保你的inventory文件配置正确：

# inventory文件示例
[web_servers]
web1.example.com ansible_user=deploy ansible_ssh_private_key_file=~/.ssh/deploy_key
web2.example.com ansible_user=deploy ansible_password=YourPassword123

二、变量使用中的陷阱

变量是Ansible的强大功能，但也是最容易出错的地方之一。新手常常在变量优先级和作用域上栽跟头。

看这个例子（技术栈：Ansible + Linux）：

# 问题示例：vars_error.yml
- hosts: all
  vars:
    app_port: 8080
  tasks:
    - name: Show port
      debug:
        msg: "Port is {{ port }}"  # 这里会报错，因为变量名错了

正确的做法应该是：

# 修正后的示例：vars_correct.yml
- hosts: all
  vars:
    app_port: 8080
  tasks:
    - name: Show port
      debug:
        msg: "Port is {{ app_port }}"  # 使用正确的变量名

更复杂的情况是变量优先级的问题。Ansible有超过20种设置变量的方式，优先级从高到低依次是：命令行变量 > play变量 > host变量 > group变量等等。

三、任务执行顺序的玄学

Ansible的默认执行顺序是线性的，但有时候我们需要控制任务的执行顺序。比如，在配置服务前需要先安装软件包。

看这个常见错误示例（技术栈：Ansible + Nginx）：

# 问题示例：order_error.yml
- hosts: web_servers
  tasks:
    - name: Start Nginx
      service:
        name: nginx
        state: started
    
    - name: Install Nginx
      apt:
        name: nginx
        state: present

显然，正确的顺序应该是先安装再启动：

# 修正后的示例：order_correct.yml
- hosts: web_servers
  tasks:
    - name: Install Nginx
      apt:
        name: nginx
        state: present
    
    - name: Start Nginx
      service:
        name: nginx
        state: started
      notify: reload nginx  # 添加handler触发

四、Handler的误用与滥用

Handler是Ansible中用于响应变更的特殊任务，但很多人对它的理解有误。

常见错误1：过度使用handler。不是所有任务都需要handler。

# 不推荐的handler使用方式
handlers:
  - name: restart everything
    service:
      name: "{{ item }}"
      state: restarted
    with_items:
      - nginx
      - mysql
      - redis

常见错误2：忘记handler只在任务changed时触发。如果你总是需要执行某个操作，应该使用普通任务而不是handler。

正确的handler使用示例（技术栈：Ansible + Apache）：

# 推荐的handler使用方式
- hosts: web_servers
  tasks:
    - name: Update Apache config
      template:
        src: httpd.conf.j2
        dest: /etc/httpd/conf/httpd.conf
      notify: restart apache  # 只有配置文件改变时才触发重启

  handlers:
    - name: restart apache
      service:
        name: httpd
        state: restarted

五、模板渲染的常见问题

Jinja2模板是Ansible的强大功能，但语法错误和变量未定义是最常见的问题。

看这个有问题的模板示例（技术栈：Ansible + Jinja2）：

# 问题模板：nginx.conf.j2
server {
    listen {{ port }};  # 如果port变量未定义会报错
    server_name {{ server_name }};
}

更好的做法是提供默认值：

# 改进后的模板：nginx.conf.j2
server {
    listen {{ port | default(80) }};  # 提供默认值
    server_name {{ server_name | default('localhost') }};
}

另一个常见问题是忘记转义特殊字符。比如在模板中需要使用{{字面量}}时，应该使用{% raw %}...{% endraw %}包裹。

六、循环使用中的坑

Ansible提供了多种循环方式，但每种都有其适用场景。

常见错误1：过度使用with_items。在较新版本的Ansible中，推荐使用loop。

# 不推荐的循环方式
- name: Add several users
  user:
    name: "{{ item.name }}"
    state: present
    groups: "{{ item.groups }}"
  with_items:
    - { name: 'test1', groups: 'wheel' }
    - { name: 'test2', groups: 'root' }

更现代的写法是：

# 推荐的循环方式
- name: Add several users
  user:
    name: "{{ item.name }}"
    state: present
    groups: "{{ item.groups }}"
  loop:
    - { name: 'test1', groups: 'wheel' }
    - { name: 'test2', groups: 'root' }

常见错误2：在不需要循环的地方使用循环。有时候使用Ansible的批量操作功能更高效。

七、角色组织的艺术

角色(role)是Ansible组织代码的主要方式，但糟糕的角色结构会让维护变得困难。

常见错误1：把所有东西都塞进一个角色。这会导致角色过于庞大难以维护。

常见错误2：角色之间过度耦合。好的角色应该尽可能独立。

推荐的角色结构示例：

roles/
    common/
        tasks/
        handlers/
        templates/
        files/
        vars/
        defaults/
        meta/
    webserver/
        tasks/
        ...
    database/
        tasks/
        ...

在meta/main.yml中定义角色依赖关系：

# roles/webserver/meta/main.yml
dependencies:
  - { role: common, some_parameter: 3 }

八、性能优化的关键点

随着管理的主机数量增加，性能问题会逐渐显现。以下是几个关键优化点：

  1. 启用流水线(pipelining)：在ansible.cfg中设置

    [ssh_connection]
pipelining = True

  2. 使用策略插件：比如free策略可以加快playbook执行

    - hosts: all
  strategy: free
  tasks:
    ...

  3. 减少gather_facts：如果不需要系统信息，可以禁用

    - hosts: all
  gather_facts: no
  tasks:
    ...

  4. 使用异步任务：对于长时间运行的任务

    - name: Run long task
  command: /usr/bin/long_running_operation
  async: 3600  # 超时时间(秒)
  poll: 0      # 不等待完成

九、调试技巧大全

当遇到问题时，以下调试技巧可能会帮到你：

  1. 使用-v或-vvv参数增加输出详细程度

    ansible-playbook playbook.yml -vvv

  2. 调试特定主机

    ansible-playbook playbook.yml --limit problem_host

  3. 使用debug模块输出变量值

    - name: Debug variables
  debug:
    var: hostvars[inventory_hostname]

  4. 检查模板渲染结果

    ansible localhost -m template -a "src=template.j2 dest=/tmp/output.txt"

  5. 使用--check模式进行试运行

    ansible-playbook playbook.yml --check

十、最佳实践总结

经过多年的Ansible使用经验，我总结了以下最佳实践：

  1. 保持playbook简洁：每个playbook只做一件事
  2. 使用版本控制：所有Ansible代码都应该纳入Git等版本控制系统
  3. 文档化：为每个角色和playbook添加清晰的注释和README
  4. 测试：使用Molecule等工具测试你的角色
  5. 安全性：使用ansible-vault保护敏感信息
  6. 模块化：尽量使用官方模块而不是raw/command/shell
  7. 幂等性：确保playbook可以安全地重复运行
  8. 环境分离：区分dev/staging/production环境
  9. 定期更新：保持Ansible和模块的版本更新
  10. 监控：监控自动化任务的执行情况和结果