てくなべ (tekunabe)

ansible / network automation / 学習メモ

[Ansible] ansible-navigator 2.0.0 新機能ピックアップ Part 2: その他編

はじめに

先日、ansible-navigator 2.0.0 がリリースされました。

Release v2.0.0 · ansible/ansible-navigator · GitHub

前回の記事で、追加されたサブコマンドを取り上げました。

tekunabe.hatenablog.jp

今回はそれ以外の気になったものを取り上げます。

（詳細、一覧はリリースノート、changelogを参照してください）

■ アーティファクトファイル名に含む日時のタイムゾーンを指定可能に

ansible-navigator は Playbook を実行すると、アーティファクトというログをJSON形式で出力できます。

これまではアーティファクトのファイル名の規則として、Playbookのディレクトリ、Playbook名、UTCの時刻を利用できました。

ansible-navigator.yml では以下のように {キー名} で、指定できます。

# ansible-navigator 1.x での設定例
---
ansible-navigator:
  playbook-artifact:
    save-as: "{playbook_dir}/{playbook_name}-artifact-{ts_utc}.json"

時刻は UTC しか指定できませんでしが、ansible-navigator 2.0.0 ではタイムゾーンを指定できるようになりました。

指定できるタイムゾーンの形式は IANA time zone とのことです。この形式の詳細はお恥ずかしながらわかっていませんでしたが、身近なところでは Japan や Asia/Tokyo が指定できました。デフォルトは UTC です。

コードを追っていくと、Python 3.9 以上では zoneinfo.ZoneInfo() の引数に渡っていました。

ほか、便利なのがlocal と指定すると、ansible-navigator 自体を実行しているOS側（コンテナの観点ではコンテナホスト）のタイムゾーンに合わせられます。実際はこの指定の仕方が一番多いのではないかと思います。

また、タイムゾーンの指定機能の導入にあわせて、時刻のキー名が ts_utc から time_stamp に変更されました。もし ts_utc のまま実行すると、書き換えるステップをはさみます（後述の設定ファイルの書式変更でも触れます）。

changelog より

タイムゾーン指定の件

Enabled the use of the time_zone settings entry for playbook artifact file name creation.

キー名変更の件

Renamed the ts_utc variable in the playbook artifact file name to time_stamp.

以下は、ansible-navigator.yml で、アーティファクトファイル名にタイムスタンプを含め、OS 側のタイムゾーンに合わせる設定例です。

---
ansible-navigator:
  playbook-artifact:
    enable: true    # デフォルト
    save-as: "{playbook_dir}/{playbook_name}-artifact-{time_stamp}.json"  # デフォルト
  time-zone: local  # OS設定に合わせる

OS側のタイムゾーンが Asia/Tokyo の場合、playbook-artifact-2022-04-19T20:58:29.302037+09:00.json のようなアーティファクトが生成されます。+09:00 になります。

なお、この機能は私が issue を書いてご対応いただきました。 @cidrblock Thank you!


■ images サブコマンドが stdout モードでも利用可能に

images サブコマンドは、実行環境内の OS、Ansible バージョン、コレクション、Python パッケージのの情報を表示できる機能です。機能自体は以前からありましたが、 interactive モードのみのサポートでした。今回、stdout モードにも対応しました。

changelogから

Added basic support for mode stdout for the images subcommand.

その場でちょっと確認するだけでしたら interactive モードが便利かもしれません。

一方、出力結果をファイルに保存したり、抽出、加工する場合は stdout モードが適していそうです。

コマンドで stdout モードを指定する場合は、--mode stdout を指定します。詳細情報を特に指定しない場合は、実行環境の概要情報が表示されます。

ansible-navigator.yml がない状態で実行したら、以下の3つの環境が表示されました。

$ ansible-navigator images --mode stdout
---
- created: 2 days ago
  execution_environment: true
  full_name: quay.io/ansible/ansible-runner:latest
  image_id: 84f0acda4cea
  inspect:
