# Kubernetes Cluster Bootstrap

This covers **phase 2** of the full cluster setup. The two phases are:

1. **Terraform** (`terraform/`) — provisions the Talos VM on Proxmox and bootstraps the Kubernetes control plane. Outputs `kubeconfig` and `talosconfig`.
2. **Flux CD** (this file) — installs the GitOps controller into the running cluster and points it at this repository. From that point on, everything in `kubernetes/` is reconciled automatically.

If you haven't run Terraform yet, start with [`terraform/README.md`](../terraform/README.md).

## Prerequisites

- `flux` CLI installed
- AGE private key for SOPS decryption
- `kubectl` configured with the cluster kubeconfig from Terraform:
  ```sh
  cd ../terraform
  terraform output -json kubeconfig | jq -r '.homelab' > ~/.kube/config
  ```

## Bootstrap Steps

### 1. Verify cluster access

```sh
kubectl get nodes
```

### 2. Bootstrap Flux CD

```sh
flux bootstrap github \
  --owner=berezovskyi-oleksandr \
  --repository=homelab \
  --branch=homelab-v2 \
  --path=./kubernetes \
  --token-auth \
  --personal
```

You will be prompted for a GitHub PAT, or set it beforehand:

```sh
export GITHUB_TOKEN=<your-pat>
```

Create a fine-grained PAT scoped to the `homelab` repository with:
- **Contents**: Read and write
- **Metadata**: Read-only (granted automatically)

This installs the Flux controllers and creates the `flux-system` namespace.

### 3. Create the SOPS AGE secret

Flux needs the AGE private key to decrypt SOPS-encrypted secrets.

```sh
kubectl create secret generic sops-age \
  --namespace=flux-system \
  --from-file=age.agekey=<path-to-age.key>
```

### 4. Verify Flux is reconciling

```sh
flux get kustomizations --watch
```

All kustomizations should eventually show as `Ready`.

### 5. Troubleshooting

Check Flux controller logs:

```sh
flux logs
```

Force a reconciliation:

```sh
flux reconcile source git flux-system
flux reconcile kustomization flux-system
```

## Changing the Target Branch

To point Flux at a different branch (e.g. after merging `homelab-v2` into `master`):

1. Merge the branch as usual via a PR.
2. Re-run `flux bootstrap` with the new `--branch` value:

```sh
flux bootstrap github \
  --owner=berezovskyi-oleksandr \
  --repository=homelab \
  --branch=master \
  --path=./kubernetes \
  --token-auth \
  --personal
```

This updates both the `GitRepository` resource in the cluster and the `flux-system/gotk-sync.yaml` file committed to the repo. No manual `kubectl patch` needed.

## Reconciliation Order

Flux applies resources in dependency order:

1. **config** — Cluster-wide variables and encrypted secrets
2. **infrastructure-controllers** — Traefik, cert-manager, Authelia, MetalLB, NFS provisioner, Intel GPU plugin (depends on config)
3. **infrastructure-configs** — ClusterIssuer, MetalLB config (depends on infrastructure-controllers)
4. **external-vars** — External service variables (e.g. Home Assistant)
5. **apps** — All application workloads (depends on config + infrastructure-configs + external-vars)