skaffold-standards

Skaffold の標準

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

次の場合にこのスキルを使用します…	次の場合は代わりに configure-skaffold を使用します…
OrbStack と dotenvx を使用する Skaffold の標準的なリファレンス（apiVersion、プロファイル、ポートフォワードのルール）が必要な場合	既存の skaffold.yaml を最初から最後まで対話型ワークフローで監査または修正する場合
プロジェクトが文書化されたプロファイルとシークレットの規約に従っているかを確認する場合	ファイルを変更する前に Skaffold／Kubernetes コンテキストを実行時に検出する場合
別のスキルから標準的な構成の形式を参照する必要がある場合	ユーザーが Skaffold の構成を実際に生成または修復するよう依頼した場合

バージョン：2025.1

OrbStack と dotenvx を使用したローカル Kubernetes 開発ワークフロー向けの標準 Skaffold 構成です。

標準構成

API バージョン

apiVersion: skaffold/v4beta13
kind: Config

常に最新の安定版 API バージョンを使用してください。現在のバージョン：skaffold/v4beta13

ビルド構成

build:
  local:
    push: false           # Never push to registry for local dev
    useDockerCLI: true    # Use Docker CLI (better caching)
    useBuildkit: true     # Enable BuildKit for performance
    concurrency: 0        # Unlimited parallel builds
  # Generate secrets from encrypted .env files before building
  hooks:
    before:
      - command: ['sh', '-c', 'dotenvx run -- sh scripts/generate-secrets.sh']
        os: [darwin, linux]
  artifacts:
    - image: app-name
      context: .
      docker:
        dockerfile: Dockerfile
    # Optional: init container for database migrations
    - image: app-db-init
      context: .
      docker:
        dockerfile: Dockerfile.db-init

ポートフォワーディング（セキュリティ）

重要：バインド先は必ずローカルホストのみにしてください。

portForward:
  - resourceType: service
    resourceName: app-name
    port: 80
    localPort: 8080
    address: 127.0.0.1    # REQUIRED: Bind to localhost only

0.0.0.0 を使用したり、アドレスフィールドを省略したりしないでください。

デプロイ構成

deploy:
  kubeContext: orbstack  # OrbStack for local development
  kubectl:
    defaultNamespace: app-name
    # Optional: validation before deploy
    hooks:
      before:
        - host:
            command: ["sh", "-c", "echo 'Deploying...'"]
            os: [darwin, linux]
  statusCheck: true
  # Extended timeout for init containers (db migrations, seeding)
  statusCheckDeadlineSeconds: 180
  tolerateFailuresUntilDeadline: true
  # Parse JSON logs from applications for cleaner output
  logs:
    jsonParse:
      fields: ["message", "level", "timestamp"]

標準プロファイル

プロファイル：db-only

データベースのみ。ホットリロードを有効にして、アプリの開発サーバーをローカルで実行する場合に使用します。

profiles:
  - name: db-only
    build:
      artifacts: []  # Don't build app
    manifests:
      rawYaml:
        - k8s/namespace.yaml
        - k8s/postgresql-secret.yaml
        - k8s/postgresql-configmap.yaml
        - k8s/postgresql-service.yaml
        - k8s/postgresql-statefulset.yaml
    portForward:
      - resourceType: service
        resourceName: postgresql
        namespace: app-name
        port: 5432
        localPort: 5435
        address: 127.0.0.1

使用例：ホットリロード開発では skaffold dev -p db-only と bun run dev を実行します。

プロファイル：services-only

バックエンドサービスのみ（データベース、API）。ローカルのフロントエンド開発と組み合わせて使用します。

