clean up and docs

This commit is contained in:
ari committed 2026-08-31 10:57:52 -04:00
1 parent 0bb935b076
commit 22ef880654
8 files changed
+312 -262

No files matched your search

+85 -1
View File
@@ -1 +1,85 @@
# My Helm Charts
# My Helm Charts
A collection of Helm charts for deploying self-hosted applications to a personal
homelab Kubernetes cluster (based on k3s). The charts assume a homelab infrastructure
that includes:
- **Traefik** as the ingress controller
- **cert-manager** for per-host certificate issuance
- **external-secrets** (with a `ClusterSecretStore`) for fetching TLS certificates
- **Tailscale** ingress (`ingressClassName: tailscale`) for VPN-only access
- **gethomepage** annotations so the [Homepage](https://gethomepage.dev) dashboard
auto-discovers services from the ingresses
> The `x.cat` domain names, DNS configuration, and certificate stores are samples from
> the author's own homelab. Adjust the `global.dns` block in your own values to match
> your environment.
---
## Contents
| Chart | Description |
| --- | --- |
| [`compose-app`](charts/compose-app) | A generic "compose-like" chart that turns a simple YAML service declaration into Deployments, Services, and Ingresses. Also manages volumes and secrets. |
| [`homepage`](charts/homepage) | Deploys [Homepage](https://gethomepage.dev), a self-hosted start page / dashboard, with a ServiceAccount + RBAC that lets it read cluster state. |
---
## Repository structure
```
charts/
├── charts/
│ ├── compose-app/ # Generic app-deploy chart (Deploy + Service + Ingress + volumes + secrets)
│ └── homepage/ # Homepage dashboard chart (Deploy + ConfigMap + RBAC)
└── Readme.md # This file
```
---
## Using these charts
Each chart is a standalone Helm chart (Helm v3 / `apiVersion: v2`). Install one with:
```sh
helm install <release-name> ./charts/<chart-name> -f my-values.yaml
```
There is no central umbrella chart and no chart repository index in this repo; each
chart is referenced by (relative) path.
---
## Global DNS configuration
`compose-app` carries a shared `global.dns` values block describing the DNS layout,
TLS, and certificate management used to build ingress hosts:
| Key | Default | Description |
| --- | --- | --- |
| `global.dns.internalPrefix` | `k3s.internal` | Host suffix used for internal ingresses (e.g. `<prefix>.k3s.internal`). |
| `global.dns.primary.domain` | `bob.cat` | Primary public domain. |
| `global.dns.primary.root` | `""` | Subdomain root under the primary domain (empty root → the domain itself). |
| `global.dns.secondary.domain` | `tod.cat` | Secondary (backup) public domain. |
| `global.dns.secondary.root` | `gr` | Subdomain root under the secondary domain. |
| `global.dns.tls.enabled` | `true` | Whether to provision TLS for ingress hosts. |
| `global.dns.tls.issuer` | `issue` | `ClusterIssuer` name used by cert-manager when not using wildcards. |
| `global.dns.tls.acmeServer` | `http://acme` | ACME server endpoint (informational). |
| `global.dns.tls.skipTLSVerify` | `true` | Skip TLS verification for the ACME client. |
| `global.dns.tls.useWildCard` | `true` | If true, reuse a wildcard cert via external-secrets; otherwise request per-host certificates. |
---
## TLS provisioning
TLS secrets are produced one of two ways, controlled by `useWildCard`:
- **Wildcard (default):** an `ExternalSecret` fetches `tls.crt` / `tls.key` from a
`ClusterSecretStore` named `k8s-ns-certs`, referenced as `cloudflare-wildcard<domain>`.
This is how the sample values provision certificates.
- **Per-host:** a cert-manager `Certificate` is created for the host, using the
`ClusterIssuer` named by `global.dns.tls.issuer`.
The generated secret is always named `tls-<prefix><domain>` and referenced by the TLS
ingress rule.
+182
View File
@@ -0,0 +1,182 @@
# 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.
+2 -2
View File
@@ -1,6 +1,6 @@
apiVersion: v2
name: Transmission
description: A Helm chart for deploying Transmission, a BitTorrent client, to a Kubernetes cluster.
name: homepage
description: A Helm chart for deploying Homepage, a self-hosted dashboard, to a Kubernetes cluster.
type: application
version: 0.1.0
dependencies: []
+43
View File
@@ -0,0 +1,43 @@
# homepage
A Helm chart that deploys [Homepage](https://gethomepage.dev), a self-hosted
dashboard / start page, with the RBAC it needs to read cluster state.
---
## What it creates
- **ConfigMap** `homepage` — home directory-style config files populated with a
default Kubernetes widget and empty `settings.yaml`, `services.yaml`,
`bookmarks.yaml`, `custom.css`, `custom.js`.
- **Deployment** `homepage` — runs the Homepage container (ports `3000`), mounts the
ConfigMap entries (and an `emptyDir` for logs).
- **Service** `homepage` — exposes the dashboard on port 80 → 3000.
- **ServiceAccount** + **Secret** `homepage` (service-account-token).
- **ClusterRole** / **ClusterRoleBinding** `homepage` — allows reading
namespaces/pods/nodes/services/endpoints, ingresses, Traefik `ingressroutes`,
Gateway API `httproutes`/`gateways`, and metrics (`metrics.k8s.io`). This powers
the cluster widgets and enables services to be discovered via the
`gethomepage.dev/*` annotations added by the `compose-app` ingresses.
---
## values.yaml reference
| Key | Default | Description |
| --- | --- | --- |
| `image` | `ghcr.io/gethomepage/homepage:latest` | Homepage container image. |
| `allowedHosts` | `gethomepage.dev` | Value for the `HOMEPAGE_ALLOWED_HOSTS` env var. |
| `serviceType` | `ClusterIP` | Type of the `homepage` Service. |
| `serviceAnnotations` | `{}` | Annotations applied to the Service. |
---
## Notes
- The ConfigMap contents are hardcoded in the template; to customize `settings.yaml`,
`services.yaml`, `bookmarks.yaml`, or `custom.*`, edit the `configmap.yaml` template
(or override it) — they are not parameterized via `values.yaml`.
- The `homepage <release>` install typically pairs with ingresses from `compose-app`
whose `gethomepage.dev` annotations are picked up automatically because Homepage
runs in `mode: cluster`.
-6
View File
@@ -1,6 +0,0 @@
apiVersion: v2
name: Transmission
description: A Helm chart for deploying Transmission, a BitTorrent client, to a Kubernetes cluster.
type: application
version: 0.1.0
dependencies: []
@@ -1,6 +0,0 @@
{{ define "envs" }}
{{- range $key, $val := . }}
- name: {{ $key }}
value: {{ $val | quote }}
{{ end -}}
{{ end }}
-211
View File
@@ -1,211 +0,0 @@
{{ $labels := (dict
"app.kubernetes.io/name" .Chart.Name
"app.kubernetes.io/instance" .Release.Name
"app.kubernetes.io/part-of" .Release.Namespace
) }}
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Release.Name }}
name: {{ .Release.Namespace }}
spec:
replicas: 1
revisionHistoryLimit: 4
selector:
matchLabels:
{{ $labels | toYaml | nindent 12 }}
strategy:
type: Recreate
template:
metadata:
labels:
{{ $labels | toYaml | nindent 16 }}
spec:
volumes:
{{ $.Values.volumes | toYaml | nindent 25 }}
containers:
{{ if $.Values.transmission.enabled }}
- name: transmission
env:
{{ include "envs" $.Values.transmission.env | nindent 25 }}
image: "{{ $.Values.transmission.image }}"
imagePullPolicy: Always
resources:
{{ $.Values.transmission.resources | toYaml | nindent 25 }}
volumeMounts:
{{ $.Values.transmission.volumeMounts | toYaml | nindent 25 }}
# livenessProbe:
# exec:
# command:
# - sh
# - -c
# - "ping -c 1 www.google.com || exit 1"
# initialDelaySeconds: 20
# periodSeconds: 60
# failureThreshold: 3
# timeoutSeconds: 10
# readinessProbe:
# exec:
# command:
# - sh
# - -c
# - "ping -c 1 www.google.com || exit 1"
# initialDelaySeconds: 20
# periodSeconds: 60
# failureThreshold: 3
# timeoutSeconds: 10
{{ end }}
{{ if $.Values.qbittorrent.enabled }}
- name: qbittorrent
env:
- name: WEBUI_PORT
value: "{{ $.Values.qbittorrent.ports.webui }}"
- name: TORRENTING_PORT
value: "{{ $.Values.qbittorrent.ports.torrenting }}"
{{ include "envs" $.Values.qbittorrent.env | nindent 24 }}
image: "{{ $.Values.qbittorrent.image }}"
imagePullPolicy: Always
resources:
{{ $.Values.qbittorrent.resources | toYaml | nindent 25 }}
volumeMounts:
{{ $.Values.qbittorrent.volumeMounts | toYaml | nindent 25 }}
# livenessProbe:
# exec:
# command:
# - sh
# - -c
# - "ping -c 1 www.google.com || exit 1"
# initialDelaySeconds: 20
# periodSeconds: 60
# failureThreshold: 3
# timeoutSeconds: 10
# readinessProbe:
# exec:
# command:
# - sh
# - -c
# - "ping -c 1 www.google.com || exit 1"
# initialDelaySeconds: 20
# periodSeconds: 60
# failureThreshold: 3
# timeoutSeconds: 10
{{ end }}
initContainers:
- name: vpn
env:
{{ include "envs" $.Values.gluetun.env | nindent 25 }}
envFrom:
{{ $.Values.gluetun.envFrom | toYaml | nindent 25 }}
image: {{ $.Values.gluetun.image }}
imagePullPolicy: IfNotPresent
ports:
{{ if $.Values.transmission.enabled }}
- containerPort: 9091
protocol: TCP
name: t-webui-tcp
- containerPort: 9091
protocol: UDP
name: t-webui-udp
- containerPort: 51413
protocol: TCP
name: t-torrent-tcp
- containerPort: 51413
protocol: UDP
name: t-torrent-udp
{{ end }}
{{ if $.Values.qbittorrent.enabled }}
- containerPort: {{ $.Values.qbittorrent.ports.webui }}
protocol: TCP
name: q-webui-tcp
- containerPort: {{ $.Values.qbittorrent.ports.webui }}
protocol: UDP
name: q-webui-udp
- containerPort: {{ $.Values.qbittorrent.ports.torrenting }}
protocol: TCP
name: q-torrent-tcp
- containerPort: {{ $.Values.qbittorrent.ports.torrenting }}
protocol: UDP
name: q-torrent-udp
{{ end }}
resources:
{{ $.Values.gluetun.resources | toYaml | nindent 25 }}
restartPolicy: Always
securityContext:
capabilities:
add:
- NET_ADMIN
# readinessProbe:
# exec:
# command:
# - sh
# - -c
# - "ping -c 1 www.google.com || exit 1"
# initialDelaySeconds: 20
# periodSeconds: 60
# failureThreshold: 3
# timeoutSeconds: 10
- name: ping
image: {{ $.Values.busybox.image }}
imagePullPolicy: IfNotPresent
resources:
{{ $.Values.busybox.resources | toYaml | nindent 25 }}
command:
- sh
- -c
- |
while ! ping -c 1 8.8.8.8; do
echo "Ping failed, retrying in 5"
sleep 5
done
echo "ping succesfull, exiting"
---
kind: Service
apiVersion: v1
metadata:
name: torrents
annotations:
{{ (.serviceAnnotations | default dict) | toYaml | nindent 4 }}
spec:
selector:
{{ $labels | toYaml | nindent 8 }}
type: {{ $.Values.serviceType | default "ClusterIP" | quote }}
ports:
{{ if $.Values.transmission.enabled }}
- targetPort: 9091
port: 9091
protocol: TCP
name: t-webui-tcp
- targetPort: 9091
port: 9091
protocol: UDP
name: t-webui-udp
- targetPort: 51413
port: 51413
protocol: TCP
name: t-torrent-tcp
- targetPort: 51413
port: 51413
protocol: UDP
name: t-torrent-udp
{{ end }}
{{ if $.Values.qbittorrent.enabled }}
- targetPort: {{ $.Values.qbittorrent.ports.webui }}
port: {{ $.Values.qbittorrent.ports.webui }}
protocol: TCP
name: q-webui-tcp
- targetPort: {{ $.Values.qbittorrent.ports.webui }}
port: {{ $.Values.qbittorrent.ports.webui }}
protocol: UDP
name: q-webui-udp
- targetPort: {{ $.Values.qbittorrent.ports.torrenting }}
port: {{ $.Values.qbittorrent.ports.torrenting }}
protocol: TCP
name: q-torrent-tcp
- targetPort: {{ $.Values.qbittorrent.ports.torrenting }}
port: {{ $.Values.qbittorrent.ports.torrenting }}
protocol: UDP
name: q-torrent-udp
{{ end }}
-36
View File
@@ -1,36 +0,0 @@
volumes: []
transmission:
enabled: true
image: linuxserver/transmission
env:
PUID: "1000"
PGID: "100"
TZ: Etc/UTC
resources: {}
volumeMounts: []
qbittorrent:
enabled: true
image: lscr.io/linuxserver/qbittorrent:latest
ports:
webui: 3000
torrenting: 6881
env:
PUID: "1000"
PGID: "100"
TZ: Etc/UTC
gluetun:
image: qmcgaw/gluetun:v3
resources: {}
env:
HEALTH_VPN_DURATION_INITIAL: 120s
# BLOCK_MALICIOUS: "off"
# DNS_KEEP_NAMESERVER: "on"
FIREWALL_OUTBOUND_SUBNETS: 10.42.0.0/15
envFrom: []
busybox:
image: busybox
resources: {}