Initial commit

docs/adding-an-app.md

@@ -0,0 +1,209 @@
+# Adding an App: Step-by-Step
+
+This guide walks through adding a new app to your cluster, using a simple `whoami` test service as an example. By the end, you'll have a working app accessible at `https://whoami.example.com`.
+
+## Overview
+
+Adding an app requires touching 4 places:
+
+1. **Namespace** — `bootstrap/ns/apps.yaml`
+2. **App manifests** — `apps/whoami/install/`
+3. **Flux Kustomization** — `bootstrap/kustomization/apps/whoami/`
+4. **IngressRoute** — `infrastructure/routes/whoami.yaml`
+
+## Step 1: Create the namespace
+
+Edit `bootstrap/ns/apps.yaml` and add:
+
+```yaml
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: whoami
+```
+
+## Step 2: Create the app manifests
+
+Create `apps/whoami/install/kustomization.yaml`:
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: whoami
+resources:
+  - deployment.yaml
+```
+
+Create `apps/whoami/install/deployment.yaml`:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: whoami
+  namespace: whoami
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: whoami
+  template:
+    metadata:
+      labels:
+        app: whoami
+    spec:
+      containers:
+        - name: whoami
+          image: traefik/whoami:latest
+          ports:
+            - containerPort: 80
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: whoami
+  namespace: whoami
+spec:
+  type: ClusterIP
+  ports:
+    - port: 80
+      targetPort: 80
+  selector:
+    app: whoami
+```
+
+## Step 3: Create the Flux Kustomization
+
+Create `bootstrap/kustomization/apps/whoami/whoami-install.yaml`:
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: install-whoami--app
+  namespace: flux-system
+spec:
+  interval: 5m
+  timeout: 4m
+  dependsOn:
+    - name: install-traefik--infra
+  path: ./apps/whoami/install
+  prune: true
+  wait: true
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+```
+
+## Step 4: Create the IngressRoute
+
+Create `infrastructure/routes/whoami.yaml`:
+
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: redirect-https
+  namespace: whoami
+spec:
+  redirectScheme:
+    scheme: https
+    permanent: true
+---
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: whoami-ingress-http
+  namespace: whoami
+spec:
+  entryPoints:
+    - web
+  routes:
+    - match: Host(`whoami.example.com`)
+      kind: Rule
+      middlewares:
+        - name: redirect-https
+      services:
+        - name: whoami
+          namespace: whoami
+          port: 80
+---
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: whoami-ingress
+  namespace: whoami
+  annotations:
+    cert-manager.io/issuer: "cert-issuer"
+spec:
+  entryPoints:
+    - websecure
+  routes:
+    - match: Host(`whoami.example.com`)
+      kind: Rule
+      services:
+        - name: whoami
+          namespace: whoami
+          port: 80
+  tls:
+    secretName: whoami-tls
+    domains:
+      - main: whoami.example.com
+        sans:
+          - whoami.example.com
+```
+
+## Step 5: Commit and push
+
+```bash
+git add -A
+git commit -m "Add whoami app"
+git push
+```
+
+Flux will automatically detect the change and deploy your app. Watch it happen:
+
+```bash
+# Watch Flux pick up the change
+flux get kustomizations --watch
+
+# Verify the pod is running
+kubectl get pods -n whoami
+
+# Test it
+curl https://whoami.example.com
+```
+
+## Using a Helm Chart Instead
+
+If your app has a Helm chart, the pattern is slightly different:
+
+1. Add a HelmRepository in `bootstrap/repositories/` pointing to the chart source
+2. In your app's install directory, use a HelmRelease instead of raw manifests:
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+  name: my-app-release
+  namespace: my-app
+spec:
+  chart:
+    spec:
+      chart: my-app
+      version: 1.0.0
+      sourceRef:
+        kind: HelmRepository
+        name: my-app-repo
+        namespace: flux-system
+  interval: 15m
+  releaseName: my-app
+  valuesFrom:
+    - kind: ConfigMap
+      name: my-app-chart-overrides
+      valuesKey: values.yaml
+```
+
+3. Create a ConfigMap with your chart value overrides (same pattern as Traefik/MetalLB)
+4. Everything else (namespace, Flux Kustomization, IngressRoute) stays the same