add-app
Skill869 starsChanged 33 days agoApache-2.0View on GitHub
Use when deploying a new application to the cluster — scaffolding a Flux Kustomization plus app-template HelmRelease under kubernetes/apps/ (new app, new service, "add X to the cluster")
2 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- joryirving/home-opsedited, first seen Oct 9, 2026
- dperezcabrera/pico-skillstheir own version, first seen Jul 29, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- joryirving/home-ops★ 23217% same
Wrote their own version · 1
- dperezcabrera/pico-skills★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-docker-appSkill
- renovate-reviewSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Ask the user (AskUserQuestion) for anything not already given:
- Very specific: line 65
Do not add commonMetadata or timeout — both were dropped as boilerplate.
- Very specific: line 82
Add user-specified dependencies to dependsOn.
- Very specific: line 271
Add ./<app>/ks.yaml to kubernetes/apps/<namespace>/kustomization.yaml resources, in alphabetical position among the app entries …
- Very specific: line 273
New namespace?: Create kubernetes/apps/<namespace>/ with a namespace.yaml and kustomization.yaml copied from an existing namespace (e.g.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add a New Application
Scaffolds kubernetes/apps/<namespace>/<app>/ with a Flux Kustomization (ks.yaml) and an app-template HelmRelease. Every value below comes from current repo conventions — when in doubt, mirror a recent real app instead of inventing structure:
| Reference app | Shows |
kubernetes/apps/network/echo-server | Minimal stateless app + route |
kubernetes/apps/selfhosted/wotcher | Secrets, config file via configMapGenerator, kopiur-backed persistence |
kubernetes/apps/selfhosted/searxng | Custom probes, CiliumNetworkPolicy, dragonfly dependency |
Step 1: Gather details
Ask the user (AskUserQuestion) for anything not already given:
- App name and namespace (existing dirs:
ls kubernetes/apps/) - Image repository + tag (upstream's current release)
- Port the app listens on, and whether it gets a route (hostname); internal (
envoy-internal, default) or public (envoy-external) - Persistence — does the app store state? (→ kopiur backup component)
- Secrets — env vars from 1Password? (→ ExternalSecret). Get the 1Password item name AND its exact field names — never guess field names
- Config files — mounted config? (→ configMapGenerator +
resources/) - Dependencies — other Flux Kustomizations this app needs
Step 2: Create the files
Layout:
kubernetes/apps/<namespace>/<app>/
├── ks.yaml
└── app/
├── kustomization.yaml
├── ocirepository.yaml
├── helmrelease.yaml
├── externalsecret.yaml # only if secrets
└── resources/ # only if config filesks.yaml
---
# yaml-language-server: $schema=https://k8s-schemas.home-operations.com/kustomize.toolkit.fluxcd.io/kustomization_v1.json
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: <app>
spec:
interval: 1h
path: "./kubernetes/apps/<namespace>/<app>/app"
prune: true
sourceRef:
kind: GitRepository
name: flux-system
namespace: flux-system
targetNamespace: <namespace>wait: omit it for a normal leaf app — it defaults to false, and explicit wait: false is redundant boilerplate we no longer keep. Only add wait: true when another Kustomization will dependsOn this one AND this Kustomization defines no healthChecks/healthCheckExprs — that is what gives the dependent a real readiness gate. If this Kustomization does define healthChecks, leave wait unset (setting wait: true would make Flux ignore those checks). Depending on another app (e.g. kopiur for persistence) does not by itself call for wait.
Do not add commonMetadata or timeout — both were dropped as boilerplate; the app-template chart sets app.kubernetes.io/* labels on the workloads, and timeout falls back to the Flux default.
If the app has persistence, add these to spec (components use ${APP} and ${KOPIUR_*} substitutions — see kubernetes/components/kopiur/backup/ for all knobs and their defaults):
components:
- ../../../../components/kopiur/backup
postBuild:
substitute:
APP: <app>
# Optional overrides, only when defaults don't fit:
# KOPIUR_CLAIM: <app>-data # PVC name (default: <app>)
# KOPIUR_CAPACITY: 15Gi # default: 5Gi
# KOPIUR_MOVER_UID: "1000" # default: 2000
# KOPIUR_MOVER_GID: "1000" # default: 2000Add user-specified dependencies to dependsOn. Include postBuild.substitute.APP whenever any component is used; omit components/postBuild entirely otherwise.
app/kustomization.yaml
---
# yaml-language-server: $schema=https://json.schemastore.org/kustomization
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ./externalsecret.yaml # only if secrets
- ./ocirepository.yaml
- ./helmrelease.yamlIf the app mounts config files, put them in resources/ and append:
configMapGenerator:
- name: <app>-configmap
files:
- config.yaml=./resources/config.yaml
generatorOptions:
disableNameSuffixHash: true
annotations:
kustomize.toolkit.fluxcd.io/substitute: disabledapp/ocirepository.yaml
---
# yaml-language-server: $schema=https://k8s-schemas.home-operations.com/source.toolkit.fluxcd.io/ocirepository_v1.json
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
name: <app>
spec:
interval: 15m
layerSelector:
mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip
operation: copy
ref:
tag: <version>
url: oci://ghcr.io/bjw-s-labs/helm/app-templateNever hardcode <version> from memory — use the version the rest of the repo is on:
/usr/bin/grep -h "tag:" kubernetes/apps/*/*/app/ocirepository.yaml | sort | uniq -c | sort -rn | head -1app/helmrelease.yaml
---
# yaml-language-server: $schema=https://raw.githubusercontent.com/bjw-s-labs/helm-charts/main/charts/other/app-template/schemas/helmrelease-helm-v2.schema.json
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: <app>
spec:
chartRef:
kind: OCIRepository
name: <app>
interval: 30m
values:
controllers:
<app>:
annotations:
reloader.stakater.com/auto: "true"
pod:
securityContext:
runAsGroup: 2000
runAsNonRoot: true
runAsUser: 2000
containers:
app:
image:
repository: <image-repo>
tag: <image-tag>
probes:
liveness:
enabled: true
readiness:
enabled: true
resources:
requests:
cpu: 10m
limits:
memory: 256Mi
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
service:
app:
ports:
http:
port: <port>Adjust runAsUser/runAsGroup (and capabilities) to what the image requires; drop the pod securityContext only if the image genuinely can't run non-root. Plain image tags are fine — Renovate pins digests and manages updates.
Optional value blocks (top-level under values, alphabetical: controllers, persistence, route, service):
Route (web UI/API):
route:
app:
hostnames:
- <app>.bjw-s.dev
parentRefs:
- name: envoy-internal # envoy-external for public apps
namespace: networkPersistence (pairs with the kopiur block in ks.yaml; also add fsGroup: 2000 + fsGroupChangePolicy: OnRootMismatch to the pod securityContext):
persistence:
data:
existingClaim: <app> # must match KOPIUR_CLAIM if overridden
globalMounts:
- path: /data
tmpfs: # writable /tmp for readOnlyRootFilesystem
type: emptyDir
globalMounts:
- path: /tmpConfig file mount (pairs with configMapGenerator):
persistence:
config:
type: configMap
name: <app>-configmap
globalMounts:
- path: /config/config.yaml
subPath: config.yaml
readOnly: trueSecrets: add to the container:
envFrom:
- secretRef:
name: <app>-secretapp/externalsecret.yaml (only if secrets)
---
# yaml-language-server: $schema=https://k8s-schemas.home-operations.com/external-secrets.io/externalsecret_v1.json
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: <app>
spec:
refreshInterval: 12h
secretStoreRef:
kind: ClusterSecretStore
name: onepassword-connect
target:
name: <app>-secret
creationPolicy: Owner
template:
data:
SOME_ENV_VAR: "{{ .<app>_field_name }}"
dataFrom:
- extract:
key: <1password-item>
rewrite:
- regexp:
source: "(.*)"
target: "<app>_$1"Convention: metadata.name is <app>, the generated Secret is <app>-secret, and dataFrom.extract + rewrite prefixes 1Password fields for use in template.data (see wotcher for a multi-item example). The .<prefix>_<field> references must use the item's real field names (from Step 1) — a wrong field name renders an empty value with no error. If the field names weren't provided and you can't ask, insert <FIXME: 1password field name> placeholders and call them out.
Step 3: Register in the namespace kustomization
Add ./<app>/ks.yaml to kubernetes/apps/<namespace>/kustomization.yaml resources, in alphabetical position among the app entries (namespace.yaml stays first; leave existing entries where they are).
New namespace? Create kubernetes/apps/<namespace>/ with a namespace.yaml and kustomization.yaml copied from an existing namespace (e.g. selfhosted) — keep the flux-alerts and kopiur/secret components and the literal name: _ in namespace.yaml (kustomize renames it) — and register the directory in kubernetes/flux/cluster's apps kustomization if namespaces are listed there.
Step 4: Verify
kustomize build kubernetes/apps/<namespace>/<app>/app # must render; ${APP} vars staying literal is expected
yamllint --config-file .yamllint.yaml kubernetes/apps/<namespace>/<app>Show the user the created files and get confirmation before committing. Commit style: feat(<app>): Deploy.
Common mistakes
- Copying a chart version or image tag from this skill or memory — always read the current version from the repo (Step 2 command) and upstream.
- Using volsync — this repo migrated to kopiur;
components/volsyncno longer exists. - Forgetting
reloader.stakater.com/auto— without it, secret/config changes don't restart pods. readOnlyRootFilesystem: truewithout a tmpfs — apps that write to/tmpwill crash; mount an emptyDir.- Skipping the sorting conventions — HelmRelease values follow
.agents/instructions/sorting.instructions.md. - Adding a CiliumNetworkPolicy by default — only some apps lock down ingress; copy
searxng's if the user asks for one. - Adding
wait,commonMetadata, ortimeouttoks.yaml— all three are boilerplate now. Leavewaitunset unless another Kustomization depends on this one and it has nohealthChecks(then, and only then,wait: true).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

