はじめに

オンプレミスのサーバやネットワーク機器を運用している場合、設定しているパラメータをまとめたパラメータシートを作成して管理する方法がよく行われているかと思います。

クラウド環境の場合、ダッシュボードを見れば設定値等わかるため、以前よりは使われる機会が減っているかもしれませんが、例えばAWSの場合、サービスも多く、横断的に確認するには手間だったりします。

AWS等のクラウドサービスでは、コマンドでJsonなどの形式で設定値を確認したりすることができ、jqを使えば整形することもできるので、書式もわかりやすく見栄えがいいMarkdown形式のドキュメントを生成するツールを作成して、以下のGitHubリポジトリで公開しましたので簡単に紹介したいと思います。

create-document

注意点

個人の制作物となり、ツールを使用して問題が生じた場合でも自己責任となりますので、その点理解したうえでご使用頂ければと思います。

AWSリソースのパラメータ取得ツールについて

詳しくはGitHubリポジトリのREADMEを参照してもらえればと思いますが、ツールの本体となる「create_document_shell」内のcreate_document.shを実行することでMarkdown形式のパラメータ一覧を作成することができます。

一覧の作成にはAWS環境へアクセスするためのアカウント設定やjqコマンドのインストールが必要となるので、事前に準備しておいてください。

以下のようにcreate_document.shシェルの引数としてresourceディレクトリ配下に格納されているファイル名を指定することで、指定したリソースの情報を取得し、docsディレクトリ配下に[リソース名]_list.mdというファイルが生成されます。

create_document.shの実行

./create_document.sh IAM

生成されたドキュメントは以下のようなMarkdown形式で出力されます。

IAMのパラメータ一覧の例

# IAM
## IAM Policy（カスタマー管理ポリシー） (ap-northeast-1)

|ポリシー名|アタッチ済みの許可ポリシー数|アタッチ済みの境界ポリシー数|ARN|ポリシーID|
|:--|:--|:--|:--|:--|
|IAMSelfManagement-20240318054455207000000001|0|0|arn:aws:iam::211125643235:policy/IAMSelfManagement-20240318054455207000000001|ANPATCKARU7R3GPQK2KFI|
|IAMSelfManagement-20240318054455209900000002|0|0|arn:aws:iam::211125643235:policy/IAMSelfManagement-20240318054455209900000002|ANPATCKARU7RW6AGIDCCQ|
|IAMSelfManagement-20240318054455212000000003|0|0|arn:aws:iam::211125643235:policy/IAMSelfManagement-20240318054455212000000003|ANPATCKARU7RQZODQ6J6U|
|example_from_data_source|0|0|arn:aws:iam::211125643235:policy/example_from_data_source|ANPATCKARU7R74F5DZUAL|

## IAM Role (ap-northeast-1)

|ロール名|Description|ARN|ロールID|
|:--|:--|:--|:--|
|AWS-QuickSetup-DHMCRole-tgvp3-ap-northeast-1|Do Not Modify or Delete. This resource has been created to support the deployment of DHMC Quick Setup configuration, and modification or deletion of this resource may hinder the functionality of that Quick Setup configuration.|arn:aws:iam::211125643235:role/AWS-QuickSetup-DHMCRole-tgvp3-ap-northeast-1|AROATCKARU7RT3DINN7XY|
|AWS-QuickSetup-DHMCRole-tgvp3-ap-northeast-2|Do Not Modify or Delete. This resource has been created to support the deployment of DHMC Quick Setup configuration, and modification or deletion of this resource may hinder the functionality of that Quick Setup configuration.|arn:aws:iam::211125643235:role/AWS-QuickSetup-DHMCRole-tgvp3-ap-northeast-2|AROATCKARU7RXIMGQLW5U|
|AWS-QuickSetup-DHMCRole-tgvp3-ap-south-1|Do Not Modify or Delete. This resource has been created to support the deployment of DHMC Quick Setup configuration, and modification or deletion of this resource may hinder the functionality of that Quick Setup configuration.|arn:aws:iam::211125643235:role/AWS-QuickSetup-DHMCRole-tgvp3-ap-south-1|AROATCKARU7RS5VOEMFZF|
|AWS-QuickSetup-DHMCRole-tgvp3-ap-southeast-1|Do Not Modify or Delete. This resource has been created to support the deployment of DHMC Quick Setup configuration, and modification or deletion of this resource may hinder the functionality of that Quick Setup configuration.|

以下、VS CodeでMarkdown Previewした場合の例。

GitHub ActionsとGitHub Pagesを使用したドキュメント生成ツール

「create_document_github」はワークフローファイルに書いた内容を定期実行したり、pushを契機に実行したりできるGitHub Actionsと、リポジトリの特定ディレクトリを静的ページとして公開することができるGitHub Pagesを使って、定期的にドキュメントを生成してパラメータ一覧のページを公開するツールとなります。

複数アカウントのパラメータをまとめて見ることができる作りにしているため、複数アカウント管理している場合に効果を発揮します。

注意点として、GitHub PagesはPrivateリポジトリでは公開できず、一般アカウントではPublicリポジトリにする必要があります。

Publicリポジトリは、誰でもアクセスできる状態で全体に公開されてしまうため、使用する場合は、GitHub Organizationが設定できるプランでOrganization、Team設定を行い、特定ユーザのみアクセスできるInternalリポジトリにしたうえで公開するようにしてください。

生成したドキュメントの例

複数システム、複数環境のパラメータ一覧ページを生成した場合、以下のような表示になります。

トップページ

環境一覧画面

パラメータ一覧画面

AWSのサービスのみ使用したドキュメント生成ツール

「create_document_codebuild」はGitHubを使用できない環境の場合でも「GitHub ActionsとGitHub Pagesを使用したドキュメント生成ツール」と同じように、定期的にドキュメントを生成してパラメータ一覧のページを公開するツールとなります。

ページの公開はS3の静的Webサイトホスティング機能で公開しているため、プロトコルはHTTPとなり、IPアドレス等のアクセス制限を行わないと全体に公開されてしまうため、使用する場合は十分に注意してください。

そのため実運用する場合はAWS WAF、CloudFrontを挟んで、WAFでアクセス制限を行ったり、S3バケットポリシーでアクセス元IPアドレスを制限したりしてください。

なお、公開用のHTML生成には、GitHub Pagesでドキュメント生成する際に使用しているものと同じJekyllを使用しているため、ページの見え方はGitHub Pagesで見た場合と同じです。

おわりに

一般的なサービスはパラメータ取得できるようにしていますが、まだまだ足りないサービス等も多いツールとなります。

create_document_shell配下のresourceに格納されているファイルを見てもらえれば分かる通り、基本的にはAWS CLIでパラメータを取ってきて、jqコマンドで整形しているだけなので、もし足りないサービスがあれば、自分で作ってみるのも良いと思います。

AWSの各種パラメータを取得するツールを作りました。