deploying-applications

アプリケーションのデプロイ

Kubernetes からサーバーレス、エッジ関数まで、実運用環境へのデプロイパターンを紹介します。アプリケーションの組み立てから実運用環境のインフラストラクチャまでをつなぎます。

目的

このスキルでは、次の内容について明確なガイダンスを提供します。

• 適切なデプロイ戦略（Kubernetes、サーバーレス、コンテナ、エッジ）の選択
• Pulumi または OpenTofu を使用した Infrastructure as Code の実装
• ArgoCD または Flux を使用した GitOps 自動化の設定
• サーバーレスデータベース（Neon、Turso、PlanetScale）の選択
• エッジ関数（Cloudflare Workers、Deno Deploy）のデプロイ

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• アプリケーションを実運用環境のインフラストラクチャにデプロイするとき
• CI/CD パイプラインと GitOps ワークフローを設定するとき
• Kubernetes、サーバーレス、エッジのいずれでデプロイするかを選ぶとき
• Infrastructure as Code（Pulumi、OpenTofu、SST）を実装するとき
• 手動デプロイから自動化されたインフラストラクチャに移行するとき
• 完全なデプロイフローのために assembling-components と統合するとき

デプロイ戦略の判断ツリー

WORKLOAD TYPE?

├── COMPLEX MICROSERVICES (10+ services)
│   └─ Kubernetes + ArgoCD/Flux (GitOps)
│       ├─ Helm 4.0 for packaging
│       ├─ Service mesh: Linkerd (5-10% overhead) or Istio (25-35%)
│       └─ See references/kubernetes-patterns.md

├── VARIABLE TRAFFIC / COST-SENSITIVE
│   └─ Serverless
│       ├─ Database: Neon/Turso (scale-to-zero)
│       ├─ Compute: Vercel, AWS Lambda, Cloud Functions
│       ├─ Edge: Cloudflare Workers (<5ms cold start)
│       └─ See references/serverless-dbs.md and references/edge-functions.md

├── CONSISTENT LOAD / PREDICTABLE TRAFFIC
│   └─ Containers (ECS, Cloud Run, Fly.io)
│       ├─ ECS Fargate: AWS-native, serverless containers
│       ├─ Cloud Run: GCP, scale-to-zero containers
│       └─ Fly.io: Global edge, multi-region

├── GLOBAL LOW-LATENCY (<50ms)
│   └─ Edge Functions + Edge Database
│       ├─ Cloudflare Workers + D1 (SQLite)
│       ├─ Deno Deploy + Turso (libSQL)
│       └─ See references/edge-functions.md

└── RAPID PROTOTYPING / STARTUP MVP
    └─ Managed Platform as a Service
        ├─ Vercel (Next.js, zero-config)
        ├─ Railway (any framework)
        └─ Render (auto-deploy from Git)

IaC CHOICE?

├─ TypeScript-first → Pulumi (Apache 2.0, multi-cloud)
├─ HCL-based → OpenTofu (CNCF, Terraform-compatible)
└─ Serverless TypeScript → SST v3 (built on Pulumi)

コアコンセプト

Infrastructure as Code（IaC）

手動で設定する代わりに、コードを使ってインフラストラクチャを定義します。

主な選択肢：Pulumi（TypeScript）

• Context7 ID：/pulumi/docs（信頼度：94.6/100、9,525 件のスニペット）
• TypeScript を優先（React/Next.js と同じ言語）
• マルチクラウド対応（AWS、GCP、Azure、Cloudflare）
• パターンと例については references/pulumi-guide.md を参照してください

代替：OpenTofu（HCL）

• CNCF プロジェクト、Terraform 互換
• MPL-2.0 ライセンス（オープンガバナンス）
• Terraform のドロップイン置き換え
• 移行については references/opentofu-guide.md を参照してください

サーバーレス：SST v3（TypeScript）

• Pulumi をベースに構築
• AWS Lambda、API Gateway 向けに最適化
• Lambda のライブ開発に対応

GitOps デプロイ

Git を信頼できる唯一の情報源とする、宣言的なインフラストラクチャです。

ArgoCD（プラットフォームチームに推奨）：

• 充実した Web UI
• RBAC とマルチテナンシーを標準搭載
• 自己修復型のデプロイ
• references/gitops-argocd.md を参照してください

Flux（DevOps の自動化に推奨）：

• Kubernetes ネイティブ
• CLI 中心
• よりシンプルなアーキテクチャ
• references/gitops-argocd.md を参照してください

サービスメッシュ

マイクロサービス間の通信、セキュリティ、可観測性のためのオプションレイヤーです。

サービスメッシュを使用する場合：

• 複数チームでマイクロサービスを運用する（セキュリティ境界が必要）
• ゼロトラストネットワーキング（mTLS が必要）
• 高度なトラフィック管理（カナリア、ブルーグリーン）が必要

使用しない場合：

• シンプルなモノリス、または 2～3 個のサービス（オーバーヘッドに見合わない）
• サーバーレスアーキテクチャ（互換性がない）

Linkerd（パフォーマンス重視）：

• オーバーヘッド 5～10%
• Rust ベース
• シンプルで、明確な方針を持つ

