/configure:skaffold

Check and configure Skaffold against FVH (Forum Virium Helsinki) standards.

Context

This command validates Skaffold configuration for local Kubernetes development using OrbStack.

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

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

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.

Workflow

Phase 1: Applicability Check

1. Check for k8s/ or helm/ directories
2. If not found: Report SKIP (Skaffold not applicable)
3. If found: Check for skaffold.yaml

Phase 2: Configuration Detection

Parse skaffold.yaml for:

• API version
• Build configuration
• Deploy configuration
• Port forwarding
• Profiles

Phase 3: Compliance Analysis

Required Checks:

Check	Standard	Severity
API version	skaffold/v4beta13	WARN if older
local.push	false	FAIL if true
portForward.address	127.0.0.1	FAIL if missing/0.0.0.0
useBuildkit	true	WARN if false
kubeContext	orbstack	INFO (recommended for local dev)
dotenvx hooks	Build or deploy hooks	INFO (recommended for secrets)

Security-Critical:

• Port forwarding MUST bind to localhost only (127.0.0.1)
• Never allow 0.0.0.0 or missing address
• Secrets should be generated via dotenvx hooks, not hardcoded

Recommended:

• 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

Phase 4: Report Generation

FVH Skaffold Compliance Report
==============================
Project Type: frontend (detected)
Skaffold: ./skaffold.yaml (found)

Configuration Checks:
  API version     v4beta13          ✅ PASS
  local.push      false             ✅ PASS
  useBuildkit     true              ✅ PASS
  Port security   127.0.0.1         ✅ PASS
  statusCheck     true              ✅ PASS
  kubeContext     orbstack          ✅ PASS
  dotenvx hooks   build hooks       ✅ PASS
  JSON log parse  enabled           ✅ PASS

Profiles Found:
  db-only         ✅ Present
  services-only   ✅ Present
  minimal         ✅ Present

Scripts:
  generate-secrets.sh ✅ Present (dotenvx integration)

Overall: Fully compliant

Phase 5: Configuration (If Requested)

If --fix flag or user confirms:

1. Missing skaffold.yaml: Create from FVH template
2. Security issues: Fix port forwarding addresses
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 template
7. Missing kubeContext: Add orbstack for local development

Phase 6: Standards Tracking

Update .fvh-standards.yaml:

components:
  skaffold: "2025.1"

FVH Standard 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

FVH 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

Usage 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"]

Flags

Flag	Description
--check-only	Report status without offering fixes
--fix	Apply fixes automatically

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.

See Also

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