Ansibleユーザーのための VS Code拡張機能の紹介 2021/11/20 えんでぃ 資料のリンク、引用、スクリーンショット等はご自由にどうぞ

自己紹介 ハンドルネーム えんでぃ VS Code の使い方 Ansible Playbook、Python、ブログ (Markdown) 外部コミュニティ Ansibleユーザー会 2 https://ansible-users.connpass.com/ Connpassからイベント開催を通知します (ハンズオン、Ansible Night、座談会など) 特定技術領域に特化したイベントもあります (ネットワーク部、Developer部、VMware部) LinuxやNWのことを書きます (個人ブログ) https://endy-tech.hatenablog.jp/archive

コンテンツ ● Ansibleとは ● Ansible拡張機能 (基本編) ● Ansible拡張機能 (応用編) ● その他のおすすめ拡張機能 動作環境 Ansible拡張機能: v0.4.5 OS: Linux (Fedora Server 33) ansible-core: 2.11.5 ansible-lint: 5.1.3 yamllint: 1.26.3 3

Ansibleとは 1スライドで説明します 4

Ansible Server Ansible とは Ansible の基本動作 (Playbookを読み込んで命令実行) ● 複数の機器の設定変更・情報取得を一括で実行する自動化ツール ● NW機器、Windows、Linux、vSphere、その他Rest API に対応 ● Simple, Powerful, Agentless (簡単、高機能) ● 非プログラマーによる自動化推進の強い味方 Playbook (YAML形式で処理内容を記述したもの) - hosts: linux tasks: - yum: state: installed name: - bind - bind-utils Playbook (1) 読込み (2) SSH / HTTPS ↑ 今回は、Ansible Playbookを 　VS Code で便利に書く機能を紹介します 1 2 3 4 5 6 7 5

Ansible拡張機能 (基本編) 概要 セットアップ方法 機能紹介 6

2017 2018 2019 2020 2021 Ansible公式拡張機能の変遷 ● 色々な拡張機能があって迷う... ● 現時点ではredhat.ansibleが推奨 7 Ansible (vscoss.vscode-ansible, Microsoft製) 公開停止 (Unpublished) Ansible Language (zbr.vscode-ansible) YAML (redhat.vscode-yaml, Red Hat製) 依存関係 Ansible (tomaciazek.ansible) Ansible (redhat.ansible) 移行 マージ [1] 非推奨 (Deprecated) 第一 世代 第二 世代 第三 世代

Ansible (redhat.ansible) 機能名 機能詳細 Syntax Hightlighting ソースコードの色分け Validation 文法、コーディング規約の警告・エラー表示 Auto Completion キーワードやモジュール名の入力補完。FQCNにも対応 Documentation Reference キーワードやモジュールの説明表示 8 ● Ansible Language Server ● Ansibleに関連するYAML言語サポートの強化 (主にPlaybook) Ansible Language Server https://github.com/ansible/ansible-language-server

* 必須の依存パッケージをインストールしないと Validation機能が動作せず、エラーのポップアップが出る (Validation以外の機能は正しく動作する ) * VS Codeの設定で ansible.ansibleLint.enabled を false にセットすることで、 Validationを無効化し、ポップアップを抑止できる セットアップ手順 9 パッケージ名 必須 / 任意 説明 ansible-lint 必須 Ansible観点のコーディング規約の警告のため ansible-core 必須 Ansible 観点の文法チェックのため (ansible-playbook --syntax-check) * ansible-coreの代わりにansibleも可 yamllint 任意 YAML観点のコーディング規約の警告のため * ansible-lintの依存関係で自動インストールされる pip install --user \ ansible-core \ ansible-lint 1. 通常の手順でredhat.ansibleをインストールする 2. Validation 機能を動作させるため、以下の依存パッケージをインストールする

機能1. Syntax Highlighting ● YAMLよりもAnsibleに特化した色分け ● 色の違いでミスに気付ける YAML の場合 Ansible の場合 Playbookキーワード モジュール名 モジュールオプション ★非キーワード Jinja2 の括弧 10

