Ansible playbook 與 role:何時該用哪個?
了解 Ansible 扁平 playbook 何時已足夠,以及何時應改用 role;涵蓋 role 目錄結構、ansible-galaxy init、role 呼叫與變數優先順序。
Ansible playbook 與 role:有何差異
Ansible playbook 是使用 ansible-playbook 執行的檔案。它會將一組主機對應至這些主機需要執行的工作。Ansible role 是採用固定目錄結構的目錄,用來存放工作、範本、處理常式與預設變數,而 playbook 會依名稱呼叫它。兩者內部的工作語法完全相同,因此問題不在於能表達哪些內容,而在於是否能重複使用。
先從扁平的 playbook 開始。第一個自動化專案使用一個包含 tasks: 清單的 site.yml 是正確的結構,而且這種結構適用的時間通常比多數人預期更久。當同一組工作必須對第二組主機執行,或檔案超過約 100 行,導致無法再透過捲動尋找工作時,再將它轉換為 role。
如果你尚未撰寫 playbook,請先針對單一 VPS 開始撰寫第一個 playbook,等它開始變大後再回來。
扁平 playbook 適用的情況
在工作只執行一次、只針對一台主機,或不會有其他人閱讀時,扁平 playbook 是正確的選擇。例如佈建單一應用程式伺服器,或在維護時段前為主機套用修補程式,都不需要建立目錄樹。role 會增加 7 個目錄和一層間接引用。如果唯一的呼叫端就是旁邊的 playbook,這層間接引用沒有帶來任何好處,卻讓你每次想查看實際執行內容時,都必須多跳轉一次。
扁平 playbook 在某個明確時刻就不再適用,而且很容易辨認。當你把一段 tasks 複製到第二個 playbook 時,這就是訊號。從那一刻起,每項修正都必須套用 2 次,而某一天你只會套用 1 次。
實際上,role 目錄包含哪些內容
roles/common/
defaults/main.yml
vars/main.yml
tasks/main.yml
handlers/main.yml
templates/99-hardening.conf.j2
files/
meta/main.ymltasks/main.yml是進入點。呼叫 role 時,Ansible 會執行這個檔案,其他目錄則全部是選用項目。defaults/main.yml存放預期由呼叫端覆寫的變數。它是 Ansible 中優先順序最低的來源,因此幾乎所有其他來源都會覆寫它。vars/main.yml存放預期不由呼叫端覆寫的變數。它的優先順序高於 inventory,因此這是需要審慎使用的設定。請少量使用。handlers/main.yml存放由notify觸發的工作。handler 會在 play 結束時執行一次,不論有多少工作通知它。files/存放由copymodule 原樣複製的檔案,templates/則存放由templatemodule 渲染的 Jinja2 template。在 role 內參照這兩者時,使用不含路徑的檔名即可,因為 Ansible 會優先搜尋 role 自身的目錄。meta/main.yml宣告 role 相依性,以及 Ansible Galaxy 讀取的中繼資料。
這種目錄配置不是風格偏好。Ansible 只會搜尋這些確切路徑,因此放在 roles/common/template/(單數形式)中的 template 根本不會被找到。
使用 ansible-galaxy init 建立 common role
mkdir -p ~/infra/roles
cd ~/infra
ansible-galaxy init --init-path roles common這會在 roles/common 下建立完整的骨架,包括不會使用的目錄,以及只包含 --- 的 main.yml 樣板。刪除會保持空白的項目。空的 vars/main.yml 對 Ansible 沒有影響,但會讓人難以判斷 role 中哪些檔案實際上重要。
現在填入實際執行工作的檔案。先處理 defaults,因為它們是 role 的公開介面。
# roles/common/defaults/main.yml
---
common_packages:
- ufw
- fail2ban
- unattended-upgrades
common_admin_group: admins
common_permit_root_login: "no"
common_password_authentication: "no"為 "no" 與 "yes" 加上引號。Ansible 使用 PyYAML 解析 YAML,而 PyYAML 會將未加引號的 no 讀成布林值 false,因此產生的設定行會變成 PermitRootLogin False,sshd 便會拒絕該設定。加上引號可確保該值維持字串。
# roles/common/tasks/main.yml
---
- name: Install the base packages
ansible.builtin.apt:
name: "{{ common_packages }}"
state: present
update_cache: true
cache_valid_time: 3600
- name: Create the admin group
ansible.builtin.group:
name: "{{ common_admin_group }}"
state: present
- name: Install the sshd hardening drop-in
ansible.builtin.template:
src: 99-hardening.conf.j2
dest: /etc/ssh/sshd_config.d/99-hardening.conf
owner: root
group: root
mode: "0644"
validate: /usr/sbin/sshd -t -f %s
notify: Restart sshd# roles/common/handlers/main.yml
---
- name: Restart sshd
ansible.builtin.service:
name: ssh
state: restarted# roles/common/templates/99-hardening.conf.j2
# Managed by Ansible. Local edits are overwritten on the next run.
PermitRootLogin {{ common_permit_root_login }}
PasswordAuthentication {{ common_password_authentication }}在 Debian 和 Ubuntu 上,systemd unit 名稱是 ssh;在 RHEL 系列系統上則是 sshd。如果 handler 指定了錯誤的 unit,只有在範本確實發生變更時才會失敗,因此通常要到數週後才會暴露。
工作中的 validate 行最有用。Ansible 會將範本轉換成暫存檔,把該檔案的路徑代入 %s,然後執行命令。只有命令以 0 結束時,才會取代目的檔案。請在範本中加入無效指令並再次執行:工作會因 failed to validate 而失敗,實際的 /etc/ssh/sshd_config.d/99-hardening.conf 不會被修改,伺服器仍可供你登入。請注意,這項檢查不只會驗證語法。如果 sshd -t 無法讀取主機金鑰,會以 sshd: no hostkeys available -- exiting. 結束,Ansible 也會回報相同的 failed to validate。因此,在判定範本有問題前,請先閱讀模組的 msg。
角色如何由 play 呼叫
# site.yml
---
- name: Base configuration for every server
hosts: all
become: true
roles:
- common# inventory.ini
[local]
localhost ansible_connection=localansible-playbook -i inventory.ini site.ymlPlay 應在摘要中以 failed=0 結束。在呼叫位置使用展開形式傳遞參數,這樣同一個角色就能服務兩組主機:
roles:
- role: common
common_admin_group: ops
common_permit_root_login: prohibit-password有一項排序規則幾乎會讓所有人感到意外。Play 可以包含 pre_tasks、roles、tasks 和 post_tasks,而 Ansible 會依該順序執行,無論你在檔案中採用何種排列順序。將 tasks: 寫在 roles: 上方,角色仍會先執行。因此,如果某項工作必須在角色之前執行,就應放在 pre_tasks:,而不是 tasks: 的開頭。
- name: Ordering demonstration
hosts: local
gather_facts: false
pre_tasks:
- name: Runs first
ansible.builtin.debug:
msg: pre
roles:
- common
tasks:
- name: Runs after the role
ansible.builtin.debug:
msg: task
post_tasks:
- name: Runs last
ansible.builtin.debug:
msg: post若要從工作清單內呼叫角色,而不是使用 roles: 鍵,請使用 import_role 或 include_role。
tasks:
- name: Static, read when the playbook is parsed
ansible.builtin.import_role:
name: common
- name: Dynamic, resolved when the task runs
ansible.builtin.include_role:
name: postgres
when: "'db' in group_names"import_role 是靜態的。Ansible 會在剖析時讀取角色,其工作會成為 play 的一部分,因此 ansible-playbook --list-tasks site.yml 會列出這些工作,而匯入項目上的標籤會套用至其中每項工作。include_role 是動態的。直到工作執行時才會讀取內容,因此可以透過變數或迴圈指定角色名稱。代價是,這些工作不會顯示在 --list-tasks 和 --start-at-task 中。
這裡有一個容易踩到的陷阱。include_role 工作上的 when:,會在被納入角色的 defaults/main.yml 進入作用域之前評估。在匯入項目上寫入 when: common_packages | length > 0,執行就會因 'common_packages' is undefined 而停止,即使該變數確實定義在你正在納入的角色中。修正方式是將這個切換設定移出角色:放在 group_vars/all.yml 中,讓它在所有位置都可用,並將角色的預設值保留給角色本身使用。
哪個變數優先:defaults、group_vars、vars、extra vars
Ansible 記錄了 20 多個變數優先順序層級。其中 4 個幾乎能解決所有實務上的爭議,以下依優先順序由低到高列出。
roles/<name>/defaults/main.yml位於接近底部的位置。幾乎任何在其他位置設定的值都會覆寫它,因此它正適合存放 role 可調整的參數。group_vars/和host_vars/位於中間。網站本身的設定值應放在這裡,而且能明確覆寫 role 預設值。roles/<name>/vars/main.yml的優先順序高於host_vars。在這裡設定的值無法從 inventory 覆寫。請保留給 role 必須維持內部一致性的項目,例如必須與服務名稱相符的套件名稱。- 在呼叫端傳入的 role 參數會覆寫
vars/main.yml,而在命令列上設定的-e會覆寫所有內容,包括 role 參數。
你可以在約 1 分鐘內觀察這個解析結果。先為一個小型 role 設定 1 個預設值和 1 個 role 變數,再於 host_vars 中設定相同的名稱。
# roles/prec/defaults/main.yml
---
prec_tunable: from-defaults
prec_internal: from-defaults# roles/prec/vars/main.yml
---
prec_internal: from-rolevars# host_vars/localhost.yml
---
prec_tunable: from-hostvars
prec_internal: from-hostvars# roles/prec/tasks/main.yml
---
- name: Show which value survived
ansible.builtin.debug:
msg: "tunable={{ prec_tunable }} internal={{ prec_internal }}"ansible-playbook -i inventory.ini prec.yml
ansible-playbook -i inventory.ini prec.yml -e prec_internal=from-cli第一次執行會輸出 tunable=from-hostvars internal=from-rolevars。Inventory 覆寫了 role 預設值,但優先順序低於 role 變數。第二次執行會輸出 internal=from-cli,因為 extra vars 位於最頂層,下面的任何設定都無法覆寫它。這也是 -e 適合一次性執行,卻不適合放在持續使用的 script 中的原因:它會在不明顯的情況下,優先於 repository 中所有經過考量的設定。
實務規則是:如果希望某個值可由使用者設定,就應放在 defaults/ 中。將它放入 vars/,等於告訴日後所有使用此 role 的人,inventory 不得變更它。這有時確實是你的目的,但通常只是意外。
證明 role 具備冪等性:執行兩次
值得信任的 Ansible 執行結果,第二次應與第一次相同,並顯示沒有任何變更。執行兩次 playbook,然後查看摘要。
ansible-playbook -i inventory.ini site.yml
ansible-playbook -i inventory.ini site.yml第二次的摘要應如下:
PLAY RECAP *********************************************************************
localhost : ok=4 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0changed=0 表示沒有任何 task 回報變更。對於 apt、template 和 group 等模組,這確實會檢查目前狀態;但結果是否可信,取決於每個 task 是否正確回報變更:使用 changed_when: false 的 task,無論實際執行了什麼,都會被計為未變更。第二次執行時出現 changed=2,表示有兩個 task 再次回報變更。這可能代表確實重複執行了工作,例如每次都重寫檔案或重新啟動服務;也可能只是唯讀命令無法表示自己未進行任何變更。無論是哪種情況,摘要都無法再告訴你伺服器是否發生狀態漂移。常見原因是 command 或 shell,因為 Ansible 無法得知任意命令實際做了什麼。
# traps.yml
---
- name: Command modules do not know what they changed
hosts: local
gather_facts: false
tasks:
- name: This appends a line on every run
ansible.builtin.shell: "echo run >> /tmp/grow.txt"
- name: This appends a line only once
ansible.builtin.shell: "echo run >> /tmp/guarded.txt"
args:
creates: /tmp/guarded.txt執行該 playbook 兩次,然後計算包含 wc -l /tmp/grow.txt /tmp/guarded.txt 的行數。/tmp/grow.txt 會包含兩行,而 /tmp/guarded.txt 會包含一行。第二次執行時,受條件保護的 task 根本沒有執行:它會以訊息 Did not run command since '/tmp/guarded.txt' exists 回報 ok,因為 creates 會先讓模組尋找可見的產出。若命令不會留下這類產出,請註冊其輸出,並使用 changed_when 自行判斷。
ansible-playbook --check --diff site.yml 會預測變更而不實際套用,--diff 則會列出 template 將要重寫的確切行內容。解讀輸出時請注意一項限制:純粹的 shell 或 command task 在 check mode 中會被略過(搭配 creates 或 removes 時,只會回報是否會執行),而標記為 check_mode: false 的 task 即使在 --check 下也會實際執行。因此,看似乾淨的計畫仍可能隱藏實際工作,dry run 也不一定完全不會修改狀態。
摘要中還有一個欄位同樣需要仔細解讀:Ansible 無法連線的主機會計入 unreachable,而不是 failed;該主機的任何 task 都完全不會執行。因此,將此 role 指向超過幾台機器前,請先預先決定單一無法連線的主機是否應中止整次執行。
為什麼 Ansible 顯示找不到 role
Ansible 會先在 playbook 檔案旁尋找 roles/ 目錄,接著才搜尋 roles_path。搜尋依據是 playbook 的位置,不是 shell 的目前目錄。
[ERROR]: The role 'common' was not found in: /home/deploy/lonely/roles:/home/deploy/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles:/home/deploy/lonely這則訊息表示 site.yml 與 roles/ 不一致,並會列出實際嘗試過的路徑。這是 ansible-core 2.21 使用的文字;較舊版本會顯示開頭為小寫且不含冒號的 the role 'common' was not found in,因此應比對 was not found in。請將兩者放在同一個目錄。從父目錄執行也沒有問題,因為實際生效的是 playbook 路徑:
ansible-playbook -i infra/inventory.ini infra/site.yml同一問題還有一種不易察覺的情況。若目前目錄允許所有使用者寫入,Ansible 會忽略其中的 ansible.cfg,因為主機上的任何使用者都能在該處放入設定檔,進而改變執行結果。
[WARNING]: Ansible is being run in a world writable directory (/tmp/infra), ignoring it as an ansible.cfg source. For more information see https://docs.ansible.com/ansible/devel/reference_appendices/config.html#cfg-in-world-writable-dir此時 roles_path 與 inventory 設定會在沒有提示的情況下失效,role 查找也會因此失敗,原因與 role 本身無關。ansible --version 會列出實際載入的 config file,而 ansible-config dump --only-changed 會列出所有與內建預設值不同的設定。只要執行結果看起來像是設定檔不存在,就應檢查這兩項。
角色共用:requirements.yml 與固定版本
其他人撰寫的角色應透過安裝取得,而不是直接複製。請宣告一次:
# requirements.yml
---
roles:
- name: postgres
src: https://github.com/example/ansible-role-postgres
scm: git
version: v1.4.0ansible-galaxy install -r requirements.yml -p galaxy_roles務必設定 version。未設定時,指令會取得執行當日預設分支中的內容。因此,上個月還能正常執行的部署,可能在自己的 repository 完全未變更的情況下失敗。將 roles_path 指向下載目錄,並將該目錄排除在 git 之外:
# ansible.cfg
[defaults]
inventory = inventory.ini
roles_path = ./galaxy_rolesplaybook 旁 roles/ 中的角色仍會被找到,因為除了 roles_path 之外,系統也一定會搜尋該路徑。因此,您自己的角色可持續提交並接受審查;第三方角色則是固定至標籤且可重現的下載內容。
角色不再是解答的情況
角色是單次 Ansible 執行中的重複使用單位。它不會在您的供應商平台建立伺服器或 DNS 記錄。若試圖讓角色負責這些工作,playbook 很快就會變成無人願意維護的內容。開始之前,建議先閱讀 Ansible 與 Terraform 的工作分工。角色也不能取代 inventory 設計:管理的機器超過少數幾台後,如何分組及連線到這些伺服器,比任務如何歸檔更重要。
這個 common 角色安裝的強化設定,也需要個別決策。上述 drop-in 只設定兩個指令,沒有其他設定。因此,在決定哪些內容應套用到您管理的每台主機之前,請先閱讀 哪些 SSH 設定確實值得修改,以及 如何讓 Ubuntu 自動套用安全更新。
FAQ
何時應將 Ansible playbook 改成 role?
當同一組工作必須在第二個 play 中執行,或必須對第二組主機執行時,就應考慮改成 role。開始在不同 playbook 之間複製工作,就是明確訊號。因為從那時起,每個修正都必須套用兩次,而且某天可能只套用一次。若單一 playbook 約少於 100 行,且始終只針對一組主機,使用 role 不會帶來好處,額外的目錄反而會降低可讀性。
Role 會在同一個 play 的 tasks 之前執行嗎?
會。Ansible 會先執行 pre_tasks,接著執行 roles: 下列出的所有項目,再執行 tasks:,最後執行 post_tasks:;這與這些鍵在檔案中的出現順序無關。將 tasks: 寫在 roles: 上方,不會讓那些工作先執行。若某項工作必須在 role 之前發生,請將它放在 pre_tasks: 中。
為什麼我的 group_vars 值無法覆寫 role 中的值?
請確認該變數是否設定在 role 的 vars/main.yml,而不是 defaults/main.yml。在 Ansible 的優先順序中,vars/ 高於 group_vars 與 host_vars,因此 inventory 無法覆寫它。請將變數移至 defaults/main.yml。它在優先順序中接近底部,適合放置任何呼叫端應能變更的值。若要確認原因確實是優先順序而非拼字錯誤,請使用 -e name=value 執行一次。它的優先順序高於其他所有來源。
為什麼 Ansible 顯示找不到 role?
搜尋會從 playbook 檔案旁開始,因此 site.yml 與 roles/ 必須位於同一個目錄中。錯誤訊息會列出 Ansible 嘗試過的路徑,並從 The role 'common' was not found in: /home/deploy/lonely/roles 開始。從父目錄執行 playbook 沒有問題,因為搜尋會依循 playbook 路徑,而不是 shell 的工作目錄。若依賴 ansible.cfg 中的 roles_path,請使用 ansible --version 確認該檔案已載入,因為全域可寫入的工作目錄會使 Ansible 忽略該檔案。
建立 role 時一定要使用 ansible-galaxy init 嗎?
不需要。Role 只是使用預期名稱建立的目錄,因此 mkdir -p roles/common/tasks 加上 tasks/main.yml 就已經是可運作的 role。ansible-galaxy init --init-path roles common 可減少輸入,並提供完整的骨架,包括 meta/main.yml 與 README 樣板。請刪除留下空白的目錄,因為空的 vars/main.yml 會掩蓋 role 中實際有作用的檔案。