Terraform Provider for TROCCO

概要

Terraform Provider for TROCCOは、TROCCOの各種リソースをTerraformでコード管理するためのプロバイダーです。
Infrastructure as Code（IaC）の手法により、TROCCOの設定をコードベースで運用・管理できます。

Terraform Provider for TROCCOのソースコードは、GitHubで公開されています。

ユースケース

Terraform Provider for TROCCOのユースケースをご紹介します。

• 開発環境で作成した転送設定やデータマート定義をコード化し、ステージング環境や本番環境向けの設定を接続情報やカスタム変数を切り替えながら作成できます
• Terraformの.tfファイルをGitリポジトリで管理し、PRベースのレビューやCI/CDによる自動適用を実現できます
• 過去のプロジェクトで作成した転送設定やデータマートの一部分だけを流用し、新規PJ向けの設定として作成できます

推奨する使用方法

TROCCOは設定項目が多いため、すべての設定をはじめから.tfファイルに手書きすることは推奨しません。
まずTROCCOのGUIで設定を作成し、terraform importでTerraformの管理下に取り込む方法が効率的です。

Terraform管理するリソースの見極め

TROCCOはGUIで手軽に設定を作成できることがメリットのひとつです。
すべてのリソースをTerraformで管理しようとするのではなく、厳格に管理したいリソースを見定めて管理スコープを決めることが重要です。
組織内で「どのリソースをTerraform管理下に置くか」の運用ルールを策定することを推奨します。

以下に、Terraform管理に移行するリソースを選定する際の指針を示します。

1. まずはチームやリソースグループなど、権限管理に関わるリソースから始めます。HCLの記述量が比較的少なく、Terraform自体の習熟にも適しています
2. 接続情報など、センシティブな情報を扱うリソースを管理下に置きます。変更頻度が低く、厳格な管理が求められるため、Terraform管理との相性がよいです
3. そのうえで、ミッションクリティカルな転送設定やデータマート定義、ワークフロー定義から徐々に移行していきます

エンジニア以外のビジネスメンバーがGUIから直接作成・運用するような転送設定まで、すべてTerraform管理にする必要はありません。
TROCCOのGUIによる手軽さを活かしつつ、厳格に管理すべき部分にTerraformを適用するのが効果的です。

立ち上げ時

1. TROCCOのGUIで開発環境向けの転送設定やデータマート定義を作成します
2. terraform importで既存の設定をTerraformの管理下に取り込みます
3. 取り込んだ設定をベースに、接続情報やカスタム変数を切り替えたステージング環境・本番環境向けの設定を.tfファイルで定義します
4. .tfファイルをGitリポジトリで管理し、PRベースのレビューやCI/CDを通じて各環境に適用します

運用時

• Terraform管理下の転送設定やデータマート定義、ワークフロー定義にリソースグループやラベルを設定します
  • たとえば本番環境用の設定はリソースグループで管理者以外が編集できないようにします
  • Terraform管理しているリソースにはそれとわかる専用のラベルを付与し、UI上で見分けをつけやすくします（例：Terraform Managed）
• GitHub ActionsなどのCI/CDツールで定期的にterraform planを実行し、GUI上での手動変更を検知する運用も有用です

Providerのセットアップ

以下のコードを.tfファイルに記述して、Terraform Provider for TROCCOを利用できます。

terraform {
  required_providers {
    trocco = {
      source = "registry.terraform.io/trocco-io/trocco"
    }
  }
}

provider "trocco" {
  api_key = var.trocco_api_key
  region  = "japan"
}

variable "trocco_api_key" {
  type      = string
  sensitive = true
}

認証

TROCCO APIキーを使用して認証します。
APIキーは以下のいずれかの方法で設定できます。

• providerブロックのapi_keyパラメータに指定する
• 環境変数TROCCO_API_KEYに設定する

リージョン

regionパラメータには、ご利用のTROCCO環境に対応するリージョンを指定します。
リージョンは以下のいずれかの方法で設定できます。

• providerブロックのregionパラメータに指定する
• 環境変数TROCCO_REGIONに設定する

指定可能なリージョンは以下のとおりです。

• japan

対応リソース

Terraform Provider for TROCCOでは、以下のTROCCOリソースを管理できます。

各リソースの詳細な設定方法やパラメータについては、Terraform Registry - trocco Providerを参照ください。

コードサンプル

転送設定（MySQL to BigQuery）

以下は、MySQLからBigQueryへの転送設定の最小構成例です。

resource "trocco_job_definition" "mysql_to_bigquery" {
  name                     = "mysql_to_bigquery_example"
  is_runnable_concurrently = false
  retry_limit              = 0

  input_option_type = "mysql"
  input_option = {
    mysql_input_option = {
      mysql_connection_id = 1
      database            = "example_database"
      query               = "SELECT id, name, created_at FROM example_table"
      fetch_rows          = 10000
      connect_timeout     = 300
      socket_timeout      = 1800
      input_option_columns = [
        { name = "id",         type = "long" },
        { name = "name",       type = "string" },
        { name = "created_at", type = "timestamp" },
      ]
    }
  }

  output_option_type = "bigquery"
  output_option = {
    bigquery_output_option = {
      bigquery_connection_id = 1
      dataset                = "example_dataset"
      table                  = "example_table"
      location               = "US"
      mode                   = "append"
    }
  }

  filter_columns = [
    { name = "id",         src = "id",         type = "long" },
    { name = "name",       src = "name",       type = "string" },
    { name = "created_at", src = "created_at", type = "timestamp" },
  ]
}

転送設定は設定項目が多いため、推奨ワークフローのようにGUIで作成した設定をterraform importで取り込む方法も検討ください。
詳細なパラメータについてはTerraform Registry - trocco_job_definitionを参照ください。

BigQueryデータマート定義

resource "trocco_bigquery_datamart_definition" "example" {
  name                     = "example datamart"
  is_runnable_concurrently = false
  bigquery_connection_id   = 1
  query                    = "SELECT * FROM tables"
  query_mode               = "insert"
  destination_dataset      = "dist_datasets"
  destination_table        = "dist_tables"
  write_disposition        = "append"
}

詳細なパラメータについてはTerraform Registry - trocco_bigquery_datamart_definitionを参照ください。

ワークフロー定義

resource "trocco_pipeline_definition" "example" {
  name = "example workflow"

  tasks = [
    {
      key  = "transfer_first"
      type = "trocco_transfer"
      trocco_transfer_config = {
        definition_id = 1
      }
    },
    {
      key  = "transfer_second"
      type = "trocco_transfer"
      trocco_transfer_config = {
        definition_id = 2
      }
    },
  ]

  task_dependencies = [
    {
      source      = "transfer_first"
      destination = "transfer_second"
    },
  ]
}

詳細なパラメータについてはTerraform Registry - trocco_pipeline_definitionを参照ください。