Configure Skaffold

/configure:skaffold

Check and configure Skaffold against project standards.

When to Use This Skill

Context

• K8s/Helm directories: !find . -maxdepth 1 -type d \( -name 'k8s' -o -name 'helm' \)
• Skaffold config: !find . -maxdepth 1 -name \'skaffold.yaml\'
• Skaffold API version: !grep -m1 apiVersion skaffold.yaml
• Port forward config: !grep -m1 address skaffold.yaml
• Profiles defined: !grep -m10 'name:' skaffold.yaml
• Generate-secrets script: !find . -maxdepth 1 -name \'scripts/generate-secrets.sh\'
• Dotenvx available: !command -v dotenvx
• Project standards: !find . -maxdepth 1 -name '.project-standards.yaml' -type f

Skills referenced: skaffold-standards, container-development, skaffold-orbstack

Applicability: Only for projects with Kubernetes deployment (k8s/, helm/ directories)

Parameters

Parse these from $ARGUMENTS:

Version Checking

CRITICAL: Before configuring Skaffold, verify latest versions:

1. Skaffold: Check skaffold.dev or GitHub releases 2. API version: Current recommended is skaffold/v4beta13 3. dotenvx: Check dotenvx.com for latest patterns

Use WebSearch or WebFetch to verify current Skaffold version and API version.

Execution

Execute this Skaffold compliance check:

Step 1: Check applicability

Check for k8s/ or helm/ directories. If neither is found, report "SKIP: Skaffold not applicable (no Kubernetes manifests)" and stop. If found, proceed to check for skaffold.yaml.

Step 2: Parse configuration

Read skaffold.yaml and extract:

• API version
• Build configuration (local.push, useBuildkit)
• Deploy configuration (kubeContext, statusCheck)
• Port forwarding (addresses)
• Profiles defined
• Hooks (dotenvx integration)

Step 3: Analyze compliance

Check each setting against these standards:

Security-critical: Port forwarding MUST bind to localhost only (127.0.0.1). Never allow 0.0.0.0 or missing address.

Recommended settings:

• db-only or services-only profile for local dev workflow
• statusCheck: true with reasonable deadline (180s for init containers)
• tolerateFailuresUntilDeadline: true for graceful pod initialization
• JSON log parsing for structured application logs
• dotenvx hooks for secrets generation from .env files

Step 4: Report results

Print a compliance report with:

• Skaffold file location and API version
• Each configuration check result (PASS/WARN/FAIL)
• Profiles found
• Scripts status (generate-secrets.sh)
• Overall compliance status

If --check-only, stop here.

Step 5: Apply fixes (if --fix or user confirms)

1. Missing skaffold.yaml: Create from standard template in REFERENCE.md 2. Security issues: Fix port forwarding addresses to 127.0.0.1 3. Missing profiles: Add db-only profile template 4. Outdated API: Update apiVersion to v4beta13 5. Missing dotenvx hooks: Add secrets generation hook 6. Missing scripts: Create scripts/generate-secrets.sh from template in REFERENCE.md 7. Missing kubeContext: Add orbstack for local development

Step 6: Update standards tracking

Update .project-standards.yaml:

components:
  skaffold: "2025.1"

Agentic Optimizations

Security Note

Port forwarding without address: 127.0.0.1 exposes services to the network. This is a FAIL condition that should always be fixed.

For the standard Skaffold template, dotenvx integration patterns, and generate-secrets script template, see REFERENCE.md.

See Also

• /configure:dockerfile - Container configuration
• /configure:all - Run all compliance checks
• skaffold-standards skill - Skaffold patterns

Skaffold Configuration Reference

Report Template

Skaffold Compliance Report
==============================
Project Type: <type> (detected)
Skaffold: ./skaffold.yaml (found/missing)

Configuration Checks:
  API version     <version>         PASS/WARN
  local.push      <value>           PASS/FAIL
  useBuildkit     <value>           PASS/WARN
  Port security   <address>         PASS/FAIL
  statusCheck     <value>           PASS/WARN
  kubeContext     <value>           PASS/INFO
  dotenvx hooks   <status>          PASS/INFO
  JSON log parse  <status>          PASS/INFO

Profiles Found:
  db-only         Present/Missing
  services-only   Present/Missing
  minimal         Present/Missing

Scripts:
  generate-secrets.sh  Present/Missing

Overall: <status>

Standard Skaffold Template

apiVersion: skaffold/v4beta13
kind: Config
metadata:
  name: project-name-local

build:
  local:
    push: false
    useDockerCLI: true
    useBuildkit: true
    concurrency: 0
  # Generate secrets before building
  hooks:
    before:
      - command: ['sh', '-c', 'dotenvx run -- sh scripts/generate-secrets.sh']
        os: [darwin, linux]
  artifacts:
    - image: app
      context: .
      docker:
        dockerfile: Dockerfile
    # Optional: init container for database migrations
    - image: app-db-init
      context: .
      docker:
        dockerfile: Dockerfile.db-init

manifests:
  rawYaml:
    - k8s/namespace.yaml
    - k8s/postgresql-secret.yaml
    - k8s/postgresql-configmap.yaml
    - k8s/postgresql-service.yaml
    - k8s/postgresql-statefulset.yaml
    - k8s/app-secrets.yaml
    - k8s/app-deployment.yaml
    - k8s/app-service.yaml

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

portForward:
  - resourceType: service
    resourceName: postgresql
    namespace: project-name
    port: 5432
    localPort: 5435
    address: 127.0.0.1  # REQUIRED: localhost only
  - resourceType: service
    resourceName: app
    namespace: project-name
    port: 3000
    localPort: 8080
    address: 127.0.0.1  # REQUIRED: localhost only

profiles:
  # Database only - for running app dev server locally
  - name: db-only
    build:
      artifacts: []
    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: project-name
        port: 5432
        localPort: 5435
        address: 127.0.0.1

  # Minimal - without optional features
  - name: minimal
    patches:
      - op: replace
        path: /manifests/rawYaml/4
        value: k8s/postgresql-statefulset-minimal.yaml

dotenvx Integration

Projects use dotenvx for encrypted secrets management in local development.

How It Works

1. Encrypted .env files: .env files contain encrypted values 2. Private key: DOTENV_PRIVATE_KEY decrypts values at runtime 3. Hooks: Skaffold hooks run dotenvx run -- script to inject secrets 4. Generated secrets: Scripts create Kubernetes Secret manifests from .env

Generate Secrets Script Template

Create scripts/generate-secrets.sh:

#!/bin/bash
# Generate Kubernetes secrets from .env using dotenvx
# Run with: dotenvx run -- sh scripts/generate-secrets.sh

set -euo pipefail

# Validate required env vars are set (decrypted by dotenvx)
: "${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: project-name
type: Opaque
stringData:
  DATABASE_URL: "${DATABASE_URL}"
  SECRET_KEY: "${SECRET_KEY}"
EOF

echo "Generated k8s/app-secrets.yaml"

dotenvx Setup

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

# Create encrypted .env (first time)
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

Hook Placement Patterns

Build hook (runs before building images):

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

Deploy hook (runs before applying manifests):

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