Depgen K8s

Deployment Artifact Generator — Kubernetes

This skill generates deployment artifacts for a custom application:

1. Dockerfile — A production-ready, multi-stage container build file placed in the

application root folder.

1. Kubernetes manifests — Manifest files stored directly in the application's own

k8s/ folder for a single target environment. Since the k8s/ folder is gitignored, each machine maintains its own independent copy of the manifests with environment-specific ConfigMap/Secret values (hostnames, credentials, resource limits).

Note: Only custom applications (from # Custom Applications in CLAUDE.md) are processed. 3rd party supporting applications and external services are NOT containerized by this skill.

Inputs

/depgen-k8s  [environment]

| Argument | Required | Example | Description | |----------|----------|---------|-------------| | ` | Yes | hubmiddleware | Application name — must be a custom application from CLAUDE.md | | | No | homeserver` | Target environment name — must match a Kubernetes environment in CLAUDE.md |

If `` is omitted:

• If CLAUDE.md defines exactly one Kubernetes environment → auto-select it.
• If CLAUDE.md defines multiple Kubernetes environments → list them and ask the user to specify.

The environment name is matched case-insensitively against the environment headings in CLAUDE.md, accepting snake_case, kebab-case, or title-case input (e.g., home_server, home-server, Home Server).

No version: or module: arguments — deployment is application-level.

Input Resolution

The application name is matched against root-level application folders:

1. Strip any leading _ prefix from folder names (e.g., 1_hub_middleware → hub_middleware)
2. Match case-insensitively against the provided application name
3. Accept snake_case, kebab-case, or title-case input
4. Verify the application is listed under # Custom Applications in CLAUDE.md — reject if it is a 3rd party application or external service
5. If no match found, list available custom applications and stop

Auto-Resolved Paths

| File | Resolved Path | |------|---------------| | CLAUDE.md | Project root CLAUDE.md | | ENVIRONMENT.md | Project root ENVIRONMENT.md | | SPECIFICATION.md | /context/specification/SPECIFICATION.md | | Source code | / (pom.xml, composer.json, package.json, etc.) | | Application config | Stack-dependent (see detection) | | K8s manifests output | /k8s/ (gitignored — each machine maintains its own copy) |

PRD.md Extended Sections

Before generating deployment artifacts, check PRD.md for the following extended sections:

Architecture Principle

If PRD.md contains an # Architecture Principle section, extract patterns that affect deployment:

| Pattern | Deployment Impact | |---|---| | "Stateless" | Deployment uses RollingUpdate strategy without sticky sessions; no PVC needed for session storage | | "Container based deployment" | Validates this skill's applicability | | "Scale out" / "horizontally scalable" | Generate HorizontalPodAutoscaler (HPA) manifest targeting CPU 70% | | Specific resource constraints (e.g., "max 256Mi per pod") | Use as default resource limits in K8s manifests | | "Message driven" / "message queue" | Readiness probe should verify message queue connectivity |

If absent, use defaults from SPECIFICATION.md and CLAUDE.md (existing behavior).

High Level Process Flow

If PRD.md contains a # High Level Process Flow section:

• Process flows reveal inter-system dependencies (message queues, external service endpoints)
• Validate that the environment variable list and ConfigMap/Secret values include all dependencies mentioned in process flows
• If a flow references an external system not in the Depends on list, log a warning

If absent, derive dependencies from CLAUDE.md only (existing behavior).

---

Pre-Requisites

Before running this skill, the following must exist:

• Source code — The application must be implemented (not just context artifacts)
• SPECIFICATION.md — The technical specification must exist (generated by a specgen-* skill)
• Externalized configuration — The application config must use environment variables

(e.g., ${ENV_VAR:default} in Spring Boot, env('VAR') in Laravel, process.env.VAR in Node.js)

If any are missing, stop and inform the user.

Workflow

Phase 0: Validate Inputs

1. Resolve application folder from the provided name
2. Verify the application is a custom application in CLAUDE.md (not 3rd party or external service)
3. Verify source code exists (at least one of: pom.xml, composer.json, package.json)
4. Verify /context/specification/SPECIFICATION.md exists
5. Read CLAUDE.md (already in context) for project-level information
6. Detect environments from CLAUDE.md's # Environment section:

• Each ## heading under # Environment is an environment
• For each environment, extract:
• Environment name (e.g., "Home Server")
• Domain field (e.g., localhost, home.server)
• Deployment Type field (e.g., Manual, Kubernetes)
• IP field (from SSH Configuration or direct IP field) if present — needed for hostAliases generation in Phase 3
• If no environments are defined, stop with error: "No environments found in CLAUDE.md # Environment section."

1. Select target environment — filter to Kubernetes environments and select one:
2. Filter environments to those with Deployment Type: Kubernetes.
3. If no environment has Deployment Type: Kubernetes, stop with error: "No Kubernetes environments found in CLAUDE.md. This skill only generates K8s manifests for environments with Deployment Type: Kubernetes."
4. If the user provided an `` argument, match it against the Kubernetes environments (case-insensitively, accepting snake_case, kebab-case, or title-case).

• If matched → use it as the target environment.
• If not matched → list available Kubernetes environments and stop.

1. If no argument was provided:

• If exactly one Kubernetes environment exists → auto-select it.
• If multiple exist → list them and ask the user to specify.

1. Record the selected environment's Domain and IP for Phase 3.

Phase 1: Detect Application Stack

Step 1 — Identify Stack

Check the application root for build files:

| File Found | Stack | Build Tool | |---|---|---| | pom.xml | spring-boot | Maven | | composer.json | laravel | Composer | | package.json (no pom.xml or composer.json) | nodejs | npm / pnpm |

If none found, stop with error: "Cannot determine application stack."

If multiple found (e.g., pom.xml + package.json), prioritize: pom.xml > composer.json > package.json (the package.json is likely for frontend or E2E tests, not the main app).

Step 2 — Extract Stack-Specific Metadata

If spring-boot:

• Read pom.xml:
• `` → JDK version for base image
• `` → image name
• `` → image tag
• frontend-maven-plugin presence → has frontend build step
• jte-maven-plugin presence → has JTE precompilation
• spring-boot-maven-plugin → executable JAR packaging
• Read src/main/resources/application.yml:
• Extract all ${ENV_VAR:default} patterns via regex \$\{([^:}]+)(?::([^}]*))?\}
• server.port default → exposed container port
• Read .env (if exists) → local dev values for reference

