GitOps Deployment: Kube-Prometheus-Stack with ArgoCD & Flux

kube-prometheus-stack is already declarative by nature — Prometheus configuration, alert rules, and scrape targets all live as Kubernetes custom resources. That makes it a natural fit for GitOps, but its CRDs need the same careful ordering in ArgoCD or Flux that they need with plain Helm.

Why GitOps and This Chart Fit Well

Because the Prometheus Operator already expresses monitoring configuration as CRDs — ServiceMonitor, PodMonitor, PrometheusRule, AlertmanagerConfig — there's very little translation needed to manage it through Git. The chart's own values.yaml becomes just another file under version control, reviewed the same way as application code.

The CRD Ordering Problem

Helm applies CRDs before templated resources automatically. ArgoCD and Flux don't guarantee that ordering out of the box — a sync can attempt to create a Prometheus or ServiceMonitor custom resource before its CRD exists, and the first sync fails.

The reliable fix in both tools is separating concerns: sync the chart's CRDs first (as their own Application/Kustomization, or an earlier wave), then sync the rest of the chart afterward. Retrofitting this after a failed first sync is far more painful than setting it up correctly from the start.

Deploying with an ArgoCD Application

An ArgoCD Application pointing at the Helm chart looks like any other Helm-sourced Application, with one addition — CRDs=true in syncOptions so ArgoCD applies the chart's bundled CRDs on sync rather than skipping them:

apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  source:
    repoURL: https://prometheus-community.github.io/helm-charts
    chart: kube-prometheus-stack
    targetRevision: 65.5.0
    helm:
      valueFiles:
        - values.yaml
  syncPolicy:
    syncOptions:
      - CRDs=true

Pinning targetRevision to an exact chart version keeps upgrades a deliberate, reviewed Git commit rather than something that happens silently on the next sync — see the upgrade guide for what to check before bumping it.

Deploying with Flux's HelmRelease

Flux uses a two-part setup: a HelmRepository pointing at the chart source, and a HelmRelease that references it with your values:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
spec:
  chart:
    spec:
      chart: kube-prometheus-stack
      version: 65.5.0
      sourceRef:
        kind: HelmRepository
        name: prometheus-community

Flux's Helm controller runs the equivalent of helm upgrade --install under the hood, so the same CRD caveats from the upgrade guide apply — CRDs still need explicit handling on major version bumps.

Keeping values.yaml in Git

The entire point of GitOps is that a diff to values.yaml is reviewable before it ships. Keep the file in the same repository as the Application or HelmRelease manifest, pin the chart version explicitly, and treat both as regular pull requests — resist any setup that pulls values from an external, unpinned, or mutable source, since that quietly reintroduces the same "drift without review" problem GitOps exists to prevent.

Frequently Asked Questions

Can I deploy kube-prometheus-stack with ArgoCD?

Yes — reference the Helm chart in an Application with CRDs=true in syncOptions.

What is the CRD ordering problem?

ArgoCD and Flux don't guarantee CRDs sync before custom resources by default, unlike Helm — sync CRDs first to avoid a failed initial deploy.

Can Flux deploy this chart?

Yes, via a HelmRepository and HelmRelease pair, functioning like helm upgrade --install.

Conclusion

kube-prometheus-stack works well under GitOps precisely because it's already CRD-driven — the only adjustment either tool needs is respecting CRD-before-resource ordering that Helm normally handles for you. Get that right once, pin your chart version, and upgrades become a routine, reviewable Git diff instead of a manual terminal command.