Files
2026-08-31 10:57:52 -04:00

182 lines
6.3 KiB
Markdown

# compose-app
A generic Helm chart that takes a compose-like YAML declaration and renders one
Deployment + Service pair per service entry, plus optional Ingresses, volumes, and
secrets. It is designed as a reusable building block for deploying applications
"the homelab way" (Traefik + cert-manager + external-secrets + gethomepage
discovery) without writing a bespoke chart each time.
---
## What it creates
For each entry in `services`:
1. **Deployment** (`apps/v1`) — replicas, image, ports, environment, command/args,
and volume mounts.
2. **Service** (`v1`) — ClusterIP by default, exposing the declared ports.
Additionally, based on the other values:
- **PersistentVolumes / PersistentVolumeClaims** for each entry in `volumes`
(supports NFS-backed volumes).
- **Secrets** for each entry in `secrets`.
- **ExternalSecrets** and **Password generators** (external-secrets) based on
`externalSecrets`.
- **Ingresses** when `ingress.enabled` is true.
---
## values.yaml reference
### `global`
Shared cluster configuration, most importantly `global.dns`, which drives the
ingress hostnames and TLS. See the [repo root Readme](../Readme.md#global-dns-configuration)
for the full DNS table. `global.dns.tls.enabled` must be true for TLS resources to be
generated.
### `services`
A map of service name → service definition:
```yaml
services:
my-app:
image: myorg/my-app:latest # container image (required)
replicas: 2 # default 1
imagePullPolicy: Always # default "Always"
labels: # optional, set as Deployment annotations
- "key=value"
ports: # list of container ports
- name: http # default "http"
port: 8080 # containerPort (required)
protocol: TCP # default "TCP"
environment: # key/value env vars
FOO: bar
envFrom: # list of configMap/secret refs
- configMapRef:
name: my-config
command: [] # list of command args
args: [] # list of args
volumes: # map: volumeName -> mount path; PVC is expected to exist
data: /var/lib/app
serviceAnnotations: {} # annotations applied to the Service
serviceType: ClusterIP # default "ClusterIP"
```
Each rendered Service points at the matching Deployment (`selector: app: <name>`).
### `volumes`
A map of volume name → volume definition. Entries produce a PersistentVolumeClaim
(with the entry's name). Two forms are supported:
- **Standard PVC** (no `type`):
```yaml
volumes:
data:
size: 10Gi # default "1Gi"
accessMode: ReadWriteOnce # default "ReadWriteOnce"
type: "" # optional storageClassName when set
```
- **NFS-backed** (`type: nfs`): renders a PersistenteVolume bound by name
(`<namespace>-nfs-<hash>`) plus a matching PVC. The volume `name` in `services.
<name>.volumes` must equal this volume key to bind.
```yaml
volumes:
media:
type: nfs
server: nfs-server.local
path: /export/media
```
### `secrets`
A map of secret name → list of entries. Each entry creates a string key/value, plus
optional aliases that reference the same value:
```yaml
secrets:
my-secret:
- name: PASSWORD
value: "s3cr3t"
aliases: # optional extra keys with the same value
- API_TOKEN
```
### `externalSecrets`
- `externalSecrets.secrets` — map of `ExternalSecret` names → spec (rendered under `spec:`).
- `externalSecrets.generators` — map of names → spec for external-secrets `Password`
generators.
```yaml
externalSecrets:
generators:
db-pass:
length: 24
secrets:
db-credentials:
secretStoreRef:
kind: SecretStore
name: vault
data:
- secretKey: password
remoteRef:
key: db
property: password
```
### `ingress`
Ingressing is handled by a shared template (`homelab.ingress`). Set
`ingress.enabled: true` and pass the following:
| Key | Default | Description |
| --- | --- | --- |
| `prefix` | (required) | Host prefix; the first dotted label is used as the subdomain, the rest as a "lead prefix". |
| `service` | (required) | Name of the Service to route to. |
| `port` | `80` | Backend service port. |
| `path` | `/` | Backend path (pathType: Prefix). |
| `middleware` | `ingress-https-redirect@kubernetescrd` | Traefik middleware name. |
| `useSecondaryDomain` | `false` | Use the secondary DNS root/domain instead of the primary. |
| `useDirectPrefix` | `false` | When true, output uses the bare primary domain (e.g. `<prefix>.bob.cat`) instead of the root-qualified form (e.g. `<prefix>.gr.bob.cat`). |
| `useWildCard` | `global.dns.tls.useWildCard` | Override wildcard TLS behavior for this ingress. |
| `disableExternalIngress` | `false` | Skip the public ingress (only the internal one is created). |
| `group` | `Unassigned` | gethomepage group label. |
| `description` | — | gethomepage description. |
| `icon` | `homepage.png` | gethomepage icon. |
| `widget` | — | Map rendered as `gethomepage.dev/widget.*` annotations. |
| `annotations` | `{}` | Extra annotations applied to both ingresses. |
| `health` | — | Suffix appended to the gethomepage siteMonitor probe URL. |
The `homelab.ingress` template always creates an **internal** ingress
(`<prefix>.<global.dns.internalPrefix>`, e.g. `app.k3s.internal`), and — unless
`disableExternalIngress` is set — a **public** ingress (e.g. `app.gr.bob.cat`),
with optional TLS and gethomepage annotations.
There is also a `homelab.ingress.tailscale` template for creating a Tailscale
(`ingressClassName: tailscale`) ingress plus a `tailscale-<name>` Service. It is not
wired into `ingress.yaml` by default; call it explicitly if you need VPN-only exposure.
```yaml
ingress:
enabled: true
prefix: app
service: my-app
port: 8080
group: Media
```
---
## Notes
- Volume mounts reference PVCs by name; for standard volumes a matching PVC is
generated for you, for NFS the generated PVC/PV must match the service's mount name.
- `global.dns.tls.enabled` gates both cert-manager/ExternalSecret generation and the
`tls` block on the public ingress.