Deploy via GitOps

pgAgroal Enterprise ships as a Helm chart, so it fits the GitOps tools you already run. This tutorial deploys the chart with both Argo CD and Flux, explains the dev/stage/prod overlay structure, covers private-registry integration, and validates the result with helm template before a controller syncs it. If you would rather install by hand first, start with Install with Helm.

Overlay structure

The deployment examples live under deploy/gitops/. An Argo CD Application and a Flux HelmRelease each reference the same chart at charts/pgagroal-enterprise, and they layer per-environment Helm values from the overlays/ directory:

deploy/gitops/
├── argocd/application.yaml      # Argo CD Application
├── flux/helmrelease.yaml        # Flux GitRepository + HelmRelease
└── overlays/
    ├── dev/values.yaml          # 1 replica, control plane off, tracing off
    ├── stage/values.yaml        # HA operator, tracing on
    ├── prod/values.yaml         # HA operator + control plane, higher limits
    └── private-registry-values.yaml  # mirror images for air-gapped/private registries

The overlays are plain Helm values files. The dev overlay runs a single operator replica with the control plane and tracing off; prod runs an HA operator plus the control plane with higher resource limits:

# overlays/dev/values.yaml — single operator replica, control plane off, tracing off
operator:
  replicas: 1
  image:
    tag: "0.1.0"
  otel: false
controlPlane:
  enabled: false

# overlays/prod/values.yaml — HA operator + control plane, tracing on, higher limits
operator:
  replicas: 2
  image:
    tag: "0.1.0"
  otel: true
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: "1"
      memory: 512Mi
controlPlane:
  enabled: true
  image:
    tag: "0.1.0"
  otel: true

Deploy with Argo CD

Apply the example Application, then edit spec.source.helm.valueFiles to pick the overlay for the target environment:

kubectl apply -f deploy/gitops/argocd/application.yaml

The Application sources the chart from the Git repo, releases it into the pgagroal-system namespace, and layers the prod overlay. The sync policy creates the namespace and uses server-side apply so Argo can manage the CRD the chart ships in crds/:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: pgagroal-enterprise
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/Elevarq/pgAgroal-Enterprise
    targetRevision: main
    path: charts/pgagroal-enterprise
    helm:
      releaseName: pgagroal-enterprise
      # Point at an environment overlay (see deploy/gitops/overlays/).
      valueFiles:
        - ../../deploy/gitops/overlays/prod/values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: pgagroal-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      # The chart ships the CRD in crds/; let Argo apply it.
      - ServerSideApply=true

Deploy with Flux

The Flux example reads its overlay values from a ConfigMap. Create the ConfigMap from the overlay you want, then apply the GitRepository and HelmRelease:

# Provide the overlay values as a ConfigMap the HelmRelease reads:
kubectl -n pgagroal-system create configmap pgagroal-enterprise-values \
  --from-file=values.yaml=deploy/gitops/overlays/prod/values.yaml
kubectl apply -f deploy/gitops/flux/helmrelease.yaml

The HelmRelease installs the CRD on first apply and replaces it on upgrade, and pulls its environment values from the pgagroal-enterprise-values ConfigMap:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: pgagroal-enterprise
  namespace: flux-system
spec:
  interval: 10m
  url: https://github.com/Elevarq/pgAgroal-Enterprise
  ref:
    branch: main
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: pgagroal-enterprise
  namespace: pgagroal-system
spec:
  interval: 10m
  releaseName: pgagroal-enterprise
  chart:
    spec:
      chart: charts/pgagroal-enterprise
      sourceRef:
        kind: GitRepository
        name: pgagroal-enterprise
        namespace: flux-system
  install:
    createNamespace: true
    crds: Create
  upgrade:
    crds: CreateReplace
  # Inline the environment overlay values (or use valuesFrom a ConfigMap/Secret).
  valuesFrom:
    - kind: ConfigMap
      name: pgagroal-enterprise-values
      optional: false

Private registry and air-gapped

Use overlays/private-registry-values.yaml to point the operator and control-plane images at your mirror. Combine it with the air-gapped bundle, which imports images by digest:

# overlays/private-registry-values.yaml — point images at your mirror
operator:
  image:
    repository: registry.internal.example.com/elevarq/pgagroal-enterprise-operator
    tag: "0.1.0"
    pullPolicy: IfNotPresent
controlPlane:
  enabled: true
  image:
    repository: registry.internal.example.com/elevarq/pgagroal-enterprise
    tag: "0.1.0"

Layer this overlay after the environment overlay so the registry override applies on top of the dev/stage/prod settings. The full disconnected workflow is covered in Run in an air-gapped cluster.

Validate before sync

The overlays are render-validated against the chart, so you can catch a broken value before a controller applies anything. Render the chart with the overlay and inspect the output:

helm template pgagroal-enterprise charts/pgagroal-enterprise \
  -f deploy/gitops/overlays/prod/values.yaml

To validate the private-registry layering, pass both files in order — the last -f wins on conflicting keys:

helm template pgagroal-enterprise charts/pgagroal-enterprise \
  -f deploy/gitops/overlays/prod/values.yaml \
  -f deploy/gitops/overlays/private-registry-values.yaml

A clean render is the signal that the manifests are well-formed and ready for Argo or Flux to sync. This local check keeps the GitOps flow auditable: what the controller applies is exactly what you reviewed.

Upgrades

To roll out a new release, bump operator.image.tag (and controlPlane.image.tag) in the overlay and let Argo CD or Flux reconcile it. Re-run the helm template check after the bump so the change is validated before it merges.