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

Symptom	Likely cause	Fix
GitRepository shows auth failed	Deploy key not configured	Recreate the SSH secret: flux create secret git opencenter-base --ssh-key-algorithm=ed25519 --url=<repo-url> -n flux-system
Kustomization shows path not found	Wrong overlay path or missing tag	Verify --path matches the directory structure in the repo
SOPS decryption fails	Missing or wrong Age key	Recreate: kubectl create secret generic sops-age --from-file=age.agekey=<keyfile> -n flux-system
HelmRelease stuck in Installing	Image pull failure (air-gap)	Verify bastion registry is running and containerd mirrors are configured