FluxCD

FluxCD is a set of continuous and progressive delivery solutions for Kubernetes, built on the GitOps Toolkit. In Portefaix, FluxCD manages infrastructure-level reconciliation and works alongside the External Secrets Operator for secret management.

GitOps Toolkit

Flux is composed of specialised controllers, each responsible for a specific concern:

Bootstrap

Flux is bootstrapped directly into your cluster using the Flux CLI:

flux bootstrap github \
  --owner=<your-org> \
  --repository=portefaix-kubernetes \
  --branch=main \
  --path=clusters/<cloud>/<env> \
  --personal

This installs Flux into the flux-system namespace and creates a deploy key on the repository so Flux can pull updates.

Secret Management with External Secrets Operator

Portefaix uses the External Secrets Operator to pull secrets from external SaaS providers into Kubernetes at runtime. Secrets are never stored in Git. Supported backends include Akeyless, Infisical, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, and HashiCorp Vault.

SecretStore — connect to the backend

# SecretStore — points to the external backend
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: akeyless-store
  namespace: my-app
spec:
  provider:
    akeyless:
      akeylessGWApiURL: "https://api.akeyless.io"
      authSecretRef:
        accessID:
          name: akeyless-auth
          key: access-id
        accessType:
          name: akeyless-auth
          key: access-type

ExternalSecret — declare what to fetch

# ExternalSecret — declares which secret to fetch
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db-credentials
  namespace: my-app
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: akeyless-store
    kind: SecretStore
  target:
    name: db-credentials   # resulting Kubernetes Secret
  data:
    - secretKey: password
      remoteRef:
        key: /portefaix/prod/db/password

Kustomization Structure

Portefaix uses a layered Kustomize structure for environment overrides:

clusters/gcp/production/
├── flux-system/           # Flux controllers
├── kustomization.yaml     # Root kustomization
└── stacks/
    ├── observability.yaml # HelmRelease refs
    ├── security.yaml
    └── networking.yaml

base/stacks/
└── observability/
    ├── kustomization.yaml
    └── helm-release.yaml   # Base HelmRelease

ArgoCD Sync Policy Reference

For comparison, the ArgoCD equivalent sync policy looks like:

spec:
  syncPolicy:
    automated:
      prune: true      # remove resources deleted from Git
      selfHeal: true   # revert manual changes to cluster
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

CI/CD Integration

Flux integrates with GitHub Actions for a full GitOps CI/CD pipeline:

1. CI — GitHub Actions builds and pushes a new container image to the registry.
2. Image Update — Flux Image Automation detects the new tag and opens a pull request updating the image reference in Git.
3. Review & Merge — The team reviews and merges the PR.
4. Reconciliation — Flux detects the change in Git and deploys the new image to the cluster.

Monitoring Flux

Flux exposes Prometheus metrics for all controllers. The Portefaix observability stack includes pre-built Grafana dashboards for Flux reconciliation status, drift detection, and error rates.

# Check reconciliation status
flux get kustomizations --all-namespaces
flux get helmreleases --all-namespaces

# View events
flux events --for Kustomization/flux-system