こんにちは。CircleCI カスタマーサクセスチームの Chisato です。
最近、野菜を7種類ほど育て始めました。
毎朝の水やりで成長を感じるのが日々の楽しみです。
今回は、CircleCI のサポートエンジニアである Kelvin さんが作成した、CircleCI のための Terraform プロバイダー（Terraform Provider for CircleCI）をご紹介します。
この Terraform プロバイダーは、まだ CircleCI の公式ではないため、ご利用の際はご注意ください。
準備するもの
- CircleCIのアカウント と プロジェクト
- Terraform
Terraform の設定
Terraform は、HashiCorp社 が提供する IaC (Infrastructure as Code)のツールで、構築、変更、バージョン管理といったインフラの構成管理を安全かつ効率的に実行可能にします。
こちらのページ にアクセスして、Terraform をインストールします。
macOS のオープンソース版は Homebrew でインストールできます。
~ % brew tap hashicorp/tap
~ % brew install hashicorp/tap/terraform
正しくインストールされたか確認するには、terraform versionのコマンドを用います。
~ % terraform version
Terraform v1.4.5
on darwin_amd64
Terraform プロバイダー
Terraform のプロバイダーを用いると、あらゆるサービスの API と連携できます。
たとえば、Terraform の公式チュートリアルでは、AWS EC2 を作成するプロバイダーが紹介されています。
Terraform の Registry では、さまざまなプロバイダーを検索・利用できます。
今回ご紹介するプロバイダーを用いると、CircleCI の下記のリソースを簡単に作成・管理できます。
下記リソースは、通常CircleCIのUIから作成するものです。
たとえば環境変数は、一度作成すると値をどこかに保存しておく必要があったり、管理や削除のために該当のページにアクセスしたりする手間が発生します。
一方、このプロバイダーを使うと、下記リソースの作成/設定、編集、削除が簡単に Terraform の *.tf ファイルで実行できます。
- Project Webhook （ウェブフック）
- Project Scheduled Pipeline（パイプラインのスケジュール実行）
- Project Environment Variables（環境変数）
- Project Checkout key（チェックアウトキー）
- Context（コンテキスト）
- Context Environment Variables（コンテキストの環境変数）
Webhook を作成・管理する
Terraform は名前が強そうでかっこいいので、プロバイダーの設定も複雑なのかと構えていましたが、実際は非常にシンプルでした。
ここでは、Webhookを作成してみます。
1. 対象プロジェクトのディレクトリ内に、main.tf というファイルを作成します。
2. プロバイダーのページにアクセスして、USE PROVIDER をクリックします。下図のピンク色で囲ったコード部分をクリックしてコピーします。または、図の下のコードをコピーして利用できます。
terraform {
required_providers {
circleci = {
source = "kelvintaywl/circleci"
version = "0.9.3"
}
}
}
provider "circleci" {
# Configuration options
}
3. main.tf の中に、コピーしたコードをペーストして保存します。
4. プロバイダーのページで Documentation をクリックします。次に、遷移先ページ左側の Resources のドロップダウンメニューをクリックして展開します。 Resources欄には、機能の作成・管理方法が記載されています。
5. 機能一覧から使いたい機能をクリックし、Example Usage 下部のコードをコピーします。Webhookは下記のコードをコピーして使用できます。
こちらも、main.tf を開き、先ほどペーストしたコードの下にペーストします。
data "circleci_project" "my_project" {
slug = "github/acmeorg/foobar"
}
resource "circleci_webhook" "my_webhook" {
project_id = data.circleci_project.my_project.id
name = "my_webhook"
url = "https://example.com/hook"
signing_secret = "5uperSeCr3t!"
verify_tls = true
events = [
// accepts only "workflow-completed" and "job-completed"
"job-completed",
"workflow-completed"
]
}
output "webhooks" {
description = "my_webhook_id"
value = circleci_webhook.my_webhook.id
}
5. CircleCI を開き、該当するプロジェクトのProject Settingsページに移動します。
下記のピンク色で囲ったアイコンをクリックして、Project IDをコピーします。
6. main.tf ファイルを開いて、project_id = "プロジェクトID" 部分に先ほどコピーしたIDをペーストします。
terraform {
required_providers {
circleci = {
source = "example.com/kelvintaywl/circleci"
}
}
}
provider "circleci" {
// api_token = ""; or set via CIRCLE_TOKEN
// hostname = "https://circleci.com"; or set via CIRCLE_HOSTNAME
}
locals {
// 下記に CircleCI の project ID をペースト
project_id = "プロジェクトID"
}
resource "circleci_webhook" "my_webhook" {
project_id = local.project_id
name = "my_webhook"
url = "WebhookのためのURL"
signing_secret = "5uperSeCr3t!"
verify_tls = true
events = [
// accepts only "workflow-completed" and "job-completed"
"job-completed",
"workflow-completed"
]
}
output "webhooks" {
description = "my_webhook_id"
value = circleci_webhook.my_webhook.id
}
7. main.tf の provider "circleci" 部分は、コメントアウトしてあります。
CircleCIとの連携には、環境変数( Enviroment Variables )、またはパーソナル API トークン（ Personal API Token ）を利用できます。
今回はパーソナル API トークンを .bash_profile に保存して、 CircleCI と連携しました。
パーソナルAPIトークンは、CircleCIのダッシュボード左下にある自分のアイコンをクリックし、User Settings ページの Personal API Tokens タブから作成できます。
export CIRCLE_TOKEN="パーソナルAPIトークン"
8. 今回は Webhook との連携に AirTable を使用しました。
Airtable 上で Create a base 、画面上部の Automations と進み、When webhook received を選択します。
その他の設定は、下図を参照ください。今回は、特定のワークフローが走るたびに、「ジョブごとのID」、「ジョブの名前」、「ビルド結果」を取得できるように設定しました。
最後にトグル（ピンクで囲った部分）を ON にするのをお忘れなく。
最後に、右側の設定画面に表示されたURLをコピーします。
9. main.tf のファイルで、resource の url = "WebhookのためのURL" に先ほどコピーしたURLをペーストします。
10. terraform init のコマンドを実行します。"Terraform has been successfully initialized!" というメッセージが返ってきたら、次に進みます。
% terraform init
9. どのような変更が加えられるかをレビューするため、下記コマンドを実行します。
~ % terraform plan
10. 内容のレビューが完了したら、下記コマンドで実際にWebhookを作成します。実行確認のメッセージが出てくるので、yes と入力します。
~ % terraform apply
~省略~
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
circleci_webhook.my_webhook: Creating...
circleci_webhook.my_webhook: Creation complete after 0s [id=]
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
Outputs:
webhooks = ""
無事に Webhook が作成されました！
Webhookが実行され、無事にワークフローが成功したことがテーブルに記録されました。
機能の設定を変更したいときは、main.tf を編集後に、先ほどと同じ要領で teffaform plan、そして terraform apply を実行すれば簡単に変更できます。
また、Webhookの機能が不要になった場合、下記コマンドを実行することで削除できます。
~ % terraform destroy
プロジェクトの環境変数を作成・管理する
こちらのページのコードを用いて、環境変数を作成してみました。
下記コードのうち、"FOOBAR" と "FIZZBUZZ"のところに環境変数名、その後ろに環境変数の値を入れます。
project_slug でプロジェクトを指定します。VCS組織/VCS組織名/プロジェクト名 です。
terraform {
required_providers {
circleci = {
source = "kelvintaywl/circleci"
version = "0.9.3"
}
}
}
provider "circleci" {
// api_token = ""; or set via CIRCLE_TOKEN
// hostname = "https://circleci.com"; or set via CIRCLE_HOSTNAME
}
# using for_each to generate multiple env var resources
resource "circleci_env_var" "my_env_vars" {
for_each = {
"FOOBAR" = "0Cme2FmlXk"
"FIZZBUZZ" = "Vbt2efixZAkrmTYiirhd"
}
project_slug = "github/chisato-ygc/hello-world"
name = each.key
value = each.value
}
先ほどと同じ要領で teffaform plan、そして terraform apply を実行します。
Project Settings ページで、環境変数が作成されていることを確認できました。
環境変数名も変数の値も、簡単に編集できます。
もちろん、terraform destroy で簡単に削除もできます。
おわりに
今回のプロジェクトのおかげで、Terraform に関する理解が以前より深まりました。
Kelvin さんには Terraform の仕組みや今回のプロジェクトについて丁寧に説明していただきました。
いつもありがとうございます。
また、プロバイダーのあまりの便利さに、さらにテクニカルな部分について学びたいという意欲が高まりました。
この記事を書いているのが4月末なので、ゴールデンウィークによってその意欲が吹き飛んでしまわないことを祈るばかりです。
がんばれ、未来の自分。
最後までお読みいただきありがとうございました。
参考URL
Terraform Documentation - Providers : https://developer.hashicorp.com/terraform/language/providers
技術的なご質問は、サポートセンターまでお問い合わせください。