LiorCohen/sdd / plugin/fullstack-typescript/skills/components/helm/helm-scaffolding
helm-scaffolding
VerifiedScaffolds Helm charts for SDD components, driven by component settings.
Helm Scaffolding Skill
Scaffolds Helm charts for deploying SDD components to Kubernetes. Charts are generated based on component settings from sdd/sdd-settings.yaml.
Skills
Use the following skills for reference:
techpack-settings— Authoritative source for helm component settings schema (deploys, deploy_type, deploy_modes, ingress, assets)
When to Use
Use when creating Helm chart components. Creates Helm charts that integrate with the SDD config system.
Settings-Driven Scaffolding
Helm charts are scaffolded based on their settings in sdd/sdd-settings.yaml. Delegate to the techpack-settings skill for the complete helm settings schema and defaults — it returns deploys (server reference), deploy_type, deploy_modes (array of mode strings), ingress (boolean), and assets (static file configuration).
Template Selection Logic
// Pseudocode for settings-driven template selection
const scaffoldHelmChart = async (helmComponent: HelmComponent): Promise<void> => {
const { settings } = helmComponent;
// Always include base templates
await copyTemplate('_helpers.tpl');
await copyTemplate('configmap.yaml');
if (settings.deploy_type === 'server') {
// Server-specific templates
await copyTemplate('servicemonitor.yaml'); // All servers get metrics
const deployModes = settings.deploy_modes ?? [serverSettings.server_type];
if (deployModes.length > 1) {
// Multiple modes = separate deployments per mode
if (deployModes.includes('api')) await copyTemplate('deployment-api.yaml');
if (deployModes.includes('worker')) await copyTemplate('deployment-worker.yaml');
if (deployModes.includes('cron')) await copyTemplate('cronjob.yaml');
} else if (deployModes[0] === 'cron') {
await copyTemplate('cronjob.yaml');
} else {
await copyTemplate('deployment.yaml');
}
// Service only if deploying api mode and server provides contracts
if (deployModes.includes('api') && serverSettings.provides_contracts.length > 0) {
await copyTemplate('service.yaml');
}
} else {
// Webapp templates
await copyTemplate('deployment.yaml');
await copyTemplate('service.yaml');
}
// Ingress from helm settings
if (settings.ingress) {
await copyTemplate('ingress.yaml');
}
};
Directory Structure
Helm charts live at components/helm_charts/<name>/:
| Component Name | Directory |
|---|---|
main-server-api | components/helm_charts/main-server-api/ |
admin-dashboard | components/helm_charts/admin-dashboard/ |
umbrella | components/helm_charts/umbrella/ |
What It Creates
Server Chart Structure
components/helm_charts/<name>/
├── Chart.yaml # Chart metadata
├── values.yaml # Default values
└── templates/
├── _helpers.tpl # Template helpers (always)
├── configmap.yaml # Config mount (always)
├── servicemonitor.yaml # Metrics integration (always)
├── deployment.yaml # Single-mode deployment
├── deployment-api.yaml # Hybrid: API mode deployment
├── deployment-worker.yaml # Hybrid: Worker mode deployment
├── cronjob.yaml # Cron mode
├── service.yaml # When provides_contracts (conditional)
└── ingress.yaml # When ingress: true (conditional)
Webapp Chart Structure
components/helm_charts/<name>/
├── Chart.yaml
├── values.yaml
└── templates/
├── _helpers.tpl
├── deployment.yaml # nginx with config injection
├── service.yaml
├── configmap.yaml # App config + nginx config
└── ingress.yaml # When ingress: true (conditional)
Umbrella Chart Structure
components/helm_charts/umbrella/
├── Chart.yaml # Lists all charts as dependencies
└── values.yaml # Enable/disable individual charts
Template Variables
| Variable | Description |
|---|---|
{{CHART_NAME}} | Helm chart name |
{{CHART_DESCRIPTION}} | Helm chart description |
{{DEPLOYS_COMPONENT}} | Name of component this chart deploys |
{{APP_VERSION}} | Application version |
{{PROJECT_NAME}} | Project name |
{{IS_HYBRID}} | True if deploying multiple modes |
{{DEPLOY_MODES}} | List of modes being deployed |
{{HAS_SERVICE}} | True if server provides contracts |
{{HAS_INGRESS}} | True if ingress enabled |
Templates Location
Templates are organized by deployment target:
skills/components/helm/helm-scaffolding/
├── templates/ # Legacy (single deployment)
├── templates-server/ # Server charts
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── deployment-api.yaml
│ ├── deployment-worker.yaml
│ ├── cronjob.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── servicemonitor.yaml
│ └── configmap.yaml
├── templates-webapp/ # Webapp charts
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ └── configmap.yaml
└── templates-umbrella/ # Umbrella chart
├── Chart.yaml
└── values.yaml
Config Integration
Server Config Injection
Config is mounted as a file at /app/config/config.yaml. The application reads config using the SDD_CONFIG_PATH environment variable:
# templates/configmap.yaml
data:
config.yaml: |
{{- toYaml .Values.config | nindent 4 }}
The ConfigMap is mounted in deployments and SDD_CONFIG_PATH is set automatically.
Deployment workflow:
# Generate merged config
<plugin-root>/fullstack-typescript/system/system-run.sh config generate --env production --component main-server \
--output production-config.yaml
# Deploy with config
helm install my-release ./components/helm_charts/main-server-api \
-f values-production.yaml \
--set-file config=production-config.yaml
Webapp Config Injection
Config is injected into HTML at deploy time via init container:
- Webapp exports:
export const startApp = (config: AppConfig) => { ... } - Helm chart's index.html has:
startApp(__SDD_CONFIG__) - Init container replaces
__SDD_CONFIG__with JSON from ConfigMap - App receives config as parameter
Observability Integration
All server charts include:
- ServiceMonitor - Registers app with Prometheus/Victoria Metrics
- Metrics endpoint - Port 9090 for health/metrics
- Structured logging - JSON logs to stdout (collector picks up)
Cluster-level observability (Victoria Metrics, Victoria Logs) is set up separately (see task #47).
Scaffold Spec
To scaffold a Helm chart, build a spec with context flags derived from helm + server settings and invoke the engine:
<plugin-root>/fullstack-typescript/system/system-run.sh scaffolding apply --spec spec.json
Variables
| Variable | Source |
|---|---|
PROJECT_NAME | From sdd-settings.yaml project name |
CHART_NAME | Helm component name |
CHART_DESCRIPTION | "Helm chart for <chart-name>" |
DEPLOYS_COMPONENT | Name of the component this chart deploys |
IS_HYBRID | "true" or "false" |
HAS_SERVICE | "true" or "false" |
HAS_INGRESS | "true" or "false" |
Context Flags (derived from settings)
| Flag | Derived From |
|---|---|
deploy_type | settings.deploy_type ("server" or "webapp") |
is_hybrid | deploy_modes.length > 1 |
is_cron_only | deploy_modes === ["cron"] |
has_api_mode | deploy_modes.includes("api") |
has_worker_mode | deploy_modes.includes("worker") |
has_cron_mode | deploy_modes.includes("cron") |
needs_service | has_api_mode && provides_contracts.length > 0 |
has_ingress | settings.ingress === true |
Example Spec (server chart)
See the full Helm chart spec example in the task description. Each template file is a separate template_file operation with appropriate when conditions based on the pre-computed context flags.
Operations Pattern
{
"target_dir": "<project-root>",
"base_dir": "<plugin-root>/skills",
"variables": { "CHART_NAME": "<chart-name>", "..." : "..." },
"context": {
"is_hybrid": false,
"is_cron_only": false,
"has_api_mode": true,
"needs_service": true,
"has_ingress": true
},
"operations": [
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/Chart.yaml", "dest": "components/helm_charts/<chart-name>/Chart.yaml" },
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/values.yaml", "dest": "components/helm_charts/<chart-name>/values.yaml" },
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/templates/_helpers.tpl", "dest": "components/helm_charts/<chart-name>/templates/_helpers.tpl" },
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/templates/configmap.yaml", "dest": "components/helm_charts/<chart-name>/templates/configmap.yaml" },
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/templates/servicemonitor.yaml", "dest": "components/helm_charts/<chart-name>/templates/servicemonitor.yaml" },
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/templates/deployment.yaml", "dest": "components/helm_charts/<chart-name>/templates/deployment.yaml", "when": [{ "key": "is_hybrid", "equals": false }, { "key": "is_cron_only", "equals": false }] },
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/templates/service.yaml", "dest": "components/helm_charts/<chart-name>/templates/service.yaml", "when": { "key": "needs_service", "equals": true } },
{ "type": "template_file", "source": "components/helm/helm-scaffolding/templates-server/templates/ingress.yaml", "dest": "components/helm_charts/<chart-name>/templates/ingress.yaml", "when": { "key": "has_ingress", "equals": true } },
{ "type": "package_json_scripts", "scripts": { "<chart-name>:lint": "helm lint components/helm_charts/<chart-name>" } }
]
}
Input
Schema: schemas/input.schema.json
Accepts chart name, deploy target, deployment type, and optional settings for modes, ingress, and webapp assets.
Output
Schema: schemas/output.schema.json
Returns the scaffolding engine result: created files, directories, and scripts; skipped paths; errors; and a human-readable summary.
Related Skills
helm-standards— Generated Helm charts must follow these standards. Definesvalues.yamlstructure, template patterns, settings-driven configuration, and release naming conventions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |