PixelaのTerraform Providerを作った。

TL;DR

• PixelaはGitHubのContributions風のグラフを生成するWebサービス
  • https://pixe.la
• PixelaのTerraform Providerを作った
  • https://github.com/budougumi0617/terraform-provider-pixela
• 使い方の紹介
• 実装の際にハマったところ
• 次はSDKも自作したい
• 他にもAPIがあったらTerraform Provider書こうかな

terraform {
  required_providers {
    pixela = {
      versions = ["0.0.5"]
      source   = "github.com/budougumi0617/pixela"
    }
  }
}

provider pixela {
  // Pixelaに登録したユーザー名
  username = "budougumi0617"
}

resource "pixela_graph" "sample" {
  graph_id              = "sample"
  name                  = "update from terraform"
  unit                  = "page"
  type                  = "int"
  color                 = "ajisai"
  timezone              = "Asia/Tokyo"
  self_sufficient       = "none"
  is_secret             = true
  publish_optional_data = false
}

Pixelaとは

Pixelaは@a-knowさんが作っているGitHubのContributions風のグラフを生成するWebサービスだ。

APIを手順通りに叩けば、任意のデータを記録できるグラフを生成できる。

（これは休止している私の英語学習記録グラフ…）

また、PixelaはREST風のAPIを使って操作するのが基本で、APIドキュメントも公開されている。

Terraform Providerとは

Terraformは宣言的にリソースを管理するためのツールだが、TerraformはProviderと呼ばれるプラグイン経由で各リソースを操作している。

たとえば、AWSだったらTerraformはAWS Providerを使ってAWS上のリソースを操作している。 TerrformはSDKが公開されているので、自分で好きなProviderを実装し、Terraform registoryに公開することができる。

Terraform Provider Pixela

リソースがあって、CRUDのAPIが用意されていればTerraform Providerをつくることができる。 こうして今回つくったのがPixela Providerだ。

Registryにも公開済みだ。

• https://registry.terraform.io/providers/budougumi0617/pixela

#pixela を宣言的に管理するぞ！ということで初めてTerraform Providerを作ってみた！
v0.0.4ではグラフをTerraformで定義できます！https://t.co/LdD99leEjO

— Yoichiro Shimizu (@budougumi0617) November 24, 2020

使い方

使いかたはTerraformを使ったことがあれば簡単で次のような宣言でグラフを生成できる。 なお、terraform applyするとき、PIXELA_TOKEN環境変数にトークンが設定されている必要がある。

terraform {
  required_providers {
    pixela = {
      versions = ["0.0.5"]
      source   = "github.com/budougumi0617/pixela"
    }
  }
}

provider pixela {
  // Pixelaに登録したユーザー名
  username = "budougumi0617"
}

resource "pixela_graph" "sample" {
  graph_id              = "sample"
  name                  = "update from terraform"
  unit                  = "page"
  type                  = "int"
  color                 = "ajisai"
  timezone              = "Asia/Tokyo"
  self_sufficient       = "none"
  is_secret             = true
  publish_optional_data = false
}

技術的な話

Terraform Providerは実装からテスト、リリースまでドキュメントを読みながら実装すれば簡単に作ることができる。
参考ドキュメントと少しハマったところを紹介しておく。

Terraform Providerの作り方

Providerの作り方は公式ガイドを参考にしながら作ることができる。

• Call APIs with Terraform Providers
  • https://learn.hashicorp.com/collections/terraform/providers

また、次の雑誌でも日本語でProviderの作り方が公開されている。

リリースの仕方

Terraform Providerを作ったらレジストリにも登録することができる。 こちらも手順通りにやればよい。

• https://www.terraform.io/docs/registry/providers/publishing.html

テストの書き方

Terrformは受け入れテスト（実際にリソースを作って確認するテスト）もSDKで簡単に作ることができる。
次のドキュメントを読みながら実装することができた。

• Acceptance Tests
  • https://www.terraform.io/docs/extend/testing/acceptance-tests/index.html
• Testing Patterns
  • https://www.terraform.io/docs/extend/best-practices/testing.html

ユニットテストは次のように書くことができる。

• 自作Terraform Providerのユニットテストの書き方

少しハマったところ

Goをやっていれば型を使って実装をするだろう。
Terrform Providerを実装するさいは型（構造体）を使って結果を取得しても、そのあとは構造体フィールドをひとつひとつセットしないといけないようだった。

func resourceGraphRead(_ context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
	// Warning or errors can be collected in a slice type
	var diags diag.Diagnostics
	client := m.(*pixela.Client)

	g, err := client.Graph().Get(&pixela.GraphGetInput{ID: pixela.String(d.Id())})
	if err != nil {
		return diag.FromErr(err)
	}
	if err := d.Set("graph_id", g.ID); err != nil {
		return diag.FromErr(err)
	}
	if err := d.Set("name", g.Name); err != nil {
		return diag.FromErr(err)
	}
	if err := d.Set("type", g.Type); err != nil {
		return diag.FromErr(err)
    }
    // ...

また、レジストリ登録時に少しハマったが、ちゃんと手順通りにやっていれば問題ない（完全に私が悪かった）。

• TerraformレジストリにリリースしようとGPG Keyをimportしようとすると「Could not find valid encryption key packet in key ~~」とエラーになる

Special Thanks…

1.20.1以前のPixelaはグラフ単体のJSON情報を取得することができなかった。
なので@a-knowさんにリクエストしてエンドポイントを増やしてもらった。大感謝…

https://github.com/a-know/Pixela/releases/tag/v1.21.0

終わりに

PixelaをTerrformで使うためのProviderを作った。ProviderはPixelaのAPI操作に3rdパーティのライブラリを使っているのだが、少し使い方が合わないのでも自作ライブラリを作って差し替える予定。
グラフにプロットするPixel自体もサポートしようかなとと思うが、毎回terraformでプロット打つのはちょっと違うかなと思っているので、Provider自体はどうやって機能拡張しようか考えている。

他にもteraformサポート外のAPIを見つけたらProviderを書いてみたい。

参考

• https://github.com/budougumi0617/terraform-provider-pixela
• https://registry.terraform.io/providers/budougumi0617/pixela
• https://pixe.la/ja
• https://learn.hashicorp.com/collections/terraform/providers

関連

• TerraformレジストリにリリースしようとGPG Keyをimportしようとすると「Could not find valid encryption key packet in key ~~」とエラーになる
• 自作Terraform Providerのユニットテストの書き方