fargocd

fargocd is a Kubernetes controller that bridges FluxCD and Argo CD. It watches FluxCD HelmRelease and HelmRepository resources and projects each HelmRelease into a fully populated Argo CD Application, with ignoreDifferences rules auto-generated by rendering the chart twice with the Helm Go SDK.

The bridge works in three deployment shapes — see Design.md for details:

• in-cluster — Argo CD runs on the same cluster as the workload.
• autonomous — argocd-agent runs on the workload cluster and pushes state back to a remote principal. (See the argocd-agent docs.)
• managed — argocd-agent principal runs on a remote cluster. fargocd writes Applications into a per-cluster namespace on the principal.

Prerequisites

fargocd talks to existing FluxCD and Argo CD installations; it does not ship them.

1. Install the FluxCD HelmRelease/HelmRepository CRDs on the cluster where fargocd runs:

   kubectl create -f https://github.com/fluxcd/helm-controller/raw/v1.2.0/config/crd/bases/helm.toolkit.fluxcd.io_helmreleases.yaml
   kubectl create -f https://github.com/fluxcd/source-controller/raw/v1.5.0/config/crd/bases/source.toolkit.fluxcd.io_helmrepositories.yaml

   The actual helm-controller and source-controller Pods are not required — fargocd reads the CRDs but does its own Helm rendering.

2. Install Argo CD (or argocd-agent) on the appropriate cluster for your chosen mode.

Quick start (in-cluster mode)

fargocd run \
  --mode=in-cluster \
  --argo-namespace=argocd \
  --leader-elect

Create a HelmRepository and a HelmRelease:

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: appscode-charts
  namespace: flux-system
spec:
  type: oci
  url: oci://ghcr.io/appscode-charts
  interval: 1h
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: kubedb
  namespace: flux-system
spec:
  interval: 10m
  chart:
    spec:
      chart: kubedb
      version: v2026.2.26
      sourceRef:
        kind: HelmRepository
        name: appscode-charts
  targetNamespace: kubedb
  values:
    ace-user-roles:
      enabled: false

fargocd will:

1. Render the chart twice with the Helm SDK and diff the rendered manifests to populate application.spec.ignoreDifferences for fields that change between renders (CA bundles, generated certs, reload annotations, etc).
2. Create the Argo CD Application kubedb in the namespace running argocd-server.
3. Mirror Argo CD's sync and health state back onto HelmRelease.status.conditions.

Flags

Flag	Default	Purpose
--mode	in-cluster	in-cluster, autonomous, or managed.
--argo-kubeconfig	empty	Kubeconfig path to the Argo CD principal (required for --mode=managed).
--argo-namespace	auto	Override namespace auto-discovery. Required when argocd-server is not labelled app.kubernetes.io/name=argocd-server.
--argo-dest-server	https://kubernetes.default.svc	Application.spec.destination.server.
--argo-dest-name	empty	Application.spec.destination.name (symbolic cluster name).
--argo-project	default	Argo CD Project assigned to generated Applications.
--cluster-name	empty	Required in managed mode. Suffixes Application names so a single principal can serve many clusters without collisions.
--leader-elect	false	Enable leader election.
--metrics-bind-address	0	:8443 for HTTPS metrics, 0 to disable.
--metrics-secure	true	Serve metrics over HTTPS with WithAuthenticationAndAuthorization.
--health-probe-bind-address	:8081	Liveness/readiness probe endpoint.
--cert-dir	empty	Directory holding tls.crt/tls.key for the webhook/metrics server.
--enable-http2	false	Keep HTTP/1.1 only to avoid the HTTP/2 stream-cancel CVE family.

Multi-cluster naming

In managed mode (one Argo CD principal, many workload clusters), the generated Application name is <HelmRelease.name>-<cluster-name> so two clusters can have a kubedb release without colliding. The ACE umbrella chart is exempt because only one ACE release exists per principal.

Build, lint, test

All Make targets run inside ghcr.io/appscode/golang-dev; Docker must be running. Day-to-day, you can also build and test natively with Go ≥ 1.24:

GOFLAGS=-mod=vendor go build ./...
GOFLAGS=-mod=vendor go test ./... -short

The integration tests in pkg/ignoregen pull real OCI charts from ghcr.io/appscode-charts and are skipped under -short.

License

Apache 2.0 — see LICENSE.