Skip to content

Bootstrapping a New Cluster

End-to-end flow for standing up a new dke-* workload cluster from nothing to fully GitOps-managed.

1. Provision with Terraform

Uncomment/configure the cluster block using terraform/vsphere/modules/k8s (control-plane + worker VM count, network plugin, and — for new clusters — controlplane_vip/kubevip_bgp_source_ip/kubevip_bgp_as for the floating BGP VIP; see Terraform). terraform plan before apply, and apply with -target=module.dke first to stand up just the cluster before wiring in ArgoCD/Rancher registration, so a mistake in the registration step doesn't require re-provisioning the whole cluster.

2. Register into ArgoCD

module.argocd_register_supervisor-style modules (modules/argocd-register-clust) take a kubeconfig_path/kubeconfig_context and a cluster_name, create the argocd-manager ServiceAccount/ClusterRole/ClusterRoleBinding in the target cluster, and register it as an ArgoCD Cluster resource. Keep the cluster_name stable — it's what prevents a re-run from creating a duplicate registration for the same API server.

3. Wire into Vault

modules/vault-k8s-auth points the cluster's kubernetes_host at its DNS name, never a raw IP — see Vault Kubernetes Auth for why that one detail matters so much later.

4. Import into Rancher

See Rancher for the fleet-registration step — this is what makes the cluster visible/manageable from Rancher's UI alongside every other cluster.

5. Sync apps

Once registered, the cluster picks up whatever ApplicationSet targets it (CNI, ESO, MetalLB, ingress, workloads) — ArgoCD reconciles automatically from here on. See ArgoCD.

The bootstrap ApplicationSet is applied out-of-band

On dke-mgmt, the bootstrap ApplicationSet (k8s/dke-mgmt/bootstrap-appset.yaml) is applied by the provisioning script directly, not by ArgoCD syncing itself from git. Editing that file and pushing to git changes nothing until someone manually runs kubectl apply -f k8s/dke-mgmt/bootstrap-appset.yaml. This is the single most common "why didn't my change take effect" trap on this cluster.

Common follow-ups after any cluster-network change

  • MetalLB: restart the controller pod so services get reallocated onto the new pool, then update pfSense DNS host overrides (ArgoCD/Rancher/registry ingress) to match the new LB IP — see DNS.
  • Static/dynamic PVs referencing an NFS server IP: PV specs are immutable. If the NFS server's IP changed, delete the PV/PVC and let the provisioner (or a hard-refresh of the cluster-config app) recreate them — data itself is safe under Retain.