手順書作成の未来（の 1 つの形）を Visual Studio Code の Extension にみたという話

#Azure CLI

#Microsoft Visual Studio

にしざわ

2024.01.10

はじめに

システム運用においては、なんらかのリソースを作成や削除したり、設定値を変更したりとさまざまな変更作業が発生します。その際、なんらかの手順書（Markdown や Excel 等）を準備して、作業をすることが一般的だと思います。

本記事では「変更手順の作成」と「その手順を実施する」という 2 点にフォーカスして、これらを支援する Visual Studio Code（以下、VS Code）の Extention をご紹介します。
なお、本 Extention は Azure でのみ使用可能な点にご注意ください。

補足: 手順書がどうあるべきかについては多くの意見があるため、この記事では触れません。
この辺りについては、運用設計ラボ様の素晴らしいスライドがあるので、末尾の参考資料にリンクしておきます。

Azure CLI Tools について

今回ご紹介するのは、Azure CLI Tools です。
こちらは Microsoft が提供する VS Code 用の Extention で、主に以下の機能が実装されています。
（リンク先の GIF をご覧いただけますと、イメージが掴めます）

特定のファイル形式（.azcli）において、Azure CLI コマンドとそのオプションを補完する
必須のオプションを自動挿入する
Azure CLI コマンドを統合ターミナルにて直接実行する
コマンドへのマウスホバーでドキュメントを表示する

なにがイケているのか

結論からお伝えすると、まるでプログラミングをしている時のような感覚で Azure CLI コマンドの入力を補完させながら、手順書を作成できます。
たとえば、以下のような点がこれまでの手法とくらべ、革新的だと考えます。

手順書作成時にコマンドとオプションの補完が効くことで、コマンドの記述ミスが減る
手順書から直接ドキュメントが読めるため、公式ドキュメントと行ったり来たりする機会が減る
手順書からコマンドを実行できるため、コピペや貼り付け時のミスが減る。また、統合ターミナルから結果を確認できる
ファイルはプレーンテキストのため、Git や Subversion でバージョン管理できる

どんな点に注意が必要か

手順書からコマンドを実行できる簡易さは、一方で意図しない操作をうむ危険性がある
手順の進捗状況は、操作者にて管理する必要がある

手順書の作成

以下クイックスタートを元に手順書を作成し、実際の変更作業をしてみます。

クイックスタート:Azure CLI で Windows 仮想マシンを作成する

前提

使用するホストマシンに Azure CLI がインストールされていること
VS Code がインストールされていること
VS Code に Azure CLI Tools がインストールされていること

準備

手順書となるファイル（.azcli）を作成します。
なお、ファイル名は任意で構いません。今回は blog.azcli とします。

手順書の作成

クイックスタートの内容をベースに、実行するコマンドを手順書へ記載します。
なお、オプションまで補完させる場合は、「動詞」->「リソース種別」の順で入力する必要があります。たとえば「az group create」と記載する場合、「creategroup」と入力し、補完候補から選択するとオプションまで補完されます。

実作業

その 1：Azure にサインインする

まずは、Azure へサインインします。
手順冒頭で az login を追記し、コマンド文を選択しながら右クリックします。「Run Line in Editor」か「Run Line in Terminal」からコマンドを実行します。ブラウザが起動するので、サインインを完了します。 ※雰囲気をお伝えするために、テキストスニペットではなく、スクリーンショットでご説明します。

その 2：手順を実行する

最初にリソースグループを作成し、次いで仮想マシンの作成、と進めていきます。
なお、直近のバージョン（0.5.0）から、バックスラッシュ（\）による複数行のコマンド実行にも対応しています。実行の際は「Run Line in Editor」ではなく「Run Line in Terminal」を選択ください。

まとめて処理を実行することも可能です。この場合、シェルスクリプトと同様に、上から処理が実行されます。クイックスタートの記載にある通り、仮想マシンの作成は、一部対話形式（パスワードの入力）となります。コマンドを実行したつもりになっているだけでなにも進んでいないということを避けるため、単一行・複数行に関係なくコマンドを実行した際は、統合ターミナルを確認するようにしてください。
（なんらかのコマンドを実行した際は、Azure portal からも結果を確認しましょう）

その 3：実行結果の確認とリソースのクリーンアップ

HTTP ポートの解放まで完了したら、Web サイトの動作確認を行います。
Web サイトが正常に確認できれば、作成したリソースを削除してください。
（本記事の内容とは関係ないため、詳細は割愛します）

まとめ

「変更手順を作成する」と「変更手順を実行する」という 2 点において、Azure CLI Tools は革新的なツールではないでしょうか。
一方で、複雑な手順書の代替えは、まだまだ機能不足感があります。たとえば、Markdown のようにプレビューできないため、進捗管理用にチェックボックスをつけたりはできません（コメントで無理やり記載することは可能）。この辺りも何らかの方法で充実してくるといいですね。
わたしは、検証環境での簡単な作業であれば、本ツールを使用して手順書作成・変更作業は十分かと思いました。

参考資料

アノテーション株式会社について

アノテーション株式会社は、クラスメソッド社のグループ企業として「オペレーション・エクセレンス」を担える企業を目指してチャレンジを続けています。「らしく働く、らしく生きる」のスローガンを掲げ、さまざまな背景をもつ多様なメンバーが自由度の高い働き方を通してお客様へサービスを提供し続けてきました。現在当社では一緒に会社を盛り上げていただけるメンバーを募集中です。少しでもご興味あれば、アノテーション株式会社 WEB サイトをご覧ください。