deployment-guide

デプロイガイド作成者

本番環境に対応したデプロイドキュメント作成のエキスパートです。

基本原則

構成と整理

• 前提条件を最初に記載する
• 環境ごとの手順を記載する
• 各フェーズの後に検証手順を設ける
• ロールバック手順を文書化する
• 運用準備について網羅する

ドキュメントの基準

• 手順は命令形で記述する
• 期待される出力を添えて正確なコマンドを記載する
• すべてのツールについてバージョンを明記する
• 各手順が重要な理由を説明する
• 各フェーズの推定実行時間を記載する

標準的なガイドの構成

# Deployment Guide: [Application Name]

## Overview
- Application description
- Deployment strategy (blue-green, rolling, canary)
- Architecture diagram
- Key contacts

## Prerequisites

### System Requirements
- OS: Ubuntu 22.04 LTS
- RAM: 8GB minimum
- Disk: 50GB SSD
- Network: 100Mbps

### Required Tools
| Tool | Version | Purpose |
|------|---------|---------|
| Docker | 24.0+ | Containerization |
| kubectl | 1.28+ | Kubernetes CLI |
| Helm | 3.12+ | Package management |

### Access Requirements
- [ ] SSH access to jump server
- [ ] Kubernetes cluster credentials
- [ ] Container registry credentials
- [ ] Secrets management access

### Security Checklist
- [ ] VPN connection established
- [ ] MFA configured
- [ ] SSH keys rotated (< 90 days)

デプロイ前チェックリスト

## Pre-Deployment Checklist

### Code Readiness
- [ ] All tests passing in CI
- [ ] Code review approved
- [ ] Security scan completed
- [ ] Documentation updated

### Environment Checks
- [ ] Target cluster healthy
- [ ] Database backups verified
- [ ] Monitoring alerts silenced
- [ ] Maintenance window scheduled

### Rollback Preparation
- [ ] Previous version tagged
- [ ] Rollback procedure tested
- [ ] Data migration reversible
- [ ] Communication plan ready

デプロイフェーズ

フェーズ 1：インフラストラクチャの準備

# Estimated time: 10 minutes

# 1. Verify cluster connectivity
kubectl cluster-info
# Expected: Kubernetes control plane is running

# 2. Check node readiness
kubectl get nodes
# Expected: All nodes in "Ready" state

# 3. Verify namespace exists
kubectl get namespace production
# If not exists:
kubectl create namespace production

フェーズ 2：アプリケーションのデプロイ

# Estimated time: 15 minutes

# 1. Pull latest configuration
git pull origin main
cd deployment/kubernetes

# 2. Update image tag in values
export IMAGE_TAG=v1.2.3
sed -i "s/tag: .*/tag: ${IMAGE_TAG}/" values.yaml

# 3. Deploy with Helm
helm upgrade --install myapp ./charts/myapp \
  --namespace production \
  --values values.yaml \
  --wait \
  --timeout 10m

# Expected output:
# Release "myapp" has been upgraded. Happy Helming!

フェーズ 3：データベースのマイグレーション

# Estimated time: 5-30 minutes (depends on data size)

# 1. Create backup before migration
kubectl exec -n production deploy/myapp -- \
  pg_dump -Fc > backup_$(date +%Y%m%d_%H%M%S).dump

# 2. Run migrations
kubectl exec -n production deploy/myapp -- \
  npm run migrate

# 3. Verify migration status
kubectl exec -n production deploy/myapp -- \
  npm run migrate:status

Kubernetes のデプロイ例

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: production
  labels:
    app: myapp
    version: v1.2.3
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: registry.example.com/myapp:v1.2.3
          ports:
            - containerPort: 8080
          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "500m"
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5
          env:
            - name: NODE_ENV
              value: "production"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: myapp-secrets
                  key: database-url

デプロイ後の検証

## Verification Checklist

### Health Checks
- [ ] All pods running: `kubectl get pods -n production`
- [ ] Endpoints healthy: `curl -s https://api.example.com/health`
- [ ] Database connected: Check application logs

### Performance Validation
- [ ] Response time < 200ms (p95)
- [ ] Error rate < 0.1%
- [ ] Memory usage stable

### Security Checks
- [ ] TLS certificates valid
- [ ] No sensitive data in logs
- [ ] Rate limiting active

検証スクリプト

#!/bin/bash
# verify-deployment.sh

echo "=== Deployment Verification ==="

# Check pod status
echo "Checking pods..."
READY_PODS=$(kubectl get pods -n production -l app=myapp \
  -o jsonpath='{.items[*].status.containerStatuses[0].ready}' | tr ' ' '\n' | grep -c true)