Istio（機能豊富）：

• オーバーヘッド 25～35%
• C++（Envoy）
• 高度なルーティング、可観測性

サービスメッシュのパターンについては references/kubernetes-patterns.md を参照してください。

クイックスタートワークフロー

ワークフロー 1：Next.js を Vercel にデプロイ（設定不要）

# Install Vercel CLI
npm i -g vercel

# Link project
vercel link

# Deploy to production
vercel --prod

完全な例については examples/nextjs-vercel/ を参照してください。

ワークフロー 2：ArgoCD を使用して Kubernetes にデプロイ

1. Helm チャートを作成する
2. チャートを Git リポジトリにプッシュする
3. ArgoCD Application を作成する
4. ArgoCD が自動的に同期する

GitOps の完全な設定については examples/k8s-argocd/ を参照してください。

ワークフロー 3：Pulumi を使用してサーバーレス環境にデプロイ

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

// Create Lambda function
const lambda = new aws.lambda.Function("api", {
    runtime: "nodejs20.x",
    handler: "index.handler",
    role: role.arn,
    code: new pulumi.asset.FileArchive("./dist"),
});

export const apiUrl = lambda.invokeArn;

パターンについては examples/pulumi-aws/ と references/pulumi-guide.md を参照してください。

ワークフロー 4：Cloudflare Workers にエッジ関数をデプロイ

import { Hono } from 'hono'

const app = new Hono()

app.get('/api/hello', (c) => {
  return c.json({ message: 'Hello from edge!' })
})

export default app

Wrangler でデプロイします：

wrangler deploy

examples/cloudflare-workers-hono/ と references/edge-functions.md を参照してください。

assembling-components との統合

assembling-components でアプリケーションを構築した後、このスキルではデプロイパターンを提供します。

フロントエンド（Next.js/Vite）→ デプロイ：

1. デプロイの意思決定ツリーを確認します
2. プラットフォームを選択します：Vercel（Next.js）、Cloudflare Pages（静的サイト）、またはカスタム（Pulumi）
3. 環境変数を設定します
4. 選択した方法でデプロイします

バックエンド（FastAPI/Axum）→ デプロイ：

1. アプリケーションをコンテナ化します（Dockerfile）
2. プラットフォームを選択します：ECS Fargate、Cloud Run、または Kubernetes
3. IaC を設定します（Pulumi または OpenTofu）
4. GitOps（ArgoCD/Flux）または CI/CD でデプロイします

統合例については references/pulumi-guide.md を参照してください。

リファレンスファイル

Kubernetes のデプロイ

• references/kubernetes-patterns.md - Helm 4.0、サービスメッシュ、自動スケーリング
• references/gitops-argocd.md - ArgoCD/Flux の GitOps ワークフロー

サーバーレスとエッジ

• references/serverless-dbs.md - Neon、Turso、PlanetScale（ゼロまでスケール）
• references/edge-functions.md - Cloudflare Workers、Deno Deploy（コールドスタート 5ms 未満）

Infrastructure as Code

• references/pulumi-guide.md - Pulumi の TypeScript パターン、コンポーネントモデル
• references/opentofu-guide.md - OpenTofu/Terraform の移行

ユーティリティスクリプト

scripts/ 内のスクリプトは、コンテキストに読み込まずに実行されます（トークンを消費しません）。

Kubernetes マニフェストの生成：

python scripts/generate_k8s_manifests.py --app-name my-app --replicas 3

デプロイ設定の検証：

python scripts/validate_deployment.py --config deployment.yaml

使用方法の詳細は、各スクリプトファイルを参照してください。

例

examples/ には、完全に実行可能な例があります。

• pulumi-aws/ - Pulumi を使用した ECS Fargate のデプロイ
• k8s-argocd/ - Kubernetes + ArgoCD の GitOps
• sst-serverless/ - SST v3 のサーバーレス TypeScript

各例には以下が含まれます。

• セットアップ手順を記載した README.md
• 完全なソースコード
• 環境変数の設定
• デプロイコマンド

ライブラリの推奨事項

Infrastructure as Code（2025）

第一候補：Pulumi

• Context7：/pulumi/docs（信頼度：94.6、9,525 件のスニペット）
• TypeScript を優先し、マルチクラウドに対応
• Apache 2.0 ライセンス

代替：OpenTofu

• CNCF プロジェクト、MPL-2.0
• Terraform 互換
• HCL 構文

サーバーレス：SST v3

• Pulumi を基盤として構築
• AWS Lambda に最適化
• TypeScript ネイティブ

サーバーレスデータベース

Neon PostgreSQL：

• データベースのブランチ作成（Git のような仕組み）
• コンピューティングをゼロまでスケール
• PostgreSQL と完全互換

Turso SQLite：

• エッジデプロイ（200 か所以上）
• 1 ミリ秒未満の読み取り
• libSQL（SQLite のフォーク）

PlanetScale MySQL：

• ノンブロッキングのスキーマ変更
• Vitess を採用
• 行単位の料金設定

比較と統合については references/serverless-dbs.md を参照してください。

エッジ関数

