AppSync カスタムドメイン証明書に DnsValidatedCertificate を継続使用する決定

[takaokouji]

Context and Problem Statement - コンテキストと問題の説明

PR #39 でコミット 6b4652b において、DnsValidatedCertificate から Certificate に変更したところ、AppSync のデプロイ時に「Certificate must be in us-east-1」エラーが発生した。

AppSync カスタムドメインは CloudFront を使用するため、証明書は必ず us-east-1 リージョンに存在する必要がある。一方、CDK の Certificate construct には region パラメータがなく、スタックのリージョン（ap-northeast-1）で証明書を作成してしまう。

DnsValidatedCertificate は非推奨（deprecated）だが、クロスリージョン証明書を作成できる唯一の手段である。非推奨の construct を継続使用すべきか、それとも別の方法を採用すべきか？

See: smalruby/mesh-v2#39 (comment)

Decision Date - 決定日付

2026/01/10

Decision Makers - 意思決定者

@takaokouji

Decision Drivers - 決定要因

• AppSync カスタムドメインには us-east-1 の証明書が必須
• CDK の Certificate construct にはクロスリージョン対応がない
• DnsValidatedCertificate の代替手段が AWS から提供されていない
• シンプルで実用的な解決策が必要

Considered Options - 検討した選択肢

• オプション1: DnsValidatedCertificate を継続使用
• オプション2: 別スタック作成 + crossRegionReferences を使用
• オプション3: Certificate construct を使用（証明書を手動で us-east-1 に作成）

Decision - 決定

内容

• DnsValidatedCertificate を継続使用する
• コミット 6b4652b の変更を元に戻す
• tsconfig.json の isolatedModules: true は維持する（ts-jest の警告対応として正しい）

理由

• AppSync カスタムドメインには us-east-1 の証明書が必須
• Certificate construct にはクロスリージョン対応がない
• DnsValidatedCertificate は非推奨だが、代替手段が提供されていない
• CDK v3 のリリース予定はまだなく、当分使用可能
• AWS 公式も「当分使用可能」としている
• 最もシンプルで実用的な解決策

Consequences - 結果

• Good
  • AppSync カスタムドメインが正常にデプロイできる
  • 既存の証明書を削除せずに継続使用できる
  • コードがシンプルで保守しやすい
• Bad
  • 非推奨の construct を使用するため、将来的に移行が必要になる可能性がある
  • npm test で非推奨警告が表示される（ただし、CDK には特定の非推奨警告を抑制する機能がない）

Confirmation - 確認

• PR #39 のコメントに調査結果を記載
• ADR として記録
• コードを DnsValidatedCertificate に戻す修正を実装

Pros and Cons of the Options - 選択肢の長所と短所

オプション1: DnsValidatedCertificate を継続使用

説明: コミット 6b4652b の変更を元に戻し、DnsValidatedCertificate を使用

• Good
  • 最もシンプルで実用的
  • 既存の証明書を継続使用できる
  • コードの変更が最小限
  • AWS 公式も「当分使用可能」としている
• Bad
  • 非推奨警告が表示される（抑制できない）
  • 将来的に移行が必要になる可能性がある

オプション2: 別スタック作成 + crossRegionReferences

説明: us-east-1 専用のスタックを作成し、証明書を管理

• Good
  • 非推奨の construct を使用しない
  • 将来的な移行リスクがない
• Bad
  • オーバースペック（小規模プロジェクトには複雑すぎる）
  • スタック管理の複雑性が増す
  • デプロイ時間が増加する

オプション3: Certificate を使用（手動作成）

説明: 証明書を手動で us-east-1 に作成し、ARN を参照

• Bad
  • IaC の原則に反する（手動操作が必要）
  • 証明書のライフサイクル管理が複雑になる
  • チーム間での共有が困難

More Information - 詳細情報

• AWS AppSync Custom Domain Documentation
• DnsValidatedCertificate Migration Discussion
• AWS CDK Cross-Region Certificate Discussion
• Feature Request: Suppress Specific Deprecations
• CDK v3 で代替手段が提供される予定だが、リリース時期は未定
• 非推奨警告が実際の問題になった場合、再度検討する