# ...(略)...
- created: 4 months ago
  execution_environment: true
  full_name: quay.io/ansible/ansible-runner:stable-2.12-devel
  image_id: 8eb88c5bd9fb
  inspect:
# ...(略)...
- created: 2 weeks ago
  execution_environment: true
  full_name: quay.io/ansible/creator-ee:v0.4.2
  image_id: 12571ac947cf
  inspect:
# ...(略)...

詳細情報の表示

-d または --details をプションを指定すると、更に詳細情報を表示できます。詳細情報は以下の種類種類をさらに指定できます。デフォルトは everything です。

  • ansible_collections
  • ansible_version
  • everything
  • os_release
  • python_packages
  • python_version
  • redhat_release
  • system_packages

例えば、ansible_version と ansible_collections に絞って表示したい場合は以下のように指定します。

$ ansible-navigator images -d ansible_version -d ansible_collections
---
ansible_collections:
  details:
    amazon.aws: 3.1.1
    ansible.posix: 1.3.0
    ansible.windows: 1.9.0
    awx.awx: 20.1.0
    azure.azcollection: 1.12.0
    community.docker: 2.3.0
    community.vmware: 2.2.0
    containers.podman: 1.9.3
    google.cloud: 1.0.2
    kubernetes.core: 2.3.0
    openstack.cloud: 1.7.2
    ovirt.ovirt: 1.6.6
    redhatinsights.insights: 1.0.7
    theforeman.foreman: 3.2.0
ansible_version:
  details: ansible [core 2.12.4.post0]
image_name: quay.io/ansible/creator-ee:v0.4.2

イメージを指定したい場合は、--eei オプションも指定します。

$ ansible-navigator images --eei イメージ名 -d ansible_version -d ansible_collections

他、collections サブコマンドも、stdout モードでも利用可能になりました。

参考: images サブコマンドのヘルプ

▼ ansible-navigator images -h の結果（クリックして開く）

$ ansible-navigator images -h
Usage: ansible-navigator images [options]

images: Explore execution environment images

Options (global):
 -h     --help                                   Show this help message and exit
 --version                                       Show the application version and
                                                 exit
 --rad  --ansible-runner-artifact-dir            The directory path to store
                                                 artifacts generated by ansible-
                                                 runner
 --rac  --ansible-runner-rotate-artifacts-count  Keep ansible-runner artifact
                                                 directories, for last n runs, if set
                                                 to 0 artifact directories won't be
                                                 deleted
 --rt   --ansible-runner-timeout                 The timeout value after which
                                                 ansible-runner will forcefully stop
                                                 the execution
 --cdcp --collection-doc-cache-path              The path to collection doc cache
                                                 (default:
                                                 /home/admin/.cache/ansible-
                                                 navigator/collection_doc_cache.db)
 --ce   --container-engine                       Specify the container engine
                                                 (auto=podman then docker)
                                                 (auto|podman|docker) (default: auto)
 --co   --container-options                      Extra parameters passed to the
                                                 container engine command
 --dc   --display-color                          Enable the use of color for mode
                                                 interactive and stdout (true|false)
                                                 (default: true)
 --ecmd --editor-command                         Specify the editor command (default:
                                                 vi +{line_number} {filename})
 --econ --editor-console                         Specify if the editor is console
                                                 based (true|false) (default: true)
 --ee   --execution-environment                  Enable or disable the use of an
                                                 execution environment (true|false)
                                                 (default: true)
 --eei  --execution-environment-image            Specify the name of the execution
                                                 environment image (default:
                                                 quay.io/ansible/creator-ee:v0.4.2)
 --eev  --execution-environment-volume-mounts    Specify volume to be bind mounted
                                                 within an execution environment
                                                 (--eev
                                                 /home/user/test:/home/user/test:Z)
 --la   --log-append                             Specify if log messages should be
                                                 appended to an existing log file,
                                                 otherwise a new log file will be
                                                 created per session (true|false)
                                                 (default: true)
 --lf   --log-file                               Specify the full path for the
                                                 ansible-navigator log file (default:
                                                 /home/admin/git/general/vagrant/nwla
                                                 b/ee/ansible-navigator.log)
 --ll   --log-level                              Specify the ansible-navigator log
                                                 level
                                                 (debug|info|warning|error|critical)
                                                 (default: warning)
 -m     --mode                                   Specify the user-interface mode
                                                 (stdout|interactive) (default:
                                                 interactive)
 --osc4 --osc4                                   Enable or disable terminal color
                                                 changing support with OSC 4
                                                 (true|false) (default: true)
 --penv --pass-environment-variable              Specify an existing environment
                                                 variable to be passed through to and
                                                 set within the execution environment
                                                 (--penv MY_VAR)
 --pa   --pull-arguments                         Specify any additional parameters
                                                 that should be added to the pull
                                                 command when pulling an execution
                                                 environment from a container
                                                 registry. e.g. --pa='--tls-
                                                 verify=false'
 --pp   --pull-policy                            Specify the image pull policy
                                                 always:Always pull the image,
                                                 missing:Pull if not locally
                                                 available, never:Never pull the
                                                 image, tag:if the image tag is
                                                 'latest', always pull the image,
                                                 otherwise pull if not locally
                                                 available (always|missing|never|tag)
                                                 (default: tag)
 --senv --set-environment-variable               Specify an environment variable and
                                                 a value to be set within the
                                                 execution environment (--senv
                                                 MY_VAR=42)
 --tz   --time-zone                              Specify the IANA time zone to use or
                                                 'local' to use the system time zone
                                                 (default: utc)