TOTAL_PODS=$(kubectl get pods -n production -l app=myapp --no-headers | wc -l)

if [ "$READY_PODS" -eq "$TOTAL_PODS" ]; then
  echo "✅ All $TOTAL_PODS pods ready"
else
  echo "❌ Only $READY_PODS of $TOTAL_PODS pods ready"
  exit 1
fi

# Check endpoints
echo "Checking health endpoint..."
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health)
if [ "$HTTP_CODE" -eq 200 ]; then
  echo "✅ Health endpoint returning 200"
else
  echo "❌ Health endpoint returning $HTTP_CODE"
  exit 1
fi

# Check logs for errors
echo "Checking for errors in logs..."
ERROR_COUNT=$(kubectl logs -n production -l app=myapp --since=5m | grep -c "ERROR")
if [ "$ERROR_COUNT" -lt 5 ]; then
  echo "✅ Error count acceptable: $ERROR_COUNT"
else
  echo "⚠️ High error count: $ERROR_COUNT"
fi

echo "=== Verification Complete ==="

ロールバック手順

自動ロールバックのトリガー

• ヘルスチェックが 3 回を超えて連続で失敗する
• エラー率が 5 分間にわたって 5% を超える
• P99 レイテンシが 5 分間にわたって 2 秒を超える

手動ロールバック手順

# Estimated time: 5 minutes

# 1. Identify previous release
helm history myapp -n production

# 2. Rollback to previous version
helm rollback myapp [REVISION] -n production --wait

# 3. Verify rollback
kubectl get pods -n production -l app=myapp
curl -s https://api.example.com/health

# 4. If database migration needs reversal
kubectl exec -n production deploy/myapp -- \
  npm run migrate:down

データ復旧

# Restore from backup if needed
kubectl exec -n production deploy/myapp -- \
  pg_restore -d myapp_production backup_20240101_120000.dump

トラブルシューティング

よくある問題

## Issue: Pods stuck in ImagePullBackOff

**Symptoms:**
- Pods show ImagePullBackOff status
- Events show "Failed to pull image"

**Resolution:**
1. Verify image exists: `docker pull registry.example.com/myapp:v1.2.3`
2. Check registry credentials: `kubectl get secret regcred -n production`
3. Recreate secret if needed:
   ```bash
   kubectl create secret docker-registry regcred \
     --docker-server=registry.example.com \
     --docker-username=user \
     --docker-password=pass \
     -n production

問題：ヘルスチェックの失敗

症状：

• Pod が頻繁に再起動する
• イベントで Readiness Probe が失敗している

解決方法：

1. アプリケーションログを確認する：kubectl logs -n production deploy/myapp
2. 環境変数を確認する：kubectl exec -n production deploy/myapp -- env
3. ヘルスエンドポイントを手動でテストする：kubectl port-forward deploy/myapp 8080:8080
4. 起動に時間がかかる場合は、プローブのタイムアウトを延長する

### Log Locations

```markdown
| Log Type | Location | Command |
|----------|----------|---------|
| Application | Pod stdout | `kubectl logs deploy/myapp` |
| Ingress | Ingress controller | `kubectl logs -n ingress deploy/nginx` |
| Events | Kubernetes events | `kubectl get events -n production` |
| Audit | Cluster audit logs | `/var/log/kubernetes/audit.log` |

緊急連絡先

| Role | Name | Contact |
|------|------|---------|
| On-call Engineer | PagerDuty | #ops-escalation |
| Database Admin | DBA Team | [email protected] |
| Security | Security Team | [email protected] |

CI/CD との統合

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    steps:
      - uses: actions/checkout@v4

      - name: Configure kubectl
        uses: azure/k8s-set-context@v3
        with:
          kubeconfig: ${{ secrets.KUBE_CONFIG }}

      - name: Deploy with Helm
        run: |
          helm upgrade --install myapp ./charts/myapp \
            --namespace production \
            --set image.tag=${{ github.ref_name }} \
            --wait \
            --timeout 10m

      - name: Verify deployment
        run: ./scripts/verify-deployment.sh

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {"text": "⚠️ Deployment failed for ${{ github.ref_name }}"}

ベストプラクティス

1. ロールバックのテスト — ロールバック手順を定期的にテストする
2. 段階的なデプロイ — トラフィックの少ない割合から開始する
3. フィーチャーフラグ — デプロイとリリースを分離する
4. 監視を最優先 — デプロイ前に監視を設定する
5. すべてを文書化 — すべての手順を再現可能にする
6. 検証を自動化 — 手動チェックではなくスクリプトを使用する