機能2. Validation ● 3つの観点で、文法やコーディング規約のエラーを表示する # 内部実行コマンド 検知対象 検知タイミング (1) ansible-playbook --syntax-check Ansible 観点の文法エラー ファイル保存時 (Ctrl+S) (2) ansible-lint Ansible 観点のコーディング規約違反 リアルタイム (3) yamllint YAML 観点のコーディング規約違反 リアルタイム (2) (3) (1) ルール名 syntax-check -> (1) yaml -> (3) 上記以外 -> (2) 行,列番号 11

* ansible.ansible.useFullyQualifiedCollectionNames を False に変更すると、FQCNを使わずに補完する Falseの場合、ansible-coreに含まれるキーワードや collections keyword に指定されたものは省略形で、それ以外のものは FQCNで補完する 機能3. Auto Completion (Intellisense) ● キーワード補完 + 解説表示 (Ctrl+Space) ● モジュールオプションも補完可能 ● デフォルトでは、FQCNによって補完する (*) Ctrl + Space 12

機能4. Documentation Reference ● 説明文の表示 (キーワードにマウスカーソルを合わせる) 13 ● ソースコードにジャンプ (モジュール名を右クリックして Go to Definition) Go to Definition ソースコードの表示

Ansible拡張機能 (応用編) Ansible 拡張機能を使えない問題の回避 YAML拡張機能との競合回避 Ctrl+F5 によるAnsible実行 Ctrl+Shift+I によるAuto Formatter実行 14

Tip 1. Ansible 拡張機能を使えない問題の回避 ● Ansible拡張機能は、VS Code上でフォルダを開いて使用すること (File > Open Folder) ● 上記で開いたフォルダ以外で YAMLファイルを開いた場合、 Ansible 拡張機能が使えなくなる (Language Server が起動しないため ) ● ファイルを保存せずに開いたり、 Ctrl+Oで別フォルダのファイルを開くと本事象にヒットするので注意 15 ↑ VS Code で開いているフォルダ配下に playbook.ymlがあるため、入力補完が正しく動作する ↑ VS Code でフォルダを開いていない場合、 入力補完に失敗する

