tl;dr

ギョームにて AWS リソース一覧を Backlog Wiki や Excel にまとめる度になんて不毛な作業をやっているんだろうと自問自答を繰り返しておりました.

そう, EC2 を追加したり削除する度にそれらの Wiki や Excel 表は誰がいったい更新するんだ, きっとそのうち誰もこの Wiki や Excel 表はメンテナンスされなくなるんだろう, そして, なにかトラブルが起きた時には情報が古いままになっているとか…せめてコマンド一発でこれらの Wiki や Excel 表が更新できたらどんなに嬉しいものかと…思いは強くなっていきました.

ということで, JAWS-UG もくもく会を利用して, この不毛な状態から脱すべく俺得ツールをざくっと作ってみました.

作ったもの

furikake

inokappa/furikake
It is a command line tool to register your resources in Wiki page (Markdown format). - inokappa/furikake
GitHub

github.com

名前は「ふりかけ」です. 特に意味は無いつもりでしたが, 実装している間に思いついたのが, 白いごはんに彩りを添える「ふりかけ」のように, 真っ白な Wiki や Excel シートに各種情報という彩りを添えるという意味をこじつけてみました.

とりあえず,「ふりかけ」には以下のような機能を実装しました.

  • 指定した AWS アカウントの指定したリソース一覧を取得して Backlog Wiki に投稿する
  • 一覧を取得したい AWS リソースは出来るだけ簡単なコードで追加出来ること (とりあえず, 自分が確認したかったリソースは追加した, AWS リソース以外にも対応可能だと思う)
  • 投稿先は出来るだけ簡単なコードで追加出来ること (とりあえず, 現状は Backlog Wiki だけ)
  • シンプルなコマンドラインツール

ひとまず, 自分がやりたいことは実現出来たので, 今後は色々と便利そうな機能を追加していきたいと考えています.

使い方

インストールは git clone でしばらくはお願い致します.

$ git clone git@github.com:inokappa/furikake.git
$ bundle install --path vendor/bundle

リソース一覧を貼り付けたい Backlog Wiki を作成します. この時に Wiki 名は適当で構いません. また, Wiki の本文は適当な文字を入れて下さい. (コンテンツが無いと Wiki は作成できないようです) 作成した Wiki の ID を控えておきます.

Wiki を作成したら, 以下のような .furikake.yml を作成します. (.furikake.yml の名前は固定しています)

backlog:
  projects:
    - space_id: 'your-backlog-space-id'
      api_key: 'your-backlog-api-key'
      top_level_domain: 'your-backlog-top-level-domain'
      wiki_id: your-wiki-id
      wiki_name: 'your-wiki-name'
      header: >
        # Test Header
      footer: >
        # Test Footer

header と footer はリソース一覧の上下に挿入されるコンテンツとなります. 上記の例では　# Test Header と # Test Footer がリソース一覧の前後に挿入されますので, 実際の出力は以下のような内容にとなります.

# Test Header

# リソース一覧

## EC2

...

## ELB

# Test Footer

尚, Backlog Wiki への投稿については, 以下のライブラリを利用していますので, パラメータ名等はこのライブラリに依存します.

emsk/backlog_kit
Client library for the Nulab's Backlog API version 2 written in Ruby. - emsk/backlog_kit
GitHub

github.com

.furikake.yml を作成したら, 以下のコマンドを実行して投稿される予定のリソース一覧を確認してみます.

$ bundle exec furikake show

以下のように出力されます.

$ bundle exec furikake show
# インフラ構成 (自動更新テスト用)
## 全体構成
ここに構成図なんかはっちゃったりして
## リソース一覧

### EC2

Name|Instance ID|Instance Type|Availability Zone|Private IP Address|Public IP Address|State
:-|:-|:-|:-|:-|:-|:-
...

## 詳細情報
### リポジトリ
* ソースコードの URL とか張ったりして

特に問題無いようであれば, 以下のコマンドを実行して Backlog Wiki にリソース一覧を投稿します.

$ bundle exec furikake publish

今のところ, 失敗する以外は, 特にメッセージが出ません. 冒頭で作成した Backlog Wiki を見ると, 以下のようにいい感じでリソースの一覧 (図では EC2 だけですが…) を確認することが出来ます.

いい感じです.

ちっぷす

Tips というか, 「ふりかけ」は利用者のニーズによって, 出来るだけ拡張し易く作ったつもりです (まだ, たくさんの改善の余地はありますが…). 例えば, リソース一覧に含めたい AWS リソースがある場合, ソースコードのlib/furikake/resources/ 以下に簡単なコードを置くことでリソースの種類を追加することが出来ます. 以下, README にも記載していますが, ELB (Classic Load Balancer) のリソース一覧を取得するコードです.

module Furikake
  module Resources
    module Clb
      def report
        resources = get_resources
        headers = ['LB Name', 'DNS Name', 'Instances']
        if resources.empty?
          info = 'N/A'
        else
          info = MarkdownTables.make_table(headers, resources, is_rows: true, align: 'l')
        end
        documents = <<"EOS"
### ELB (CLB)

#{info}
EOS

        documents
      end

      def get_resources
        elb = Aws::ElasticLoadBalancing::Client.new
        elbs = []
        elb.describe_load_balancers.load_balancer_descriptions.each do |lb|
          elb = []
          elb << lb.load_balancer_name
          elb << lb.dns_name
          elb << (lb.instances.map(&:to_h).map {|a| a[:instance_id] }).join(',')
          elbs << elb
        end
        elbs
      end

      module_function :report, :get_resources
    end
  end
end

report というメソッド名を遵守して頂いて, 且つ, 以下のようなフォーマットのデータを返すように実装するといい感じになります.

[['ID', 'Name', 'Status'], ['ID', 'Name', 'Status'], ['ID', 'Name', 'Status']]

ただし, 現在はソースコードを追加した後で, lib/furikake/resource.rb の types にリソース名を追加する必要があります…ごめんなさい.

module Furikake
  class Resource
    def initialize
    end
    
    def generate
      types = %w(
        ec2 alb clb lambda elasticsearch_service
        kinesis rds directory_service
      )

      documents = ""
      types.each do |type|
        require "furikake/resources/#{type}"
        eval "documents.concat(Furikake::Resources::#{type.camelize}.report)"
        documents.concat("\n")
      end
      documents
    end
  end
end

以上

まだまだ

「ふりかけ」には改善の余地がたくさんあります. 例えば, Backlog Wiki 以外の Github Wiki や Gist 等に投稿出来るようにしたいなと考えています. また, Excel 表も考慮して CSV 出力も出来ればなあと考えています. また, 機能以外にもエラー処理が残念ながら不十分ですので, 今後, ぼちぼち整備していこうかな〜と思っています.

awspec

「ふりかけ」の実装にあたり, awspec の実装をめちゃくちゃ参考にしてみました. めちゃくちゃ参考にした割には…残念な感じになっているかもしれませんが, awspec は AWS リソースを取得して色々する処理を書く時にとても参考になると思います. そして, awspec 同様にリソースの種類の追加は比較的容易に行えるようになっているはずですので, awspec のような成長を遂げてくれるとやばい感じになると思います.

ということで,「awspec だ〜いすき♡」(ハズキルーペ CM 風)

ということで

興味を持って頂けた方, ぜひ, 触って頂いてフィードバックを頂けると嬉しいでござります.

元記事はこちら

「AWS リソースを Backlog Wiki によしなにドキュメント化 (一覧化) するツール, その名も furikake を作った」