If laravel:

• Read composer.json:
• require.php → PHP version for base image
• require.laravel/framework → Laravel version
• name → image name
• Read .env.example or scan config/*.php:
• Extract all env('VAR', 'default') patterns via regex env\('([^']+)'(?:,\s*'?([^')*]*)'?)?\)
• APP_PORT or default 8000 → exposed container port
• Check for vite.config.js or webpack.mix.js → has frontend build step
• Check for package.json in app root → Node.js needed for frontend build

If nodejs:

• Read package.json:
• engines.node → Node.js version for base image
• name → image name
• version → image tag
• scripts.build → build command (e.g., tsc, tsup, vite build, next build)
• scripts.start → start command
• Scan source files or .env for process.env.VAR patterns
• Check for tsconfig.json → TypeScript build step
• Determine framework: Express, Fastify, NestJS, Next.js, etc.

Step 3 — Common Detection (All Stacks)

From CLAUDE.md → extract the "Depends on" list for the target application:

| Dependency Pattern | External Service | |---|---| | References MongoDB | MongoDB required | | References MySQL / HC Database / SC Database | MySQL required | | References PostgreSQL | PostgreSQL required | | References Hub Single Sign On / Keycloak | Keycloak required | | References RabbitMQ / Message Queue | RabbitMQ required | | References Redis / Hub Cache | Redis required | | References SMTP / Mailcatcher | SMTP service required | | References Meilisearch / Hub Search Engine | Meilisearch required |

From SPECIFICATION.md → extract:

• Technology stack table (versions)
• Environment variable reference table (if present)

Step 4 — Classify Environment Variables

For each detected environment variable, classify as ConfigMap or Secret:

Secret (sensitive — stored in K8s Secret):

• Variable name contains PASSWORD, SECRET, KEY, TOKEN, CREDENTIAL
• Variable name contains ADMIN_USERNAME (admin-level credentials)
• Variable name is a database connection URI containing credentials

ConfigMap (non-sensitive — stored in K8s ConfigMap):

• Everything else: hostnames, ports, log levels, feature flags, queue names, CORS origins

Step 5 — Determine Health Check

| Stack | Default Health Endpoint | Condition | |---|---|---| | Spring Boot | /actuator/health | If spring-boot-starter-actuator in pom.xml | | Spring Boot | / (HTTP 200/302 check) | If no actuator | | Laravel | /health or / | Custom route or root | | Node.js | /health or / | Custom route or root |

Check if a health endpoint is explicitly defined in the source code. If not, use the default for the stack.

Step 6 — Present Detection Summary

Before generating, present findings to the user for confirmation:

Application Stack Detection:
- Stack:           Spring Boot 3.5.7 (Java 21)
- Artifact:        hub-middleware:1.0.3
- Frontend Build:  Yes (Vite via frontend-maven-plugin)
- JTE Precompile:  Yes (jte-maven-plugin)
- Exposed Port:    8080
- Health Check:    /actuator/health (actuator present)

External Services:
- MongoDB 7.0.6 (Hub Core Database)
- Keycloak 26.5.3 (Hub Single Sign On)
- RabbitMQ 3.11.9 (HC + SC Adapter Message Queues)
- Mailcatcher 0.8.1 (SMTP)

Environment Variables: 25 detected
- ConfigMap: 18 (hostnames, ports, log levels, queue names, flags)
- Secret: 7 (passwords, admin credentials)

If the user disagrees, allow overrides before proceeding.

Phase 2: Generate or Update Dockerfile

1. Check if /Dockerfile already exists
2. If it exists (UPDATE mode):

• Read the existing Dockerfile
• Compare detected values against what the Dockerfile currently has:
• Base image version (e.g., Java version changed in pom.xml)
• Exposed port (e.g., server.port default changed)
• Environment variable defaults (e.g., new env vars added)
• Build commands (e.g., frontend build step added or removed)
• Preserve any lines marked with # CUSTOM: comments — these are manual overrides

by the user/DevOps that should not be replaced

• Update only the parts that changed, keeping the overall structure intact
• Log what was changed (e.g., "Updated Java version from 17 to 21",

"Added MAIL_HOST env var")

1. If it does not exist (CREATE mode):

• Select the Dockerfile pattern from references/dockerfile-.md
• Substitute detected values (Java version, artifact name, port, etc.)
• Write the Dockerfile to /Dockerfile

The Dockerfile MUST:

• Use a multi-stage build (build stage + runtime stage)
• Use specific version tags for base images (not latest)
• Run as a non-root user in the runtime stage
• NOT copy .env, context/, e2e/, or test files into the image
• Include a HEALTHCHECK instruction if a health endpoint is available
• Include comments explaining each significant instruction
• Include a LABEL version="{version}" instruction using the application version extracted

from pom.xml (`), composer.json (version), or package.json (version`)

• Include a build argument ARG APP_VERSION={version} that can be overridden at build time

via docker build --build-arg APP_VERSION=1.0.3

Read references/dockerfile-spring-boot.md, references/dockerfile-laravel.md, or references/dockerfile-nodejs.md for the complete Dockerfile template per stack.

Phase 3: Generate or Update Kubernetes Manifests

Kubernetes manifests are stored directly in /k8s/ (no per-environment subfolders). Since the k8s/ folder is gitignored, each machine maintains its own independent copy with values specific to the target environment selected in Phase 0.

3a. Ensure Folder Structure

1. Check if /k8s/ exists. If not, create it.

Example folder structure:

hub_middleware/
  Dockerfile
  k8s/
    namespace.yaml
    configmap.yaml
    secret.yaml
    deployment.yaml
    service.yaml
    ingress.yaml          (optional)

3b. Generate Manifests

Generate individual YAML files inside /k8s/ using values from the target environment selected in Phase 0:

1. namespace.yaml — Namespace resource (use project code from CLAUDE.md in lowercase,

e.g., urp). Shared across all applications — identical content for every environment.

1. configmap.yaml — Non-sensitive environment variables (from Step 4 classification).

Values may differ per environment — use defaults from .env for local development; use TODO placeholders for other environments where values are not known.

1. secret.yaml — Sensitive environment variables (from Step 4 classification),

base64-encoded. Values use TODO placeholders for all non-local environments.

1. deployment.yaml — Container spec with:

• Versioned image tag (e.g., image: hub-middleware:1.0.3), NOT latest
• envFrom referencing ConfigMap and Secret
• Resource requests/limits (sensible defaults: 256Mi-512Mi memory, 250m-500m CPU)
• Readiness and liveness probes using the detected health endpoint
• Non-root securityContext
• hostAliases (conditional): If the environment's Domain from CLAUDE.md is referenced

in ConfigMap values AND is not localhost, add hostAliases mapping the Domain to the environment's IP address. This is needed because K8s pod DNS cannot resolve custom domains defined only in the host machine's /etc/hosts. See references/k8s-patterns.md.

1. service.yaml — ClusterIP service exposing the application port
2. ingress.yaml (optional) — if the application is a web application or API with

external access. Only generate if the environment's CLAUDE.md description suggests external access (e.g., mentions domain, IP, or ingress).

Read references/k8s-patterns.md for the complete manifest templates per resource type.

3c. Environment-Specific Values

When generating manifests for the target environment:

• ConfigMap and Secret values: Read ENVIRONMENT.md from the project root. If ENVIRONMENT.md

contains environment-specific credentials (organized by environment), use the matching values for the target environment. If values are not found, use TODO as placeholder.

• Resource limits: Use sensible defaults. If the CLAUDE.md environment description

mentions resource constraints, adjust accordingly.

• Ingress hostnames: Derive from the target environment description in CLAUDE.md if

available (e.g., IP address, domain name). Use TODO if not specified.

3d. Create

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rashidee
• Source: rashidee/co2-skills
• License: MIT
• Homepage: https://compound-context.com/

Install and usage instructions live in the source repository linked above.