Tip 2. Playbook以外にもAnsible拡張機能を使う ● デフォルトではplaybooks/*.yml, .ansible.yml, site.yml, *playbook*.yml (.yamlも含む) のみがAnsible言語として認識され、 他のパターンはYAML言語として認識されてしまう [1] ● 以下の設定を入れることでその他の Ansible関連ファイルもAnsible言語として認識させ、 Ansible拡張機能を使えるようにする 16 "files.associations ": { "**/tasks/*.yaml ": "ansible", "**/tasks/*.yml ": "ansible", "**/handlers/*.yaml ": "ansible", "**/handlers/*.yml ": "ansible", "**/host_vars/*.yml ": "ansible", "**/group_vars/*.yml ": "ansible", "**/defaults/*.yaml ": "ansible", "**/defaults/*.yml ": "ansible", "**/vars/*.yaml ": "ansible", "**/vars/*.yml ": "ansible", "**/meta/*.yaml ": "ansible", "**/meta/*.yml ": "ansible", "hosts": "ini" }, ↑File Associations の設定変更 上述の設定をVS Codeの設定 (Ctrl + ,) に追記する。 Ansibleならではの補完機能が効くのは Playbook, Tasks, Handlersだが、変数ファイルも Ansibleとして認識させたほうが編集しやすいのでおすすめ (例) xxxという文字列を選択して {{ と入力してスペースキーを押すと、{{ xxx }} という形式になってくれる [1] GitHub - ansible/vscode-ansible - README.md 2024/2/26 更新

Tip 3. Ctrl+F5 によるAnsible実行 ● 基本的には、Ctrl+F5による保存&実行や F5によるデバッグは不可 (2021/10現在、Ansible拡張機能にデバッグ機能がないため ) ● Commands (usernamehw.commands) という拡張機能を使えば、 Ctrl+F5 による保存 & 実行が可能となる ● 一部制限あり。次スライド参照 17 手順1. Commands 拡張機能のインストール (usernamehw.commands) 通常の手順でインストールする。 単一のショートカットキーに対して複数のアクションを割り当てることができるようになる (他にも機能多数)。 手順2. VS Code のsettings.json に以下を追記 (Ctrl+Shift+P → workbench.action.openSettingsJson) 以下の2コマンドを順に実行する、新たなコマンドを生成 (saveAndExecuteAnsiblePlaybook)。 　・ファイル保存 (workbench.action.files.save) 　・ansible-playbook実行 (extension.ansible-playbook.run) "commands.commands": { "saveAndExecuteAnsiblePlaybook": { "sequence": [ "workbench.action.files.save", "extension.ansible-playbook.run", ] } },

Tip 3. Ctrl+F5 によるAnsible実行 18 手順3. keybindings.json の編集 (Ctrl+Shift+P → workbench.action.openGlobalKeybindingsFile) 手順2で作成したコマンドにショートカットキーを割り当てる。 言語がAnsibleである場合のみショートカットキーが有効となる 設定を入れるため、 GUIではなくjsonを直接編集している { "key": "ctrl+f5", "command": "saveAndExecuteAnsiblePlaybook", "when": "editorLangId == ansible" }, 手順4. Ansible設定ファイルの編集 (任意) ショートカットキーで実行する際、 -i によってインベントリファイルを指定できない。 デフォルトの/etc/ansible/hosts以外のパスを利用する場合は、 ansible.cfgで指定しておく[1]。 # ~/.ansible.cfg (in the home directory) [defaults] inventory = $PWD/hosts [1] ansible.cfgのパス, https://docs.ansible.com/ansible/latest/reference_appendices/general_precedence.html#configuration-settings

Tip 3. Ctrl+F5 によるAnsible実行 19 手順5. 使う Playbookのエディタにカーソルがあっている状態で Ctrl+F5を押せば、ansible-playbookが実行される 制限事項 ● ショートカットキーを使えるのは、エディタにマウスカーソルがあっている時のみ * 手順3のeditorLangIdの制約 [1] ● ansible-playbook コマンドにオプションを渡すことはできない * extension.ansible-playbook.run の制約 [1] When clause contexts, https://code.visualstudio.com/api/references/when-clause-contexts#available-contexts

Tip 3. Ctrl+F5 によるAnsible実行 20 ■(補足) コマンドラインオプションを渡す方法 Ansible拡張機能の命令を使わなくなる関係で、 Ctrl+F5から実行した時に拡張機能のオプションが無視されるので、推奨はしない 。 例えば、ansible-playbook実行ファイルパスの設定 (ansible.ansiblePlaybook.path) が効かなくなる。 手順2のsettings.jsonの記載内容を以下のように変更する。 以下は、--check オプションをデフォルトで有効にする例。 “args” 配下で${file} を変数展開できるように、 commands.variableSubstitutionEnabled をTrueにセットしている[1]。 --tags, --diff などのデフォルト値を指定したい場合は、 ansible.cfg による設定を先に検討するのが推奨 "commands.commands": { "saveAndExecuteAnsiblePlaybook": { "sequence": [ "workbench.action.files.save", { "command": "commands.runInTerminal", "args": "ansible-playbook ${file} --check" } ] } } "commands.variableSubstitutionEnabled": true, [1] Predefined variables, https://code.visualstudio.com/docs/editor/variables-reference Skip

Tip 4. Ctrl+Shift+I によるAuto Formatter実行 21 ● 2021/10 現在、Ansible拡張機能にはAuto Formatter 機能がない (*) ● しかし、工夫すればYAML拡張機能のAuto Formatter を呼び出すことはできる * Auto Formatter は、Ctrl+Shift+I で空行やインデントなどの体裁を自動で整えてくれる機能 * yamllint のエラーをある程度自動修正してくれるスグレモノ 手順1. Commands 拡張機能のインストール (usernamehw.commands) 通常の手順でインストールする。 単一のショートカットキーに対して複数のアクションを割り当てることができるようになる。 アクションに引数を付けて実行できる。 (他にも機能多数) 手順2. YAML拡張機能のインストール (redhat.vscode-yaml) 通常の手順でインストールする

Tip 4. Ctrl+Shift+I によるAuto Formatter実行 手順3. VS Code のsettings.json に以下を追記 (Ctrl+Shift+P → workbench.action.openSettingsJson) 以下の3コマンドを順に実行する、新たなコマンドを生成 (formatAnsible)。 　・エディタ言語をYAMLに変更 (commands.setEditorLanguage) 　・Auto Format の実行 (extension.ansible-playbook.run) 　・エディタ言語をAnsibleに戻す (commands.setEditorLanguage) 22 "commands.commands ": { "formatAnsible ": { "sequence ": [ { "command": "commands.setEditorLanguage ", "args": "yaml" }, { "command": "editor.action.formatDocument " }, { "command": "commands.setEditorLanguage ", "args": "ansible" } ] }, # "saveAndExecuteAnsiblePlaybook": { 　# Tip3 の設定 },

Ctrl+Shift+I Tip 4. Ctrl+Shift+I によるAuto Formatter実行 手順4. keybindings.json の編集 (Ctrl+Shift+P → workbench.action.openGlobalKeybindingsFile) 手順3で作成したコマンドにショートカットキーを割り当てる。 言語がAnsibleである場合のみショートカットキーが有効となる 設定を入れるため、 GUIではなくjsonを直接編集している 23 { "key": "ctrl+shift+i", "command": "formatAnsible", "when": "editorLangId == ansible" }, 手順5. 使う (Shift+Ctrl+I) 先頭の無駄な空行が削除する例

Tip 4. Ctrl+Shift+I によるAuto Formatter実行 24 制限事項 ● ショートカットキーを使えるのは、エディタにマウスカーソルがあっている時のみ * 手順3のeditorLangIdの制約 [1] Tip 3と同じ [1] When clause contexts, https://code.visualstudio.com/api/references/when-clause-contexts#available-contexts

その他のおすすめ機能 その他オススメの拡張機能 25

Editor: Render Whitespace (editor.renderWhitespace) 26 ● 標準機能 ● 設定 (Ctrl+,) → editor.renderWhitespace → all ● スペースやタブ文字を可視化する ↑デフォルト (selection) ↑設定変更後 (all) 3行目にタブx4、4行目に半角スペースx1

SSHで遠隔操作 Remote - SSH (ms-vscode-remote.remote-ssh) ● 拡張機能 ● Windows/Mac のVS CodeからLinuxを遠隔操作する ● Windows / Mac の使い勝手と、Linux 開発環境を両立できる ● Ansible はWindows上では動作しないので、Windowsユーザーにはほぼ必須の機能 27 Windows / Mac Linux * Remote Development using SSH https://code.visualstudio.com/docs/remote/ssh

Indent Rainbow (oderwat.indent-rainbow) ● 拡張機能 ● インデントの違いを色で強調する 28 * Indent Rainbow https://marketplace.visualstudio.com/items?itemName=oderwat.indent-rainbow ↑拡張機能なし ↑拡張機能あり

Highlight Bad Chars (wengerk.highlight-bad-chars) ● 拡張機能 ● 良くない文字を強調表示する 29 * Highlight Bad Chars https://marketplace.visualstudio.com/items?itemName=wengerk.highlight-bad-chars ↑拡張機能なし ↑拡張機能あり (全角スペース) ↑拡張機能あり (ゼロ幅スペース) ↑拡張機能なし

Highlight Bad Chars (wengerk.highlight-bad-chars) ● カスタマイズ例 30 * NG文字のデフォルト値 , https://github.com/WengerK/vscode-highlight-bad-chars/blob/master/src/bad-characters.ts * スタイルのデフォルト値 , https://github.com/WengerK/vscode-highlight-bad-chars/blob/master/package.json#L40 * スタイルに利用可能なパラメータ , https://code.visualstudio.com/api/references/vscode-api#DecorationRenderOptions // タブ文字もNGに加える "highlight-bad-chars.additionalUnicodeChars": [ "\u0009" ] // スタイルのカスタマイズ "highlight-bad-chars.badCharDecorationStyle": { "backgroundColor": "rgba(255,255,255,0.3)", "borderColor": "rgba(255,255,255,0.4)", "borderRadius": "4px" },

Better Jinja (samuelcolvin.jinjahtml) ● JinjaのSyntax Highlightingを提供してくれる ● html.j2やyaml.j2など、j2の手前の拡張子を認識してhtmlやyamlなどの色分けもしてくれるので大変見やすい ● 下図で言語別の見た目を比較する 31 HTMLの場合 Ansibleの場合 ansible-jinjaの場合 Jinja HTMLの場合 VS Codeのデフォルト ・HTMLタグ : 色分けする ・Jinja Expression: 色分けしない Ansible拡張機能 ・HTMLタグ : 色分けしない ・Jinja Expression: 色分けする Better Jinja拡張機能 ・HTMLタグ : 色分けする ・Jinja Expression: 色分けする 2024/2/26 追記

ENDy 32