Options (images subcommand):
 -d     --details                                Provide detailed information about
                                                 the selected execution environment
                                                 image (ansible_collections|ansible_v
                                                 ersion|everything|os_release|python_
                                                 packages|python_version|redhat_relea
                                                 se|system_packages) (default:
                                                 ['everything'])


■ 設定ファイルの JSON Schema によるチェック

ansible-navigator run などの各処理の実行前に、ansible-navigator.yml などの設定ファイルの JSON Schema によるチェックが行われるようになりました。

changelogから

Added settings file validation against the settings file JSON Schema during application initialization.

これまでは、設定ファイルにスペルミスなどの不備があった場合は、無視して処理が続行されていました。事前にチェックが入ることにより、意図しない挙動を未然に防げそうです。

例えば、以下の ansible-navigator.yml では environment のスペルを間違えています。

---
ansible-navigator:
  execution-enviroment:     # environment がスペルミス
    enabled: true
    image: localhost/my-ee:latest

この状態で、書式チェックするために単に ansible-navigator とだけ実行すると、以下のようなエラーが表示されます。

$ ansible-navigator
Warning: Issues were found while applying the settings.
   Hint: Command provided: ''

  Error: The following errors were found in the settings file (/home/admin/git/general/vagrant/nwlab/ee/ansible-navigator.yml):
         In 'ansible-navigator': Additional properties are not allowed ('execution-enviroment' was unexpected).
   Hint: Check the settings file and compare it to the current version.
         The current version can be found here:
         (https://ansible-navigator.readthedocs.io/en/latest/settings/#ansible-navigator-settings)
         The schema used for validation can be seen with 'ansible-navigator settings --schema'
         A sample settings file can be created with 'ansible-navigator settings --sample'

   Note: Configuration failed, using default log file location. (/home/admin/git/general/vagrant/nwlab/ee/ansible-navigator.log) Log
         level set to debug
   Hint: Review the hints and log file to see what went wrong.

'execution-enviroment' was unexpected とあるので、すぐに気づけます。もし問題なければ、この場合は Welcome 画面が開きます。

一方、以前の バージョンの ansible-navigator では、書式エラーは無視され、デフォルトの設定で処理を続行しようとしてしまいます。

書式エラーで早い段階で止まってくれるのは安心です。

参考: VSCode による書式チェック

書式チェックの方法としては、VS Code に YAML という拡張を利用するというアプローチもあります。

そうすると、ansible-navigator.yml 以下のように、書式エラーが表示されます。

スペルミスを検出

また、この拡張によって各設定項目の入力候補も表示されるため、とても便利です。

便利な補完機能


■ 設定ファイルの書式変更

設定ファイル（ansible-navigator.yml）の一部の書式が変更されました。

旧書式を新書式の対応を示したサンプルは以下のとおりです。コメントアウトした旧書式Nと新書式Nが対応しています。

---
ansible-navigator:
  execution-environment:
    # 旧書式1
    # pull-policy: missing

    # 新書式1
    pull:
      policy: missing

  # 旧書式2
  # documentation:
  #   plugin:
  #     name: service
  #     type: module

  ansible:
    # 新書式2
    doc:
      plugin:
        name: service
        type: module

    # 旧書式3
    # playbook: hoge.yml
    # config: ansible.cfg
    # inventories: 
    #   - inventory.yml

    # 新書式3
    playbook:
      path: hoge.yml
    config:
      path: ansible.cfg
    inventory:
      entries:
        - inventory.yml

新書式のほうが、きれいに階層化された印象があります。

他にも、ヘルプ系の設定項目も書式変更があります。詳細は changelog を参照してください。

Moved the help entries into their respective ansible command parent keys in settings file.

新書式への移行機能

ansible-navigator 実行時に、以前のままの書式が検出された場合、新しい書式に移行（書き換え）するかどうか選択できます。

$ ansible-navigator 

The following version migrations are required:
  - Version 1 to Version 2 settings file format migration
Do you want to run them all? (Y/n): Y       # 書き換えする場合は Y

Version 1 to Version 2 settings file format migration:
Migration of 'config path'..................................Not needed
Migration of 'documentation'................................Updated     # 書き換わった
Migration of 'playbook path'................................Not needed
Migration of 'help builder'.................................Not needed
Migration of 'help config'..................................Not needed
Migration of 'help doc'.....................................Not needed
Migration of 'help inventory'...............................Not needed
Migration of 'help playbook'................................Not needed
Migration of 'inventory paths'..............................Not needed
Migration of 'playbook artifact timestamp'..................Not needed
Migration of 'pull-policy'..................................Not needed
Migration of 'volume mount labels'..........................Not needed
Backup: /home/admin/git/general/vagrant/nwlab/ee/ansible-navigator.v1
Updated: /home/admin/git/general/vagrant/nwlab/ee/ansible-navigator.yml

Migration complete

Press Enter to continue:    # 処理を続けるには Enter

書き換え前のファイルは ansible-navigator.v1 としてバックアップされますので、不要であれば削除します。


■ Python 3.8 以上が要件に

Python 3.6 と 3.7 がサポートから外され、Python 3.8 以上が要件になりました。

changelogから

Set the minimum supported python version for ansible-navigator to 3.8.

関連PR

github.com


■ 実行環境イメージpull時のオプションを指定可能に

ansible-navigator コマンドに、実行環境イメージpull時のオプションを指定できる --pa、--pull-arguments オプションが利用できるようになりました。

たとえば、--pa='--tls-verify=false' と指定することで、podman pull 時に証明書検証を無効にする指定もできるようです。

  • ansible-navigator -h から抜粋
 --pa   --pull-arguments                         Specify any additional parameters that should be added
                                                 to the pull command when pulling an execution
                                                 environment from a container registry. e.g. --pa='--
                                                 tls-verify=false'


■ デフォルトの実行イメージが変更

pip でインストールした ansible-navigator 1.1.0 では quay.io/ansible/ansible-navigator-demo-ee:0.6.0 でしたが quay.io/ansible/creator-ee:v0.4 に変更されました。

changelog より

Upgraded default execution environment image to creator-ee:v0.4.0


おわりに

前回に続いて、ansible-navigator 2.0.0 の機能で気になったポイントを取り上げました。

いろいろと機能が追加されて、これかの発展も楽しみなツールです。

参考

リリースノート

github.com

changelog

ansible-navigator.readthedocs.io