mcpField
S
skaffold-standards

skaffold-standards

github.com/laurigates云与 DevOps5961 次安装1 天前更新
代码仓库

关于 skaffold-standards

skaffold-standards 是面向 OrbStack 和 dotenvx 本地 Kubernetes 开发的 Skaffold 配置参考技能，供开发者核对配置约定，并查阅标准配置档案与安全要求。

主要功能

  1. 01Skaffold API 版本指引
  2. 02OrbStack 部署上下文规则
  3. 03仅绑定本机的端口转发
  4. 04标准开发与测试配置档案
  5. 05dotenvx 密钥生成钩子

适用场景

  1. 01检查 Skaffold 配置约定
  2. 02设置仅含数据库的本地开发
  3. 03准备全栈端到端测试

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/laurigates/claude-plugins --skill skaffold-standards

安装后在 Claude Code 中输入/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，也不要省略 address 字段。

部署配置
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.kubeContextorbstack（默认）
local.pushfalse
portForward.address127.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存在安全问题（例如，portForward 未绑定到本地主机）
SKIP不适用（例如，基础设施仓库）

故障排除

Pod 未启动
  • 检查 statusCheckDeadlineSeconds（必要时调大）
  • 启用 tolerateFailuresUntilDeadline: true
  • 查看 Pod 日志：kubectl logs -f <pod>
端口转发问题
  • 确保端口未被占用
  • 检查服务名称是否与部署匹配
  • 确认已设置 address: 127.0.0.1
构建缓存
  • 启用 BuildKit：useBuildkit: true
  • 使用 Docker CLI：useDockerCLI: true
  • 设置 concurrency: 0 以并行构建

评论

支持 Markdown