GitOps Principles

Portefaix is built on GitOps — a set of practices that use Git as the single source of truth for declarative infrastructure and application state. We follow the OpenGitOps specification, a CNCF Sandbox project that formalises what "GitOps" means.

The Four OpenGitOps Principles

1. Declarative

The entire system — infrastructure, applications, policies — is described declaratively. Desired state is expressed as code checked into Git, not as imperative commands. This means the system state is always auditable and reproducible.

2. Versioned and Immutable

The desired state is stored in a way that enforces immutability and retains a complete version history. Git provides this naturally: every change is a commit, and history is never rewritten in a production context. This makes rollback trivial — revert to any previous commit.

3. Pulled Automatically

Software agents (ArgoCD, and FluxCD in v1.x) continuously observe the desired state in Git and automatically apply it to the target system. Rather than pushing changes from a CI pipeline, the cluster pulls its own desired state. This eliminates the need to grant CI systems write access to production clusters.

4. Continuously Reconciled

Software agents continuously reconcile the actual state of the system with the desired state. Any drift — whether from manual changes, node restarts, or partial failures — is automatically corrected. The system self-heals.

GitOps in Portefaix

Portefaix supports two GitOps tools, which serve different purposes and can be used together:

Repository Structure

In a typical Portefaix deployment, the GitOps repositories are structured as follows:

portefaix-kubernetes/
├── clusters/
│   ├── gcp/
│   │   └── production/     # cluster-specific kustomizations
│   └── aws/
│       └── staging/
├── stacks/
│   ├── observability/      # Grafana, Prometheus, Loki, Tempo
│   ├── security/           # Falco, Trivy, VAP policies
│   ├── networking/         # Cilium, cert-manager, external-dns
│   └── platform/           # Crossplane, ArgoCD/FluxCD itself
└── apps/
    └── ...                 # application-level GitOps

Secrets Management

Portefaix uses the External Secrets Operator (ESO) to synchronise secrets from external SaaS providers into Kubernetes. Secrets never live in Git — they are stored in a dedicated secret store and pulled into the cluster at runtime via SecretStore and ExternalSecret custom resources.

Supported backends include:

• Akeyless
• Infisical
• AWS Secrets Manager
• GCP Secret Manager
• Azure Key Vault
• HashiCorp Vault