今日目標

• 大家來分享各自遇到有趣的故事吧
• 學會 Ansible 常見錯誤的診斷與解法

常見的 Ansible 錯誤問題

1. SSH 連線問題

UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host via ssh"}

UNREACHABLE! => {"changed": false, "msg": "Authentication failure"}

排查的步驟：

# 第一步：先確認基本連線
ansible all -i inventory.ini -m ping

# 第二步：用 SSH 手動連看看
ssh -v user@target-server

# 第三步：檢查 inventory 設定
ansible-inventory -i inventory.ini --list

💡 Tips：我現在習慣先用 ssh-copy-id 把金鑰複製到所有機器，可以省掉很多麻煩。

2. 權限問題

FAILED! => {"msg": "Missing sudo password"}
FAILED! => {"msg": "User is not in the sudoers file"}

# 養成好習慣
- name: Install packages
  package:
    name: nginx
    state: present
  become: yes                   # 筆者建議：所有系統操作都要加這個
  become_user: root             # 明確指定用戶
  become_method: sudo           # 明確指定方法

3. 變數未定義問題

FAILED! => {"msg": "AnsibleUndefinedVariable: 'database_host' is undefined"}

# 善用 jinja2 的特性，可以加上 default 值，就不會一直遇到這個問題了
- name: 連接資料庫
  mysql_user:
    name: "{{ app_user }}"
    host: "{{ database_host | default('localhost') }}" 
    password: "{{ db_password | default('changeme') }}"

Ansible 除錯常見工具

1. 詳細輸出模式

ansible-playbook site.yml -v        # 平常測試用這個就夠
ansible-playbook site.yml -vv       # 出問題時用這個
ansible-playbook site.yml -vvv      # 複雜問題必用，超詳細
ansible-playbook site.yml -vvvv     # 絕招，什麼都看得到 (但輸出有點多)

筆者的實戰範例：

# 當筆者遇到莫名其妙的錯誤時，一定會這樣做
ansible-playbook -i production deploy.yml -vvv --limit problematic-server
# 通常看了詳細輸出就知道問題在哪了

2. Debug Module

---
- name: Debug Sample
  hosts: all
  tasks:
    - name: 收集系統資訊
      setup:
      register: system_info

    - name: 顯示筆者關心的系統資訊
      debug:
        msg:
          - "主機名稱: {{ inventory_hostname }}"
          - "IP 位址: {{ ansible_default_ipv4.address }}"
          - "系統版本: {{ ansible_distribution }} {{ ansible_distribution_version }}"
          - "記憶體大小: {{ ansible_memtotal_mb }}MB"

    - name: 檢查設定檔是否存在
      stat:
        path: /etc/nginx/nginx.conf
      register: nginx_config

    # 小技巧：用 verbosity 控制輸出層級
    - name: 顯示檔案狀態詳情
      debug:
        var: nginx_config
        verbosity: 2  # 只有用 -vv 以上才會顯示，避免輸出太雜亂

    - name: 筆者的條件式除錯
      debug:
        msg: "太好了！Nginx 設定檔存在且可讀取 🎉"
      when: nginx_config.stat.exists and nginx_config.stat.readable

3. 檢查模式

筆者現在執行任何 Playbook 之前，都會先用檢查模式跑一遍：

# 1. 先檢查會做什麼改變 (超重要！)
ansible-playbook site.yml --check

# 2. 看看具體會改什麼檔案 (筆者必做)
ansible-playbook site.yml --check --diff

# 3. 只檢查特定部分 (筆者常用技巧)
ansible-playbook site.yml --check --tags database

# 筆者現在都會在 Playbook 裡加入這種檢查
- name: 筆者的服務狀態檢查
  service_facts:
  register: service_status

- name: 確認關鍵服務正常運行
  assert:
    that:
      - "'nginx.service' in service_status.ansible_facts.services"
      - "service_status.ansible_facts.services['nginx.service'].state == 'running'"
    fail_msg: "慘了！Nginx 服務掛了 😱"
    success_msg: "太好了！Nginx 服務正常運行 ✅"

4. 限制執行範圍

# 只在特定群組執行 (安全第一)
ansible-playbook site.yml --limit web-servers

# 只在出問題的機器執行 (筆者最愛用這招)
ansible-playbook site.yml --limit "web-01,web-02"

# 使用模式匹配 (很方便)
ansible-playbook site.yml --limit "web-*"

# 排除特定機器 (當某台機器有問題時超好用)
ansible-playbook site.yml --limit "all:!problematic-server"

閒話家常

四大維運原則

• 預防勝於治療：多花時間設計良好的檢查機制，總比每次半夜一直被 call 起來修 bug 好
• 自動化一切：工程師的宗旨之一能夠自動化絕不手動
• 詳細記錄：千萬不要覺得 log、monitor、document 做起來很麻煩，但每當出現問題時這些東西會非常重要
• 小步快跑：盡量不要做大幅度的調整，一次改一點，慢慢地做迭代，會比較安全

成長建議

• 多看官方文件，非常重要，因為很多官方都會提供最佳實務的範例參考，跟著做基本上不會有什麼大問題
• 多加入社群，學習別人的經驗
• 記得要定期回顧和改進自己的維運流程

作業練習時間

練習一：筆者建議的故障診斷實戰

1. 故意在 Playbook 中製造問題，練習筆者教的診斷技巧
2. 嘗試用不同的 v 等級來找問題
3. 練習用 debug 模組來追蹤變數值

明日預告

明天來聊聊安全性！