🚘

Cloudflare Workersのwrangler.tomlを見てみる

2024/12/24に公開

Cloudflare

worker

tech

記事の概要

Cloudflare Workersの開発に便利なwrangler.tomlについてまとめてみました。
最初にそもそもWrangler（ラングラー）の解説をしていますが、既知でしたら飛ばしていただいても大丈夫です🙆‍♂️
~~私はラングラーと聞いて、最初は車？と思ってました🚘~~

対象読者としては「Cloudflare Workersって何？」を理解している方に向けておりますので、Cloudflare Workersをそもそも知らない方は一度以下の記事を覗いてみるといいかもしれません。

前提）Wranglerとは？

Cloudflare Workersの開発、ビルド、デプロイなど、コマンドラインからWorkerを操作できるCLIツールです。これを使うだけでローカル開発とデプロイがかなり簡単になるのでWorkers開発には必須くらいです。

Wrangler, the Cloudflare Developer Platform command-line interface (CLI), allows you to manage Worker projects.

Wrangler Commands

$ wrangler helpでできることをざっと見てみます。

shell

COMMANDS
  wrangler docs [search..]        📚 Open Wrangler's command documentation in your browser

  wrangler init [name]            📥 Initialize a basic Worker
  wrangler dev [script]           👂 Start a local server for developing your Worker
  wrangler deploy [script]        🆙 Deploy a Worker to Cloudflare  [aliases: publish]
  wrangler deployments            🚢 List and view the current and past deployments for your Worker
  wrangler rollback [version-id]  🔙 Rollback a deployment for a Worker
  wrangler versions               🫧  List, view, upload and deploy Versions of your Worker to Cloudflare
  wrangler triggers               🎯 Updates the triggers of your current deployment
  wrangler delete [script]        🗑  Delete a Worker from Cloudflare
  wrangler tail [worker]          🦚 Start a log tailing session for a Worker
  wrangler secret                 🤫 Generate a secret that can be referenced in a Worker
  wrangler types [path]           📝 Generate types from bindings and module rules in configuration

  wrangler kv                     🗂️  Manage Workers KV Namespaces
  wrangler queues                 🇶  Manage Workers Queues
  wrangler r2                     📦 Manage R2 buckets & objects
  wrangler d1                     🗄  Manage Workers D1 databases
  wrangler vectorize              🧮 Manage Vectorize indexes [open beta]
  wrangler hyperdrive             🚀 Manage Hyperdrive databases
  wrangler pages                  ⚡️ Configure Cloudflare Pages
  wrangler mtls-certificate       🪪  Manage certificates used for mTLS connections
  wrangler pubsub                 📮 Manage Pub/Sub brokers [private beta]
  wrangler dispatch-namespace     🏗️  Manage dispatch namespaces
  wrangler ai                     🤖 Manage AI models
  wrangler workflows              🔁 Manage Workflows [open-beta]
  wrangler login                  🔓 Login to Cloudflare
  wrangler logout                 🚪 Logout from Cloudflare
  wrangler whoami                 🕵️  Retrieve your user information

  GLOBAL FLAGS
  -c, --config   Path to Wrangler configuration file  [string]
  -e, --env      Environment to use for operations and .env files  [string]
  -h, --help     Show help  [boolean]
  -v, --version  Show version number  [boolean]

よく使う系のコマンドは以下になります。

wrangler dev
- ローカルサーバーを立ち上げる
wrangler deploy
- Cloudflare Workerにデプロイ
wrangler delete
- Cloudflare WorkerやWorkerが持っている設定情報（環境変数など）を削除
wrangler login
- 登録しているCloudflareアカウントにログイン（OAuthトークンの作成）
wrangler logout
- Wranglerで使用していたCloudflareアカウントからログアウト（OAuthトークンの削除）
wrangler whoami
- ログインしているアカウント情報の確認
wrangler secret
- Worker内で使用する環境変数周りの操作
- アップロード、確認など

本題）wrangler.tomlとは？

上記で説明したWranglerですが、Wranglerはオプションでwrangler.tomlというファイルを使ってWorkerの開発・デプロイ設定をカスタマイズすることができます。
環境設定をソースコード管理できるとチーム開発の際にも便利なのと、環境ごとの設定も書けるので諸々と融通が効きます。

ちなみに、TOMLは設定ファイルを記述するフォーマットの一種なので、記法は以下の資料などを参考にしてみてください。

wrangler.toml内を見てみる

wrangler.toml内では以下のように設定ができます。

wrangler.toml

name = "worker_name" ## Workerの名前
main = "src/index.js" ## Workerが実行するメインのjsファイル
compatibility_date = "2024-12-24" ## 互換性の日付
account_id = "000000000000" ## Wranglerで連携しているCloudflareのアカウントID
route = "example.com/*" ## Workerアクセスドメイン

# カスタムビルド設定
[build]
command = "make build"

# 環境変数(機密性が低いもの)
[vars]
API_ENDPOINT = "https://example.com/*****"
API_KEY = "*******"

# ログ設定
[observability]
enabled = true
head_sampling_rate = 0.1 # 10%のログを記録する

# CRON設定
[triggers]
crons = ["* * * * *"]

# R2バケット連携設定
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "r2_sample_bucket"

補足: Bindings

Worker内で他のCloudflareサービスと連携したいときには、Bindingを設定するだけで簡単にできます。先ほどの例のコードにもR2バケットとのバインディングを記載をしておりますが、

wrangler.toml

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "r2_sample_bucket"

このように設定するだけで、Worker内からMY_BUCKETという名称を使用して、r2_sample_bucketの操作をできるようになってます。

Worker内のコードを見るとイメージしやすいと思うので、以下に載せておきます。（処理としては、オブジェクトをバインディングしたR2に保存しています）

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const key = url.pathname.slice(1);

    switch (request.method) {
      case "PUT":
        await env.MY_BUCKET.put(key, request.body);
        return new Response(`Put ${key} successfully!`);

      default:
        return new Response(`${request.method} is not allowed.`, {
          status: 405,
          headers: {
            Allow: "PUT",
          },
        });
    }
  },
};

補足: Compatibility Dates

Compatibility Datesを指定すると、Workerのランタイムを指定することができ、後方互換への対策をすることができます。

wrangler.toml

compatibility_date = "2024-12-24"

Workerのランタイムは、指定したCompatibiliti Datesの日付になるので、最新の修正を適用を適切なタイミングで行えたり、柔軟な対応が可能になります。
プロジェクトの開始タイミングには必ず現在の日付を設定する必要があります。

wrangler.tomlを触る際の注意点

Source of truth

設定ファイル触ったり、IaCなどを使用している方は馴染みがあるかもしれませんが、wrangler.tomlもSource of truth（信頼できる情報源）であることが推奨されています。
Worker上のコンソールからポチポチ設定を変えると設定ファイルと差分が出てしまい、設定ファイルの信頼できなくなってくるので、Workerの設定を変えたい時は必ずwrangler.tomlから触るようにしましょう。

We recommend treating your Wrangler configuration file as the source of truth for your Worker configuration, and to avoid making changes to your Worker via the Cloudflare dashboard if you are using Wrangler.

もしコンソールから変える必要がある時は、設定情報をコンソールからコピーして、設定ファイルと差分がない状態にする。

If you need to make changes to your Worker from the Cloudflare dashboard, the dashboard will generate a TOML snippet for you to copy into your Wrangler configuration file, which will help ensure your Wrangler configuration file is always up to date.

セキュアな情報はwrangler.tomlに直接書かない

セキュアな情報を扱うときにも注意が必要です。

wrangler.tomlに環境変数など、漏洩してはいけない情報を書くのではなく、プロジェクトのルートに.dev.varsファイルを作成して、そこにSecretsを定義していくことが推奨されています。

When developing your Worker or Pages Function, create a .dev.vars file in the root of your project to define secrets that will be used when running wrangler dev or wrangler pages dev, as opposed to using environment variables in wrangler.toml. This works both in local and remote development modes.

環境が複数ある場合は、.dev.vars.<environment-name>のようにして環境を分ける。

/
├─ .dev.vars.stg // staging環境用の環境変数
├─ .dev.vars.prd // 本番環境用の環境変数
├─ wrangler.toml
├─ .gitignore // .dev.vars.*を除外
└─ ...

記述方法は、よくあるKEY="VALUE"のような形で書けばokです。

.dev.vars

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

また、wrangler secret put <KEY>のような形で、wrangler cliから直接Workerのコンソール上に環境変数を作成することも可能です。ですが、.dev.varsが存在する場合は、.dev.varsを優先してWorkerのSecretに登録をする仕様なので注意が必要そうです。

環境ごとのデプロイ管理

実際に開発を進めていくときに本番環境と開発環境用でWorkerをデプロイしたいことは往々にしてあると思います。そのような場合はデプロイ時に--envフラグを使用します。

shell

# dev環境のWorkerにデプロイ
$ wrangler deploy --env development

すると、自動でWorkerのnameのpreffixに--envで指定した環境名が付いた状態のWorkerが作成されます。
development環境で独自の設定などを行いたい場合は、wrangler.tomlで[env.<env_name>]で設定を書くとdeploy時に自動で反映をしてくれます。

wrangler.toml

name = "my-worker"
main = "src/index.js"
compatibility_date = "2022-07-12"

[env.development]
name = "my-worker-development"
route = { pattern = "development.example.org/*", zone_name = "example.org" }

kv_namespaces = [
  { binding = "<MY_NAMESPACE>", id = "<DEVELOPMENT_KV_ID>" }
]

WorkerってJavaScriptで書かないといけないの？

WorkerはそもそもJavascriptのランタイム環境なのでJavaScriptで書かないといけないと思いがちですが、他の言語でも書くことは可能です。
本記事執筆時点（2024年12月）でサポートされている言語は以下になります。

Javascript
TypeScript
Python
Rust

また、WebAssemblyもサポートしているので、WebAssemblyにコンパイルできるC、C++、Kotlin、Goを始め様々な言語で書くことができます。

最後に

最近の業務でWokerを使用していることもあり、今回のタイミングで設定周りの情報をキャッチアップして記事を書くことにしました。現在は@__syumaiさんが作成したライブラリを使用して、GoでWorkerを開発をしております。

自分自身もまだまだCloudflare Workersについて知らないこともたくさんありますのでこれからもっとキャッチアップしていく予定です。
本記事に関しても修正点や指摘箇所などあればコメントなどしていただけると助かります！

記事の概要

前提）Wranglerとは？

Wrangler Commands

本題）wrangler.tomlとは？

wrangler.toml内を見てみる

補足: Bindings

補足: Compatibility Dates

wrangler.tomlを触る際の注意点

Source of truth

セキュアな情報はwrangler.tomlに直接書かない

環境ごとのデプロイ管理

WorkerってJavaScriptで書かないといけないの？

最後に

Discussion