profiles:
  - name: services-only
    build:
      artifacts: []  # Don't build frontend
    manifests:
      rawYaml:
        - k8s/namespace.yaml
        - k8s/database/*.yaml
        - k8s/api/*.yaml
    portForward:
      - resourceType: service
        resourceName: postgresql
        port: 5432
        localPort: 5435
        address: 127.0.0.1

使用例：ホットリロードでフロントエンドを開発するには、skaffold dev -p services-only と bun run dev を実行します。

プロファイル：e2e または e2e-with-prod-data

エンドツーエンドテスト用のフルスタック構成です。

profiles:
  - name: e2e
    manifests:
      rawYaml:
        - k8s/*.yaml  # All manifests

プロファイル：migration-test

データベースのマイグレーションテスト用です。

profiles:
  - name: migration-test
    manifests:
      rawYaml:
        - k8s/database/*.yaml
    test:
      - image: migration-tester
        custom:
          - command: "run-migrations.sh"

準拠要件

クラスターコンテキスト（重大）

デプロイ構成では必ず kubeContext: orbstack を指定してください。これが標準のローカル開発コンテキストです。

deploy:
  kubeContext: orbstack
  kubectl: {}

Skaffold コマンドを実行する際は、必ず --kube-context=orbstack を含めてください。

skaffold dev --kube-context=orbstack
skaffold run --kube-context=orbstack
skaffold delete --kube-context=orbstack

別のコンテキストを使用するのは、ユーザーが明示的に依頼した場合に限ります。

必須要素

要素	要件
API バージョン	skaffold/v4beta13
deploy.kubeContext	orbstack（デフォルト）
local.push	false
portForward.address	127.0.0.1
statusCheck	true を推奨
dotenvx フック	シークレットには推奨

推奨プロファイル

プロジェクトの種類に応じて選択します。

プロファイル	用途	必須
db-only	データベースのみ＋ローカルアプリ開発	推奨
services-only	バックエンドサービス＋ローカルフロントエンド	推奨
minimal	オプション機能なし	任意
e2e	フルスタックテスト	任意

プロジェクトの種類による違い

バックエンドサービスを含むフロントエンド

# Default: Full stack
manifests:
  rawYaml:
    - k8s/namespace.yaml
    - k8s/frontend/*.yaml
    - k8s/backend/*.yaml
    - k8s/database/*.yaml

profiles:
  - name: services-only
    build:
      artifacts: []
    manifests:
      rawYaml:
        - k8s/namespace.yaml
        - k8s/backend/*.yaml
        - k8s/database/*.yaml

API サービスのみ

# Simpler configuration
manifests:
  rawYaml:
    - k8s/*.yaml

# No profiles needed for simple services

インフラストラクチャのテスト

インフラストラクチャのみのリポジトリでは、Skaffold が適さない場合があります。その場合は Terraform／Helm を直接使用してください。

dotenvx の統合

プロジェクトでは、ローカル開発時に暗号化されたシークレットを管理するために dotenvx を使用します。

仕組み

1. 暗号化された .env ファイル：.env ファイルには暗号化された値が含まれており、安全にコミットできます
2. 秘密鍵：DOTENV_PRIVATE_KEY によって実行時に値を復号します
3. フック：Skaffold フックは dotenvx run -- script を実行してシークレットを注入します
4. 生成されるシークレット：スクリプトによって .env から Kubernetes Secret マニフェストが作成されます

dotenvx を使ったビルドフック

build:
  hooks:
    before:
      - command: ['sh', '-c', 'dotenvx run -- sh scripts/generate-secrets.sh']
        os: [darwin, linux]

dotenvx を使ったデプロイフック

deploy:
  kubectl:
    hooks:
      before:
        - host:
            command: ["sh", "-c", "dotenvx run -- sh scripts/generate-secrets.sh"]

シークレット生成スクリプト

​scripts/generate-secrets.sh を作成します。

#!/bin/bash
# Generate Kubernetes secrets from .env using dotenvx
set -euo pipefail

# Validate required env vars are set
: "${DATABASE_URL:?DATABASE_URL must be set}"
: "${SECRET_KEY:?SECRET_KEY must be set}"

# Generate app secrets manifest
cat > k8s/app-secrets.yaml << EOF
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
  namespace: app-name
type: Opaque
stringData:
  DATABASE_URL: "${DATABASE_URL}"
  SECRET_KEY: "${SECRET_KEY}"
EOF

echo "Generated k8s/app-secrets.yaml"

dotenvx のセットアップ

# Install dotenvx
curl -sfS https://dotenvx.sh | sh

# Create encrypted .env
dotenvx set DATABASE_URL "postgresql://..."
dotenvx set SECRET_KEY "..."

# Encrypt existing .env
dotenvx encrypt

# Store private key securely (NOT in git)
echo "DOTENV_PRIVATE_KEY=..." >> ~/.zshrc

ビルドフック（検証）

dotenvx に加えて、ビルド前の検証フックを設定します。

build:
  artifacts:
    - image: app
      hooks:
        before:
          - command: ['bun', 'run', 'check']
            os: [darwin, linux]

ステータスレベル

ステータス	条件
PASS	構成が要件に準拠しています
WARN	設定されていますが、推奨要素が不足しています
FAIL	セキュリティ上の問題があります（例：ポートフォワーディングに localhost の指定がない）
SKIP	該当しません（例：インフラストラクチャのリポジトリ）

トラブルシューティング

Pod が起動しない

• statusCheckDeadlineSeconds を確認します（必要に応じて増やしてください）
• tolerateFailuresUntilDeadline: true を有効にします
• Pod のログを確認します：kubectl logs -f <pod>

ポートフォワーディングの問題

• ポートがすでに使用されていないことを確認します
• サービス名がデプロイメントと一致していることを確認します
• address: 127.0.0.1 が設定されていることを確認します

ビルドキャッシュ

• BuildKit を有効にします：useBuildkit: true
• Docker CLI を使用します：useDockerCLI: true
• 並列ビルドを行うには concurrency: 0 を設定します