Contents
TraefikでLet's Encrypt自動更新を導入する意義と前提条件
Docker Compose環境においてSSL証明書の管理は、運用コストとセキュリティリスクの両面で重要な課題です。Traefikの自動更新機能を活用することで、手動での証明書交換やエラー対応を削減し、運用負荷を軽減できます。特にLet's Encryptの無料証明書は90日有効なため、定期的な更新が必須です。本記事では、Traefik v3.xに対応したDocker Composeでの実装手順を解説します。
Docker Compose環境におけるSSL管理の課題
Docker Composeで複数サービスを運用する際、各コンテナに個別にSSL証明書を設定すると、管理が煩雑になります。また、証明書の有効期限切れによるダウンタイムリスクも高まります。TraefikのACME機能は、これらの課題を自動化し、運用効率を向上させます。
v3.x版対応の最新設定フロー概観
Traefik v3.xでは、コンフィグ構造が階層的に変更されており、証明書リゾルバーやルーティングルールの定義方法に注意が必要です。以下に示す手順を基に、最新版に対応した設定ファイルを作成します。
ACMEプロトコルの技術的背景
ACME（Automatic Certificate Management Environment）は、Let's Encryptが提供する証明書自動発行プロトコルです。Traefikはこのプロトコルを介してドメイン検証を行い、証明書を取得・更新します。DNS-01チャレンジでは、トラフィックレコーダーによりDNSレコードを作成し、所有権を確認します。
certificatesResolversの定義とACMEチャレンジ設定
TraefikでLet's Encrypt証明書を自動取得するには、certificatesResolversを正しく定義することが不可欠です。ここではDNS-01チャレンジに必要な環境変数や、エラー回避策について解説します。
Let's Encryptプロバイダとの接続設定
TraefikはACMEプロトコルを通じてLet's Encryptと通信します。証明書リゾルバーを定義する際には、acmeプロバイダを指定し、emailやstorageといった必要パラメータを記述します。
- メールアドレス：失効や再発行時の通知を受け取るための必須項目
- ストレージパス：証明書情報を保存するローカルファイルの指定（例:
/etc/traefik/acme.json）
|
1 2 3 4 5 6 7 |
certificatesResolvers: letsencrypt: acme: email: [メールアドレス削除] storage: /etc/traefik/acme.json caServer: https://acme-staging-v02.api.letsencrypt.org/directory |
注意：本番環境では
caServerをhttps://acme-v02.api.letsencrypt.org/directoryに変更してください。
DNS-01チャレンジ用の環境変数定義
DNS-01チャレンジでは、TraefikがDNSレコードを作成・削除するために、プロバイダの資格情報を環境変数として設定します。CloudflareやRoute53などに対応したリゾルバを使用する場合、以下のように指定します。
|
1 2 3 4 5 6 7 8 9 10 |
certificatesResolvers: letsencrypt: acme: ... dnsChallenge: provider: cloudflare resolvers: - 1.1.1.1:53 - 8.8.8.8:53 |
- provider: DNSプロバイダを指定（
cloudflare,route53など） - resolvers: DNSクエリを行うDNSサーバーのIPアドレスとポート
トラブルシューティング：DNSレコード作成に失敗する場合は、
traefik.acme.dnschallenge.resolversを複数指定し、冗長性を確保しましょう。
Docker ComposeでのTraefik設定ファイル構築例
サービス定義におけるtraefik.http.routersの記述
Docker ComposeでTraefikを起動する際、証明書自動更新を有効化するにはlabelsにtraefik.http.routers.*.tls.certresolverを設定します。以下はシンプルなサービス定義例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
services: traefik: image: traefik:v3.10.2 ports: - "80:80" - "443:443" volumes: - ./acme:/etc/traefik/acme - /var/run/docker.sock:/var/run/docker.sock labels: - "traefik.http.routers.dashboard.rule=Host(`dashboard.example.com`)" - "traefik.http.routers.dashboard.entrypoints=websecure" - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt" |
ポイント：v3.xではCLI引数の使用が非推奨なため、YAML内の
labelsで定義してください。
v3系とv2系のYAML構文差異比較
| 項目 | v2.x（古） | v3.x（新） | 補足 |
|---|---|---|---|
| サービス定義 | labelsで直接設定 |
labelsにルールを記載 |
CLI引数の使用が非推奨に |
| 証明書リゾルバー | certificatesResolversの直下に定義 |
labelsで指定 |
設定構造が階層的に変更 |
| TLS設定 | tls: { certResolver: "letsencrypt" } |
labelsでtraefik.http.routers.*.tls.certresolverを指定 |
v3.xではルーティングルールに直接記載 |
| ルート定義 | ルーティングルールの記述方法が異なる | rule=Host()による明示的定義 |
新規サービス追加時にも反映される |
補足：v2.xとv3.xでは、Traefikのコンフィグ構造が大きく異なるため、古い設定ファイルを再利用する場合は構文変更が必要です。
自動更新ポリシーのベストプラクティス
レプリケーション制御と失敗時の再試行戦略
証明書取得や更新に失敗した場合、Traefikは自動で再試行を行います。しかし、本番環境では失敗時のロギングや再試行回数を制限することが推奨されます。
- 自動再試行の上限：
--certificatesresolvers.letsencrypt.acme.retryBackoffで指定可能 - 証明書有効期限監視：Traefikのデフォルトでは証明書更新が90日前に開始されるため、有効期間を15日以上余裕を持たせることが重要
証明書有効期限の監視・通知設定
証明書の有効期限を事前に把握するには、Traefikの内部メトリクスや外部ツール（例: Prometheus + Grafana）と連携することが効果的です。また、Let's Encryptの--acme.acmeChallenge.timeoutパラメータでチャレンジ失敗時のタイムアウトを調整できます。
v3.x版での設定変更点と移行ガイド
コンフィグ構造の階層変更影響
Traefik v3.xでは、以前のようにYAMLファイル内に証明書リゾルバを定義する代わりに、labelsで直接指定する方式が採用されています。これにより、複数コンテナ環境での運用がシンプルになりました。
ACLやルール定義の書き換え要件
v3.xでは、traefik.http.middlewaresやtraefik.http.routersの構文に変更があります。例えば、ACL（アクセス制御リスト）は--providers.fileまたは.tomlファイルで定義されるようになりました。
例：
|
1 2 3 4 |
labels: - "traefik.http.middlewares.auth.basicauth.users=admin:$$2y$$05$$X7Y9UJg4QvKtRj1V8xL6qOZz1pIe7GkM9B8WnD3T" - "traefik.http.routers.myapp.middlewares=auth@file" |
実装後の検証手順と運用時の注意点
自動更新テストのための仮想ドメイン設定
本番環境導入前に、テスト用ドメインを用意し、自動更新が正しく動作することを確認しましょう。以下のような手順でテストできます。
- DNSレコード作成：
test.example.comを仮想ドメインとして準備し、AレコードやCNAMEレコードを設定 - Traefikコンテナ起動：設定ファイルに該当ドメインを記載し、
docker-compose up -d --buildで起動 - 証明書確認：
curl -v https://test.example.comでSSL証明書が正しく取得されているか確認
DNSレコード例（Cloudflare向け）
|
1 2 3 |
A Record: test.example.com → 192.0.2.1 (IPv4アドレス) TXT Record: _acme-challenge.test.example.com → ランダム文字列 (Traefikが自動生成) |
ロギングレベル調整による問題特定
Traefikのデフォルトロギングは簡易情報ですが、問題発生時のトラブルシューティングには詳細なログが必要です。以下のように--log.level=DEBUGを設定することで、証明書取得プロセスの詳細情報を出力できます。
|
1 2 3 4 5 6 |
labels: - "traefik.http.routers.dashboard.rule=Host(`dashboard.example.com`)" - "traefik.http.routers.dashboard.entrypoints=websecure" - "traefik.http.routers.dashboard.tls.certresolver=letsencrypt" - "traefik.log.level=DEBUG" |
補足：デバッグログは本番環境では無効にしてください。運用時はINFOレベルに設定することを推奨します。
実装の完了確認手順
以下のステップで自動更新が正しく動作しているか検証してください。
- 証明書取得状況の確認：
docker volume inspect traefik_acmeでJSONファイルに証明書情報が保存されていることを確認 - ドメインへのアクセステスト：ブラウザやcurlからHTTPS通信を試し、SSL証明書の有効性を確認
- 更新動作の検証：証明書の有効期限を手動で短く設定し（例: 1日）、Traefikが自動で再取得することを確認
環境変数の管理とセキュリティ対策
DNSプロバイダやメールアドレスなどは.envファイルで一括管理し、漏洩リスクを抑えると良いです。
例: .envファイル
|
1 2 3 |
LETS_ENCRYPT_EMAIL=[メールアドレス削除] CLOUDFLARE_API_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
定期的なセキュリティチェック
TraefikのバージョンアップやACMEプロトコルの変更に合わせて、設定ファイルを確認してください。また、証明書の再発行時に新しいCAサーバーを指定することも検討してください。