Config Files

Overview

Many self-hosted applications require configuration files at specific paths inside the container — prometheus.yml, gitlab.rb, mosquitto.conf, nginx.conf, and so on. Config Slots let you define these files as part of a stack template and edit their contents per deployment.

Under the hood, each config slot becomes a Kubernetes ConfigMap with a subPath volume mount. PodWarden handles ConfigMap creation, mounting, and cleanup automatically.

How Config Slots Work

Config Slots have two parts:

1. Config Schema (on the stack) — declares which config files the workload accepts, their mount paths, file types, and optional default content
2. Config Values (on the deployment) — stores the actual file content per deployment, allowing operators to customize each config file

When you deploy a deployment, PodWarden:

1. Resolves content for each config slot (user-edited content takes priority over defaults)
2. Creates a Kubernetes ConfigMap for each slot
3. Mounts each ConfigMap into the container at the declared path using a subPath volume mount
4. On undeploy, cleans up the ConfigMaps automatically

Defining Config Slots

Config slots are defined on stacks (or Hub templates). Each slot declares a mountable config file.

Adding Config Slots

1. Go to Apps & Stacks and create or edit a definition
2. Scroll to the Config Files section
3. Click Add Config Slot
4. Fill in the slot fields:

Supported File Types

The file_type field determines syntax highlighting in the config editor:

Config Schema Format

Config slots are stored as a JSON array in the config_schema field:

[
  {
    "name": "Prometheus Config",
    "key": "prometheus_yml",
    "mount_path": "/etc/prometheus/prometheus.yml",
    "file_type": "yaml",
    "required": true,
    "description": "Main Prometheus configuration file",
    "default_content": "global:\n  scrape_interval: 15s\n\nscrape_configs:\n  - job_name: 'prometheus'\n    static_configs:\n      - targets: ['localhost:9090']\n"
  }
]

Editing Config Files on Assignments

When creating or editing a deployment, config files appear in a collapsible Config Files section below the environment variables.

Customizing Config Files

1. Go to Deployments and create or edit an assignment
2. Expand the Config Files section (shows a count badge, e.g. "2 config files available")
3. Each config slot shows as a card with the slot name, description, and file type
4. Click Edit on any slot to open the code editor
5. Edit the file content — the editor provides syntax highlighting based on the file type
6. Click Reset to Default to revert to the template's default content

Each slot shows a status badge:

• default — using the template's default content (or empty)
• customized — operator has provided custom content

Config Values Format

Customized config file contents are stored as a JSON array in the config_values field on the assignment:

[
  {
    "key": "prometheus_yml",
    "content": "global:\n  scrape_interval: 30s\n\nscrape_configs:\n  - job_name: 'node'\n    static_configs:\n      - targets: ['node-exporter:9100']\n"
  }
]

Only slots with customized content are stored. Slots without a config_values entry use the default_content from the schema.

Deployment Behavior

Content Resolution

For each config slot, PodWarden resolves the file content in this order:

1. User-provided content — from config_values on the assignment
2. Default content — from default_content in the definition's config_schema
3. Skip — if neither exists and the slot is not required, it's omitted

If a required slot has no content (no user value and no default), deployment is blocked with a validation error.

Kubernetes Resources

Each config slot with resolved content creates:

• ConfigMap named {deployment-name}-cfg-{slot-key} in the target namespace
• Volume mount using subPath to mount the single file at the declared mount_path

The ConfigMap contains a single data key — the filename extracted from the mount path (e.g. prometheus.yml from /etc/prometheus/prometheus.yml).

Redeployment

When you redeploy an assignment after changing config values:

1. ConfigMaps are updated with new content
2. The Deployment is reapplied, triggering a pod restart with the updated config files

Undeploy Cleanup

When you undeploy an assignment, PodWarden deletes all config slot ConfigMaps along with the Deployment, Service, and other resources.

Examples

Prometheus

A monitoring server with a YAML config file.

Config schema on the stack:

[
  {
    "name": "Prometheus Config",
    "key": "prometheus_yml",
    "mount_path": "/etc/prometheus/prometheus.yml",
    "file_type": "yaml",
    "required": true,
    "description": "Scrape targets and alerting rules",
    "default_content": "global:\n  scrape_interval: 15s\n\nscrape_configs:\n  - job_name: 'prometheus'\n    static_configs:\n      - targets: ['localhost:9090']\n"
  }
]

Operators customize the scrape targets per deployment while the default config provides a working starting point.

Mosquitto MQTT Broker

An MQTT broker with a .conf config file.

Config schema:

[
  {
    "name": "Mosquitto Config",
    "key": "mosquitto_conf",
    "mount_path": "/mosquitto/config/mosquitto.conf",
    "file_type": "conf",
    "required": false,
    "description": "Mosquitto broker configuration",
    "default_content": "listener 1883\nallow_anonymous true\npersistence true\npersistence_location /mosquitto/data/\nlog_dest stdout\n"
  }
]

GitLab (Multiple Config Files)

A complex application with multiple config files at different paths.

Config schema:

[
  {
    "name": "GitLab Configuration",
    "key": "gitlab_rb",
    "mount_path": "/etc/gitlab/gitlab.rb",
    "file_type": "rb",
    "required": true,
    "description": "Main GitLab Omnibus configuration file"
  },
  {
    "name": "GitLab Runner Config",
    "key": "runner_toml",
    "mount_path": "/etc/gitlab-runner/config.toml",
    "file_type": "toml",
    "required": false,
    "description": "GitLab Runner registration and executor settings"
  }
]

Each config slot is independently editable per assignment. One operator might customize gitlab.rb while another uses the default.

Hub Templates with Config Slots

When you import a template from PodWarden Hub, any config slots defined on the Hub template are imported along with all other fields. The config_schema carries over — including default content — so operators can deploy immediately with sensible defaults or customize per deployment.

Hub template authors can add config slots in the template editor under the Config File Slots section.

Config Files vs. Volume Mounts

Config Slots and volume mounts serve different purposes:

Use Config Slots when you want operators to edit config file contents directly in PodWarden. Use configMap volume mounts when you have pre-existing ConfigMaps managed outside of PodWarden.

Next Steps

• Apps & Stacks — full field reference
• Storage — volume types including configMap and secret mounts
• Creating Custom Templates — build your own stack templates
• PodWarden Hub — browse templates with pre-configured config slots