隨著 Ansible 版本（ansible-core）持續升級，除了控制端（Control Node）本身的改進外，Ansible 對受控端（Managed Node / Target Host）的 Python 或 PowerShell 版本要求也隨之提高。

如果在企業內部環境中，受限於維運規範無法輕易升級受控端的 Python 或 PowerShell，透過 Execution Environment (EE) 將特定版本的 Ansible、Python 執行環境與 Collection 封裝在容器中，便能輕鬆維持與舊主機的環境相容性。

本文將介紹如何使用 pipx 安裝 ansible-navigator、配置設定檔並使用 Execution Environment 執行 Playbook。

為什麼需要 ansible-navigator？

以往在 Control Node 上直接執行 ansible-playbook 時，所有的 Python 依賴套件、Ansible 版本與 Collection 都直接依賴本機作業系統環境，容易遇到以下痛點：

  1. 環境污染與衝突：不同專案可能需要不同版本的 Collection 或 Python 函式庫。
  2. 目的端版本不相容：新版 Ansible 不再支援受控端過舊的 Python 版本（例如 Python 2.7 或 3.6）。
  3. 環境一致性問題：本機端測試通過的 Playbook，在 CI/CD 或同事電腦上可能因環境差異而失敗。

Ansible 官方推出的 ansible-navigator 搭配容器化 Execution Environment (EE)，透過 Docker 或 Podman 啟動容器來執行 Playbook，讓自動化環境達到高度隔離與標準化。

1. 使用 pipx 安裝 ansible-navigator

以往官方常建議使用 pip install --user ansible-navigator 進行安裝，但此方式容易污染使用者的 Python 環境或造成套件衝突。

推薦改用 pipx 進行安裝。pipx 會自動為每個 CLI 工具建立獨立的 Python 虛擬環境（virtual environment），並將執行檔連結到系統路徑中，既乾淨又便於管理。

在 Ubuntu / Debian 上安裝

# 安裝 pipx
sudo apt update
sudo apt install -y pipx
pipx ensurepath

# 安裝 ansible-navigator
pipx install ansible-navigator

安裝完成後，可執行以下指令確認版本：

ansible-navigator --version

2. 產生與配置設定檔 (ansible-navigator.yml)

安裝完成後，建議在專案根目錄或家目錄產生 ansible-navigator.yml 設定檔，省去每次執行指令時手動輸入一長串參數的麻煩。

產生設定檔範本（注意避坑）

# 先輸出到暫存檔
ansible-navigator settings --sample > ansible-navigator-new.yml

# 再更名為正式設定檔
mv ansible-navigator-new.yml ansible-navigator.yml

💡 小提醒：建議先導出至暫存檔（如 ansible-navigator-new.yml）再更名。若直接重導向到 ansible-navigator.yml，Shell 在執行前會先建立空檔案，此時 ansible-navigator 讀取到空檔案會判定設定錯誤而中斷執行。

3. 選擇 Execution Environment (EE) 容器映像檔

ansible-navigator 會透過容器引擎（Podman 或 Docker）拉取 EE 映像檔來執行任務。

經過實際測試，社群維護的 giuffrelab/awx-community-general-ee:31 穩定性良好且預載常用 collection。

4. ansible-navigator.yml 設定檔範例

以下為推薦的 ansible-navigator.yml 配置內容：

---
ansible-navigator:
  ansible:
    config:
      help: False
      path: ./ansible.cfg # 指定 ansible.cfg 路徑
    cmdline: "--forks 10" # 額外傳入 ansible 的參數
    doc:
      help: False
      plugin:
        name: debug
        type: module
    inventory:
      help: True
      entries: []
    playbook:
      help: False

  ansible-builder:
    help: False
    workdir: /tmp/

  ansible-runner:
    artifact-dir: ./runner-artifacts
    rotate-artifacts-count: 10
    timeout: 300
    job-events: True

  app: welcome
  collection-doc-cache-path: $HOME/.cache/ansible-navigator/collection_doc_cache.db

  color:
    enable: True
    osc4: True

  editor:
    command: vim
    console: True

  enable-prompts: True

  exec:
    shell: True
    command: /bin/bash

  execution-environment:
    # 容器引擎：auto (優先使用 podman，其次 docker)
    container-engine: auto
    # 傳入容器的額外參數
    container-options:
      - "--net=host"
    enabled: True
    environment-variables:
      set:
        AWS_PAGER: ""
    # 指定使用的 Execution Environment 映像檔
    image: giuffrelab/awx-community-general-ee:31
    pull:
      policy: missing # 僅在本地不存在時才 pull

  format: json

  images:
    details:
      - ansible_collections
      - ansible_version

  inventory-columns:
    - ansible_network_os
    - ansible_network_cli_ssh_type
    - ansible_connection

  logging:
    level: debug
    append: False
    file: /tmp/ansible-navigator.log

  # mode 可設為 stdout（傳統文字輸出）或 interactive（TUI 互動介面）
  mode: stdout

  playbook-artifact:
    enable: True
    replay: /tmp/test_artifact.json
    save-as: "{playbook_dir}/{playbook_name}-artifact-{time_stamp}.json"

  settings:
    effective: False
    sample: False
    schema: json
    sources: False

  time-zone: Asia/Taipei

完整設定項目與說明可參考官方文件：Ansible Navigator Settings。

5. 執行 Playbook 與常用指令

設定完成後，原本使用 ansible-playbook 執行的工作即可改用 ansible-navigator run：

# 執行 Playbook
ansible-navigator run site.yml \
  -i inventory.ini \
  -e "var1=value1"

其他常用子命令

除了執行 Playbook 外，ansible-navigator 亦整合了多項強大功能：

  • 查閱模組文件： 
    ansible-navigator doc ansible.builtin.copy
  • 檢視目前環境中的 Collections： 
    ansible-navigator collections
  • 檢視 EE 容器映像檔細節： 
    ansible-navigator images
  • 重播先前的執行紀錄（Artifact）： 
    ansible-navigator replay ./runner-artifacts/site-artifact-xxxx.json

結語

透過 ansible-navigator 與 Execution Environment（EE），不僅能將自動化執行環境完全標準化與容器化，更能在不升級目的端老舊主機 Python / PowerShell 的限制下，靈活切換不同版本的 ansible-core 與 Collection，是維護異質環境非常實用且優雅的解決方案。