Cloudflare 34：Wrangler と Terraform ― Cloudflare をコードで扱う

2つの道具：wrangler と Terraform

Cloudflare の管理画面でできることは、ほぼすべて Cloudflare API からもできます。管理画面も、裏ではこの API を呼んでいます。wrangler も Terraform も、この API を呼ぶ道具です。違いは、得意な範囲です。

ざっくり言うと、アプリを作る人の道具が wrangler、土台を管理する人の道具が Terraform です。

両方を使う会社も多くあります。たとえば、DNS やセキュリティのルールは Terraform で管理し、Worker のコードは wrangler で公開する、という分け方です。Workers そのものも Terraform で管理できますが、コードの開発と公開の流れは wrangler のほうが圧倒的に手軽です。

大事なのは、同じものを2つの道具で管理しないことです。落とし穴のページで、その理由を見ます。

wrangler：作る・試す・公開するを1つで

wrangler は、Cloudflare が作っている公式のコマンドラインツールです。Node.js のパッケージとして配られているので、プロジェクトに入れて npx wrangler で使います。

始め方は次のとおりです。

npm create cloudflare@latest my-app   # ひな形からプロジェクトを作る
cd my-app
npx wrangler login                    # ブラウザでログインして、この PC を許可する
npx wrangler dev                      # 手元で動かす
npx wrangler deploy                   # Cloudflare に公開する

npm create cloudflare は、Worker のひな形や、フレームワーク（React・Astro など）の雛形を選んでプロジェクトを作ってくれます。wrangler login は、ブラウザで Cloudflare にログインし、この PC から API を呼んでよいと許可する手順です。

wrangler deploy を実行すると、コードをまとめて Cloudflare に送り、数秒で世界中の拠点に行き渡ります。サーバーを選んだり、台数を決めたりする必要はありません。

このあと見るように、wrangler はデプロイだけでなく、D1 のデータベースを作る、秘密の値を登録する、本番のログを見る、といった仕事もこなします。Workers の開発は、ほぼ wrangler だけで完結すると考えてよいでしょう。

wrangler dev：手元で本物に近い形で動かす

開発中にいちばん使うのが wrangler dev です。手元の PC で Worker を動かし、ブラウザで http://localhost:8787 を開けば試せます。

手元で動かすときも、Cloudflare の本番と同じ実行環境（workerd という、Workers を動かしているソフトウェア）が使われます。「手元では動いたのに本番で動かない」が起きにくい作りです。ファイルを保存すると、自動で読み直されます。

D1（23号）・KV（20号）・R2（22号）などのバインディングも、手元では手元のデータで動きます。本番のデータを壊す心配がありません。

API キーなどの秘密の値は、手元では .dev.vars というファイルに書きます。このファイルは Git に入れないようにします（.gitignore に足す）。本番の秘密の値は、後で見る wrangler secret put で登録します。

設定ファイル：wrangler.jsonc に全部書く

Worker の設定は、プロジェクトの設定ファイルに書きます。形式は wrangler.jsonc（コメントが書ける JSON）と wrangler.toml の2つがあり、中身は同じです。Cloudflare は新しいプロジェクトには jsonc を勧めています。新しい機能の一部は JSON の設定でしか使えないからです。

{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-01",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [{ "binding": "DB", "database_name": "app", "database_id": "…" }],
  "r2_buckets": [{ "binding": "FILES", "bucket_name": "app-files" }],
  "vars": { "MODE": "production" }
}

このファイルを Git に入れておけば、「どの Worker が、どのデータベースを使っているか」が、コードといっしょに履歴に残ります。wrangler types を実行すると、このファイルから env の型が作られます。

環境を分ける：検証と本番を1つのファイルで

本番に出す前に、検証用の環境で確かめたいものです。wrangler では、1つの設定ファイルの中に環境（env）を書き分けられます。

{
  "name": "my-app",
  "d1_databases": [{ "binding": "DB", "database_name": "app", "database_id": "…" }],
  "env": {
    "staging": {
      "vars": { "MODE": "staging" },
      "d1_databases": [{ "binding": "DB", "database_name": "app-staging", "database_id": "…" }]
    }
  }
}

公開するときに --env で環境を選びます。

環境ごとに別の Worker として公開されるので、検証を壊しても本番には影響しません。

注意したいのは、バインディングや vars は、上の階層から引き継がれないことです。env.staging にデータベースを書き忘れると、検証の Worker にはデータベースが無い、ということになります。環境ごとに、必要なバインディングを全部書きましょう。

よく使うコマンド：秘密・ログ・データ

wrangler には、デプロイ以外にも便利なコマンドがたくさんあります。

秘密の値（API キー・パスワード）は、vars に書いてはいけません。vars は設定ファイルに平文で残り、Git にも入ってしまいます。secret put で登録した値は暗号化して保存され、コードからは env.API_KEY として読めます。

