Docker上のAtlantisでTerraformを自動化：実践的なGitOpsガイド

Table of Contents

背景と目的：手動でのTerraform管理における課題

Terraformを使用したInfrastructure as Code (IaC) の管理は、通常、個人プロジェクトとして始まります。HCLを記述し、terraform plan を実行し、ターミナルから apply を叩く。チームに2人目のエンジニアが加わるまでは、すべてが順調に進みます。しかし、突然摩擦が生じ始めます。オフィスで「最後にステージング環境のRDSを更新したのは誰？」「なぜステートファイルが20分間もロックされているの？」といった叫び声が聞こえてくるようになるのです。

ローカルでの実行はギャンブルのようなものです。中央集中型の監査トレイル（証跡）が欠如しており、「自分のマシンでは動く」シンドロームを招きます。これは軽量なセルフホストDevOpsスタックを構築する際に直面する共通の課題です。あるエンジニアはAWSプロバイダーのv4.0を実行し、別のエンジニアはv5.0を使用しているといった状況が発生し、即座にステートの乖離（ドリフト）に繋がります。GitOpsは、実行環境を個人のPCから切り離すことで、この問題を解決し、「自分のマシンでは動くのに」の終焉を実現します。インフラの進化は、手動のターミナルコマンドではなく、Gitのコミットを通じて行われるようになります。

Atlantisはこのギャップを埋めるツールです。GitHub、GitLab、Bitbucketなどのウェブフックをリッスンする専用アプリケーションです。プルリクエスト（PR）を作成すると、Atlantisはプランを実行し、その出力をPRのコメントとして返信します。チームが承認したら、atlantis apply とコメントするだけで変更がトリガーされます。50以上のマイクロサービスを抱えるクラスターを管理してきた私の経験では、このワークフローによって、環境間の「同期ズレ」による頭痛の種の90%が解消されました。

インストール：DockerでのAtlantisデプロイ

Dockerデプロイの自動化は、ホストシステムを汚さずにAtlantisを稼働させるための最も速い方法です。Docker Composeを使用して、コンテナとその環境変数をオーケストレーションします。

1. 前提条件

DockerとComposeがインストールされたLinux VPSまたはローカルマシン。
リポジトリへの管理者権限を持つGitHubアカウント。
外部公開されているIPまたはドメイン。Atlantisはウェブフックを受信する必要があります。ローカルでのテストには、ngrok などのツールを使用してポート4141をインターネットに公開できます。

2. Docker Composeの設計図

まず、専用のディレクトリを作成します。その中に docker-compose.yml ファイルを追加します。この設定では公式イメージを取得し、Terraformのデータを保存するための永続ボリュームをマッピングします。

version: '3.8'

services:
  atlantis:
    image: runatlantis/atlantis:latest
    container_name: atlantis
    ports:
      - "4141:4141"
    volumes:
      - ./atlantis-data:/atlantis-data
    environment:
      - ATLANTIS_GH_USER=your-github-username # あなたのGitHubユーザー名
      - ATLANTIS_GH_TOKEN=your-github-token # あなたのGitHubトークン
      - ATLANTIS_GH_WEBHOOK_SECRET=your-webhook-secret # あなたのウェブフックシークレット
      - ATLANTIS_REPO_ALLOWLIST=github.com/your-org/* # 許可するリポジトリのリスト
      - ATLANTIS_DATA_DIR=/atlantis-data
      - ATLANTIS_ATLANTIS_URL=http://your-public-url:4141 # 公開URL
    restart: always

セキュリティは重要です。ATLANTIS_REPO_ALLOWLIST は主要な防御策であり、検証済みのリポジトリのみがボットをトリガーできるようにし、Infrastructure as Code のセキュリティ確保を強化します。

設定：双方向のハンドシェイク

コンテナの準備ができたら、サーバーとGitHub間の接続を承認する必要があります。これには、個人アクセストークン（PAT）と特定のウェブフック設定が必要です。

1. GitHub PATの生成

GitHubの Settings > Developer Settings > Personal Access Tokens (Classic) に移動します。repo スコープを持つトークンを作成します。これにより、AtlantisはHCLファイルを読み取り、コメントを投稿できるようになります。このトークンは一度しか表示されないため、すぐにコピーして ATLANTIS_GH_TOKEN 変数に貼り付けてください。モダンなシークレット管理が、安全な自動化の鍵となります。

2. GitHubウェブフックの設定

自動化したいリポジトリを開きます。Settings > Webhooks > Add webhook に移動します。

Payload URL: http://your-public-url:4141/events
Content type: application/json
Secret: ATLANTIS_GH_WEBHOOK_SECRET に設定した文字列を正確に使用してください。
Events: 「Let me select individual events」を選択し、Issue comments, Pull requests, Pull request reviews, および Pushes にチェックを入れます。

3. atlantis.yaml による詳細な制御

Atlantisはデフォルトですべてのディレクトリで .tf ファイルをスキャンします。正確な制御を行うには、リポジトリのルートに atlantis.yaml ファイルを配置します。これにより、特定のプロジェクトとその自動化ルールを定義できます。

version: 3
projects:
- name: staging-app # ステージング環境アプリ
  dir: staging/us-east-1
  autoplan:
    when_modified: ["*.tf", "../modules/**"]
    enabled: true
- name: production-app # 本番環境アプリ
  dir: prod/us-east-1
  autoplan:
    enabled: false # 重要な環境のため手動プランのみ

検証：初めての自動化PR

いよいよ運命の瞬間です。コンテナを起動しましょう：

docker-compose up -d

1. 実際のワークフロー

新しいブランチを作成し、既存のリソースに簡単なタグを追加して、プルリクエストを作成します。数秒後、Atlantisが起動するはずです。Atlantisは変更をスキャンし、terraform plan の出力を整形したコメントとしてPRのスレッドに直接投稿します。

プランを慎重に確認してください。差分が正しければ、新しいコメントを入力します：

atlantis apply

ボットがコマンドを実行し、結果を報告します。成功すると、PRがマージされるまで競合状態を防ぐためにプロジェクトにロックをかけます。

2. モニタリングとトラブルシューティング

http://your-public-url:4141 にアクセスして Atlantis UI を確認します。現在のステートロックの状態が明確に表示されます。PRの後にボットが反応しない場合は、すぐにログを確認してください：

docker logs -f atlantis

403 Forbiddenエラー（通常はトークンの権限の問題）や400エラー（多くはウェブフックシークレットの不一致）に注意してください。このDockerベースのアプローチを採用することで、インフラの成長に合わせて、隔離され、再現可能で、スケーリングが容易なCI/CDパイプラインを確保できます。