Skip to main content

FluxCD Bootstrap

Purpose: For platform engineers, shows how to use opencenter cluster bootstrap to install FluxCD and start reconciling platform services.

Prerequisites​

  • A running Kubernetes cluster deployed via Kubespray (see Kubernetes Deployment)
  • kubeconfig.yaml for the target cluster
  • opencenter CLI installed
  • SSH deploy key configured for the customer GitOps repository
  • SOPS Age key generated for secrets decryption

What Bootstrap Does​

The bootstrap command installs FluxCD controllers into the cluster and configures them to reconcile from the customer GitOps repository. After bootstrap, FluxCD continuously pulls manifests from Git and applies them — platform services, security policies, and customer applications all deploy through this single mechanism.

Steps​

1. Verify cluster access​

export KUBECONFIG=infrastructure/clusters/k8s-sandbox/kubeconfig.yaml
kubectl get nodes

All nodes should show Ready status.

2. Run the bootstrap command​

opencenter cluster bootstrap <cluster-name>

This command:

  1. Installs FluxCD components (source-controller, kustomize-controller, helm-controller, notification-controller).
  2. Creates the flux-system namespace.
  3. Configures the Git source pointing to the customer repository.
  4. Creates the SOPS Age secret for decrypting encrypted values.
  5. Starts reconciliation from applications/overlays/<cluster-name>/.

3. Verify FluxCD is running​

kubectl get pods -n flux-system

Expected output — four controllers in Running state:

NAME                                       READY   STATUS    RESTARTS   AGE
helm-controller-xxx                        1/1     Running   0          60s
kustomize-controller-xxx                   1/1     Running   0          60s
notification-controller-xxx                1/1     Running   0          60s
source-controller-xxx                      1/1     Running   0          60s

4. Check reconciliation status​

# GitRepository source
kubectl get gitrepositories -n flux-system

# Kustomizations
kubectl get kustomizations -n flux-system

The main GitRepository should show Ready: True. Kustomizations deploy in dependency order — cert-manager and kyverno typically reconcile first, followed by other platform services.

5. Monitor service rollout​

# Watch all Kustomizations converge
kubectl get kustomizations -n flux-system -w

# Check HelmReleases
kubectl get helmreleases -A

A full platform rollout (cert-manager, Kyverno, MetalLB, Longhorn, monitoring stack, Keycloak) takes 5–15 minutes depending on cluster size and image pull speed.

Manual Bootstrap (Alternative)​

If you need to bootstrap without the opencenter CLI:

flux bootstrap git \
  --url=ssh://git@github.com/<org>/<repo>.git \
  --branch=main \
  --path=applications/overlays/<cluster-name> \
  --private-key-file=<path-to-deploy-key>

Then create the SOPS secret manually:

kubectl create secret generic sops-age \
  --from-file=age.agekey=secrets/age/<cluster>_keys.txt \
  -n flux-system

Verification​

# All Kustomizations should be Ready
kubectl get kustomizations -n flux-system -o wide

# No failed HelmReleases
kubectl get helmreleases -A --field-selector=status.conditions[0].type=Ready

# Platform services running
kubectl get pods -n cert-manager
kubectl get pods -n kyverno
kubectl get pods -n monitoring

Troubleshooting​

SymptomLikely causeFix
GitRepository shows auth failedDeploy key not configuredRecreate the SSH secret: flux create secret git opencenter-base --ssh-key-algorithm=ed25519 --url=<repo-url> -n flux-system
Kustomization shows path not foundWrong overlay path or missing tagVerify --path matches the directory structure in the repo
SOPS decryption failsMissing or wrong Age keyRecreate: kubectl create secret generic sops-age --from-file=age.agekey=<keyfile> -n flux-system
HelmRelease stuck in InstallingImage pull failure (air-gap)Verify bastion registry is running and containerd mirrors are configured