182 lines
6.3 KiB
Markdown
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. |