diff --git a/Readme.md b/Readme.md index fa1ff38..91ed97a 100644 --- a/Readme.md +++ b/Readme.md @@ -1 +1,85 @@ -# My Helm Charts \ No newline at end of file +# 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 ./charts/ -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. `.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`. + 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-` and referenced by the TLS +ingress rule. \ No newline at end of file diff --git a/charts/compose-app/Readme.md b/charts/compose-app/Readme.md new file mode 100644 index 0000000..b5f9962 --- /dev/null +++ b/charts/compose-app/Readme.md @@ -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: `). + +### `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 + (`-nfs-`) plus a matching PVC. The volume `name` in `services. + .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. `.bob.cat`) instead of the root-qualified form (e.g. `.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 +(`.`, 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-` 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. \ No newline at end of file diff --git a/charts/homepage/Chart.yaml b/charts/homepage/Chart.yaml index 384fc56..9a8b24a 100644 --- a/charts/homepage/Chart.yaml +++ b/charts/homepage/Chart.yaml @@ -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: [] diff --git a/charts/homepage/Readme.md b/charts/homepage/Readme.md new file mode 100644 index 0000000..43486fc --- /dev/null +++ b/charts/homepage/Readme.md @@ -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 ` install typically pairs with ingresses from `compose-app` + whose `gethomepage.dev` annotations are picked up automatically because Homepage + runs in `mode: cluster`. \ No newline at end of file diff --git a/charts/torrents/Chart.yaml b/charts/torrents/Chart.yaml deleted file mode 100644 index 384fc56..0000000 --- a/charts/torrents/Chart.yaml +++ /dev/null @@ -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: [] diff --git a/charts/torrents/templates/_helpers/envs.tpl b/charts/torrents/templates/_helpers/envs.tpl deleted file mode 100644 index 822c03a..0000000 --- a/charts/torrents/templates/_helpers/envs.tpl +++ /dev/null @@ -1,6 +0,0 @@ -{{ define "envs" }} -{{- range $key, $val := . }} -- name: {{ $key }} - value: {{ $val | quote }} -{{ end -}} -{{ end }} \ No newline at end of file diff --git a/charts/torrents/templates/deploy.yaml b/charts/torrents/templates/deploy.yaml deleted file mode 100644 index 4998584..0000000 --- a/charts/torrents/templates/deploy.yaml +++ /dev/null @@ -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 }} \ No newline at end of file diff --git a/charts/torrents/values.yaml b/charts/torrents/values.yaml deleted file mode 100644 index 0b3ad01..0000000 --- a/charts/torrents/values.yaml +++ /dev/null @@ -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: {}