Kratix Ep 5: ArgoCD GitOps Integration

1. The Separation of State (WHAT & WHY)

#

In our E-Commerce scenario, Kratix pushes the generated Redis YAML to a State Store (e.g., a GitHub repository named kratix-state).

When you (the Platform Engineer) register a Worker Cluster with Kratix (which you do from the Platform Cluster), you create a Destination object. This object tells Kratix exactly where to put the files for this specific cluster.

# This is executed ONLY on the Platform Cluster
apiVersion: platform.kratix.io/v1alpha1
kind: Destination
metadata:
  name: worker-prod-us-east
  labels:
    environment: production
spec:
  filepath:
    # Kratix will commit YAML to this directory in GitHub
    repo: https://github.com/acmecorp/kratix-state.git
    path: clusters/prod-us-east/

When the E-Commerce Developer requests Redis, the Kratix Pipeline finishes and commits the StatefulSet YAML directly into the clusters/prod-us-east/ directory in the kratix-state repository.

Our goal now is to tell ArgoCD (which will be running on the Worker cluster) to monitor that exact directory and apply any changes it finds.

2. Installing ArgoCD (WHERE)

#

First, you must switch your kubectl context to your Worker Cluster (e.g., prod-us-east). Everything in this episode happens on the Worker Cluster.

Install the core ArgoCD components:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Wait a few moments for the pods to initialize and become ready:

kubectl get pods -n argocd --watch

3. Creating the ArgoCD Application (HOW)

#

ArgoCD uses a Custom Resource called an Application to track Git repositories.

We need to create an Application that explicitly tells ArgoCD: “Watch the kratix-state repository, look specifically inside the clusters/prod-us-east/ directory, and apply whatever YAML you find there into this cluster.”

Create a file named kratix-sync.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kratix-workloads
  namespace: argocd
spec:
  project: default
  
  # 1. The Source: The Kratix State Store
  source:
    repoURL: 'https://github.com/acmecorp/kratix-state.git'
    targetRevision: HEAD
    path: clusters/prod-us-east/

  # 2. The Destination: The local Worker Cluster
  destination:
    # This URL is the internal Kubernetes API address. It tells ArgoCD to deploy to the cluster it is currently running on.
    server: 'https://kubernetes.default.svc'
    # NOTE: Do not hardcode a namespace here. Kratix payloads often contain 
    # resources meant for many different namespaces, and Kratix defines those namespaces in the YAML.
  
  # 3. The Sync Policy
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply this configuration to the Worker Cluster:

kubectl apply -f kratix-sync.yaml

If your kratix-state repository is public, ArgoCD will immediately begin syncing. (If it is a private repository, which it should be in production, you must first provide ArgoCD with a GitHub Deploy Key or Personal Access Token via a Kubernetes Secret).

4. The End-to-End Workflow (WHEN)

#

You have now successfully wired the two halves of the Kratix architecture together. Let’s walk through the full lifecycle of the E-Commerce database request to ensure we understand exactly when things happen:

1. The Request (WHEN): The E-Commerce developer runs kubectl apply -f my-redis.yaml on the Platform Cluster.
2. The Pipeline: Kratix instantly detects the Redis claim, boots the Pipeline container, and the script generates a Kubernetes StatefulSet and Service.
3. The Push: Kratix connects to GitHub, authenticates, and commits the StatefulSet YAML into clusters/prod-us-east/redis-my-redis.yaml.
4. The Pull: Within 3 minutes (ArgoCD’s default polling interval), ArgoCD on the Worker Cluster detects the new commit.
5. The Deployment: ArgoCD pulls the YAML and applies it to the Worker Cluster’s API. The physical Redis database begins booting.

Handling Deletions Securely

#

What happens when the E-Commerce team is finished with the project and deletes their database request?

1. The developer runs kubectl delete redis my-redis on the Platform Cluster.
2. Kratix detects the deletion event. It automatically connects to GitHub and deletes the YAML files from the clusters/prod-us-east/ directory.
3. ArgoCD detects that the files were removed from Git.
4. Because we explicitly set prune: true in the ArgoCD sync policy earlier, ArgoCD executes a kubectl delete on the local Worker Cluster, destroying the Redis database and freeing up the cluster resources.

The entire lifecycle—from creation to deletion—is perfectly synchronized without the Platform Cluster ever directly touching the Worker Cluster.

Conclusion & Next Steps

#

By integrating ArgoCD with Kratix, you have built a massively scalable, deeply secure architecture. The Platform Cluster is an impenetrable fortress that only accepts API requests, and the Worker Clusters autonomously pull their workloads from Git. You have successfully implemented the GitOps deployment pattern.

However, ArgoCD is not the only player in the GitOps space. If you prefer FluxCD over ArgoCD, the architecture is conceptually identical, but it uses completely different Custom Resources (GitRepository and Kustomization).

In Episode 6: FluxCD GitOps Integration, we will briefly cover how to swap out ArgoCD for Flux, providing a quick guide for teams that are already deeply embedded in the Weaveworks ecosystem.