Cloudflare Workers：

• コールドスタート 5ms 未満（V8 アイソレート）
• 200 か所以上のエッジロケーション
• リクエストごとに 128MB のメモリ

Deno Deploy：

• TypeScript ネイティブ
• Web 標準 API
• グローバルエッジ（50ms 未満）

Hono フレームワーク：

• すべてのエッジランタイムで動作
• バンドルサイズ 14KB
• TypeScript を優先

パターンについては references/edge-functions.md を参照してください。

ベストプラクティス

セキュリティ

• シークレット管理を使用します（AWS Secrets Manager、Vault）
• サービス間通信で mTLS を有効にします
• 最小権限の IAM ロールを実装します
• コンテナイメージの脆弱性をスキャンします

コストの最適化

• トラフィックが変動する場合はサーバーレスデータベースを使用します（ゼロまでスケール）
• Kubernetes で水平ポッド自動スケーリング（HPA）を有効にします
• コンピューティングリソース（CPU/メモリ）を適正化します
• 重要度の低いワークロードにはスポットインスタンスを使用します

パフォーマンス

• ユーザーの近くにデプロイします（グローバルアプリにはエッジ関数を使用）
• 静的アセットには CDN を使用します（CloudFront、Cloudflare）
• キャッシュ戦略を実装します（Redis、CloudFront）
• サーバーレスのコールドスタート時間を監視します

信頼性

• ヘルスチェックを実装します（Kubernetes の liveness/readiness プローブ）
• オートスケーリングを設定します（HPA、Lambda の同時実行数）
• 重要なサービスではマルチリージョンデプロイを使用します
• サーキットブレーカーとリトライを実装します

トラブルシューティング

デプロイ時の障害

Kubernetes ポッドが起動しない場合：

1. ポッドのログを確認します：kubectl logs <pod-name>
2. ポッドの詳細を表示します：kubectl describe pod <pod-name>
3. リソースの制限とリクエストを確認します
4. イメージのプルエラーを確認します（imagePullSecrets）

サーバーレスのコールドスタートが遅すぎる場合：

1. バンドルサイズを削減します（ツリーシェイキング、コード分割）
2. プロビジョニング済み同時実行を使用します（AWS Lambda）
3. エッジ関数を検討します（Cloudflare Workers）
4. 初期化コードを最適化します

GitOps の同期エラー（ArgoCD/Flux）：

1. Git リポジトリへのアクセスを確認します
2. マニフェストの有効性を確認します（kubectl apply --dry-run）
3. 同期ポリシーを確認します（prune、selfHeal）
4. ArgoCD/Flux のログを確認します

パフォーマンスの問題

サービスメッシュのオーバーヘッドが大きい場合：

1. Linkerd への切り替えを検討します（Istio の 25～35% に対し 5～10%）
2. 不要な機能を無効にします
3. サービスメッシュが必要かどうかを評価します

データベースの接続プールが枯渇した場合：

1. 接続プールのサイズを大きくします
2. サーバーレスデータベースを使用します（Neon scale-to-zero）
3. 接続プーリングを実装します（PgBouncer）

詳細なトラブルシューティングガイドについては、references/ ファイルを参照してください。

移行パターン

手動管理から IaC へ

1. 既存のインフラストラクチャを棚卸しします
2. 重要度の低い環境（dev、staging）から始めます
3. Pulumi/OpenTofu を使用してインフラストラクチャをコード化します
4. 本番環境の前に staging でテストします
5. 段階的に移行します（一度に 1 つのサービス）

Terraform から OpenTofu へ

# Install OpenTofu
brew install opentofu

# Migrate state
terraform state pull > terraform.tfstate.backup
tofu init -migrate-state
tofu plan
tofu apply

移行の全手順については、references/opentofu-guide.md を参照してください。

EC2 からコンテナへ

1. アプリケーションをコンテナ化します（Dockerfile を作成）
2. ローカルでテストします（Docker Compose）
3. staging にデプロイします（ECS/Cloud Run/Kubernetes）
4. パフォーマンスとコストを監視します
5. 本番トラフィックを切り替えます（ブルーグリーンデプロイ）

コンテナからサーバーレスへ

1. ステートレスなサービスを特定します
2. サーバーレスに適したパターンにリファクタリングします
3. サーバーレスデータベースを使用します（Neon/Turso）
4. Lambda/Cloud Functions にデプロイします
5. コールドスタートとコストを監視します

次のステップ

アプリケーションをデプロイした後：

• オブザーバビリティを設定します（メトリクス、ログ、トレース）
• CI/CD パイプラインを実装します（GitHub Actions、GitLab CI）
• 自動スケーリングとリソース制限を設定します
• 災害復旧とバックアップを設定します
• インシデント対応のためのランブックを文書化します

追加リソース

• Pulumi のドキュメント：https://www.pulumi.com/docs/
• OpenTofu のドキュメント：https://opentofu.org/docs/
• ArgoCD のドキュメント：https://argo-cd.readthedocs.io/
• Cloudflare Workers のドキュメント：https://developers.cloudflare.com/workers/
• Neon のドキュメント：https://neon.tech/docs/