wrangler tail は、本番で何が起きているかを見るのに欠かせません。console.log の出力やエラーが、その場で流れてきます。長く保存して調べたいなら、分析とログ（32号）の機能を使います。

Terraform：アカウントの設定を、コードで持つ

Terraform は、HashiCorp が作っている、インフラをコードで管理するための道具です。AWS や Google Cloud でも広く使われていて、Cloudflare 用の部品（プロバイダー）は Cloudflare が公式に提供しています。

Terraform の考え方は「あるべき姿を書く」です。「DNS の www という行は、この値であるべき」と書いておくと、Terraform が今の姿と比べて、足りないものを作り、違うものを直し、要らないものを消します。

いちばんの価値は plan です。反映する前に「何が変わるか」を目で確かめられます。プルリクエストに plan の結果を貼ってレビューしてもらえば、DNS の書き間違いでサイトが止まる、といった事故を防げます。

管理画面で作った既存の設定を Terraform に取り込むには、Cloudflare の cf-terraforming という道具で、今の設定を Terraform のファイルとして書き出せます。

Terraform の書き方：DNS レコードを1つ

Terraform の設定は、.tf というファイルに HCL という書き方で書きます。DNS の行を1つ作る例です。

terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 5"
    }
  }
}

provider "cloudflare" {}   # トークンは環境変数 CLOUDFLARE_API_TOKEN から読む

resource "cloudflare_dns_record" "www" {
  zone_id = var.zone_id
  name    = "www"
  type    = "CNAME"
  content = "my-app.pages.dev"
  proxied = true   # オレンジの雲（01号）
  ttl     = 1      # 1 は「自動」
}

resource が「あるべき姿」の1つです。同じように、ゾーンの設定、リダイレクトや WAF のルール（09・05号）、Access のアプリ（16号）なども書けます。

Terraform は、今の姿を state（状態のファイル）に記録します。チームで使うときは、state を各自の PC に置かず、共有の置き場に置きます。R2（22号）は S3 と同じ形で使えるので、state の置き場としても使えます。

プロバイダーは版によって書き方が変わることがあります。とくに版5では資源の名前がいくつか変わりました（DNS は cloudflare_dns_record）。古い記事の例をそのまま使わず、使っている版の説明を見てください。

API トークン：必要な権限だけを渡す

wrangler も Terraform も、Cloudflare API を呼ぶために資格情報が要ります。手元では wrangler login のようにブラウザでログインできますが、CI や Terraform では API トークンを使います。

API トークンは、管理画面の「My Profile」の「API Tokens」で作ります。作るときに、できることの範囲を細かく決められます。

大事なのは、最小権限の考え方です。Terraform で DNS だけを管理するなら、トークンには「そのゾーンの DNS を編集」だけを付けます。CI で Worker を公開するなら、「Workers を編集」だけです。万一トークンが漏れても、被害をその範囲に閉じ込められます。

古くからある Global API Key は、アカウントのすべてを操作できる鍵です。道具に渡すのは避けましょう。トークンは、道具ごと・用途ごとに分けて作り、要らなくなったら消します。

CI：main に入ったら、自動で公開する

手元の PC から wrangler deploy するのは、最初のうちは手軽です。でもチームで開発するなら、レビューを通ったコードだけが、自動で本番に出る形にしたいものです。これが CI（継続的インテグレーション）からのデプロイです。

GitHub を使っているなら、Cloudflare 公式の wrangler-action が使えます。

name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

API トークンとアカウント ID は、リポジトリの Secrets に入れます。ファイルに直接書いてはいけません。

もっと手軽な方法として、管理画面で Git のリポジトリをつなぐだけで、push のたびに Cloudflare がビルドと公開をしてくれる Workers Builds もあります。プルリクエストごとにプレビューの URL を作ることもできます。Terraform も同じように、プルリクエストで plan の結果を表示し、main に入ったら apply する、という流れを CI に組むのが定番です。

料金と制限：道具は無料。API には回数の上限

wrangler も、Terraform の Cloudflare プロバイダーも、それ自体は無料です。

お金がかかるのは、道具で作ったものの使用量です。Worker のリクエストや、D1・R2 の使用量は、それぞれの号の料金のとおりに数えられます。

気をつけたいのは、Cloudflare API を呼べる回数に上限があることです。短い時間にあまりにたくさん呼ぶと、しばらく断られます。何千もの DNS レコードを一度に apply するような場面では、この上限に当たることがあります。上限に当たったら、少し待ってからやり直すか、変更を分けて反映します。

※2026年9月時点の情報です。料金・上限は変わるので、公式の Pricing と Limits のページで確かめてください。

よくある落とし穴

wrangler と Terraform でつまずきやすい点です。

いちばん多いのは2つめです。Terraform で管理しているものを、急ぎのときに管理画面で直してしまうと、次に誰かが apply したときに、何の警告もなく元に戻ります。コードで管理すると決めたら、コード以外から変えないのが鉄則です。