traP-jp Organization のメンバー・チームを管理する Terraform

Terraform v1系を使用しています。

• GitHub Organizationについて https://docs.github.com/ja/organizations/collaborating-with-groups-in-organizations/about-organizations
• Terraformについて https://www.terraform.io/

.
├── README.md
├── docs
│   └── image.png
├── hackathon # ハッカソン用の設定
│   ├── h23s.tf
│   └── h23w.tf
├── main.tf # providerの設定やteams.tf, members.tf, hackathon以下を取り込んでの実行
├── members.tf # orgのメンバー管理
├── modules # モジュール
│   ├── members # orgのメンバー
│   │   ├── main.tf
│   │   ├── provider.tf
│   │   └── variables.tf
│   └── teams # orgのチームとそのメンバー
│       ├── main.tf
│       ├── output.tf
│       ├── provider.tf
│       └── variables.tf
└── teams.tf # 親子関係の無いチーム

Organization のメンバー・チーム情報をコードで一元管理し、反映を GitHub Actions と Google Cloud Storage を用いて行います。

1. mainブランチへのプルリクエストを出すと、GitHub Actions で以下がチェックされる
   1. terraform validate
   2. terraform fmt
   3. terraform plan
2. plan の結果が自動的にコメントされる
3. Admin がレビューする
4. マージされたタイミングで terraform apply が実行され、変更が反映される

::: warning

Organization の Admin は terraform では管理せず、手動で管理しています。 詳細は「Organization の admin を追加したい」セクションを確認してください。

:::

リポジトリルートのmembers.tf を編集してください。 membersの配列の中にGitHubのIDを追加し、横にコメントでtraQのIDを併記してください。 可能ならアルファベット順にすることが望ましいですが、PRの要件とはしません。

locals {
  members = [
    "ikura-hamu", # ikura-hamu
    "H1rono", # H1rono_K
  ]
}

一部コメントで traQ の ID が記載されていないメンバーが居ますが、これは terraform での管理前に追加されたメンバーです。 適宜コメントを追加していただけると助かります。

teams.tf の teams の中に以下のように追記してください。

"team-name" = {
  members = ["aaa", "bbb"] # チームのメンバーのGitHub ID
  maintainers = ["ccc", "ddd"] # チームのメンテナーGitHub ID
  description = "チームの説明" # optional だがチーム名から推測し辛い場合は記載すること
  secret = false # Organization 内に公開されているチームか否か。デフォルトはfalse（公開）
}

secret について：チーム情報全体が Public Repository で運用されていることから traP-jp organization でチームを secret にする理由はあまりないと考えていますが、判断は個々人に委ねられます。

チームの数にもよりますが、基本的にファイルを分けて記述してください。

ファイルの記述方法は hackathon/h23s.tf を参考にしてください。

ファイルの作成場所は以下に従ってください。

• ハッカソンの設定を追加したい場合：hackathon フォルダ内
• それ以外の親子関係のあるチームを作りたい場合：リポジトリルート

記述方法はどちらも基本的に共通です。ただし、module の source は相対パス です。ご注意ください。

xxx-teamというチームの下にxxx_01とxxx_02 というチームを作成する場合（リポジトリルート下に設置）

module "xxx_parent_team" {
  source = "./modules/teams" # hackathonフォルダの下であれば、 "../modules/teams" にする

  team_name   = "xxx-team" # 親チーム名
  members     = local.xxx_parent.members
  maintainers = local.xxx_parent.maintainers
  description = "親チームの説明"
}

module "xxx_children_teams" {
  for_each = local.xxx_children
  source   = "./modules/teams" # hackathonフォルダの下であれば、 "../modules/teams" にする

  team_name   = each.key
  members     = each.value.members
  maintainers = each.value.maintainers
  description = contains(keys(each.value), "description") ? each.value.description : ""

  parent_id = module.xxx_parent_team.team_id
}

locals {
  xxx_parent = {
    members = ["aaa", "bbb", "ccc", "ddd"] # 親チームのメンバーの GitHub ID
    maintainers = ["eee"] # 親チームのメンテナーの GitHub ID
  }

  xxx_children = {
    "xxx_01" = {
      members     = []
      maintainers = ["aaa", "bbb"]
      description = "チーム01"
    }

    "xxx_02" = {
      members     = ["ccc"]
      maintainers = ["ddd"]
      secret = true
    }
  }
}

3階層以上の親子関係も作成しようと思えば作成可能です。

admin のみ terraform で管理しない運用をするため、煩雑な手順を踏んています。

1. members.tf から、新しく Admin になるユーザーをコメントアウトし、その上 admin と分かるようにコメントを追記してください。
2. 1 の PR を作成し main に反映させてください。
3. 既存の Admin が github.com の UI 上から新しい admin を招待し、 admin に登録してください。
4. 新しい Admin が所属しているチームについて、チームのmembersに含まれている場合は、tfファイルを編集して、すべてmaintainersにしてください。
   • OrgのAdminはチームに所属すると必ずmaintainerになるという GitHub の仕様に合わせるためです。

1. [Organization のメンバーを編集する](#Organization のメンバーを編集する) と同様に members.tf に追加してください。
2. チームのmaintainerから外したい場合は、それぞれmaintainersからmembersに移動させてください。

Terraformのバックエンドとして、SysAd班のGCPアカウントのGoogle Cloud Storageのtrap-tfstateというバケットを使用しています。

GitHub ActionsにはPERSONAL_TOKENとGOOGLE_BACKEND_CREDENTIALSの二つのsecretを設定する必要があります。

• PERSONAL_TOKEN
  • Adminの誰かのGitHubのFine-grained token
  • Organization の members への Read,Write 権限が必要
  • 以下のようになっていれば OK
• GOOGLE_BACKEND_CREDENTIALS
  • GCS の credential 情報