Skip to main content
CI/CD·6 min read

Crossplane with ArgoCD — Provision Cloud Infrastructure the GitOps Way

How to combine Crossplane and ArgoCD so cloud infrastructure like S3 buckets and RDS databases is declared as Kubernetes resources and continuously synced from Git.

DT

DevOps Engineer & Technical Writer

The Problem

Terraform describes infrastructure in HCL and runs from a CI job that holds cloud credentials and a state file. That works, but it lives outside your cluster's reconciliation loop. If someone deletes a bucket by hand, nothing notices until the next terraform plan. Crossplane flips this: your cloud resources become Kubernetes objects, and a controller continuously reconciles them toward the desired state — exactly like it does for Deployments and Services. Pair it with ArgoCD and the desired state comes straight from Git.

GITOPS INFRASTRUCTURE — GIT → ARGOCD → CROSSPLANE → AWS Git Repo Claims + Apps (desired state) ArgoCD pull + sync reconcile loop KUBERNETES CLUSTER Crossplane Controllers Claim → Composition → Managed Resources provider-aws reconciles continuously AWS Cloud API S3 bucket · RDS instance · IAM role

The whole chain is declarative: Git holds the intent, ArgoCD delivers it, Crossplane turns it into real AWS resources, and the controller keeps reality matching Git.

How the Pieces Fit Together

Crossplane introduces a small vocabulary. Learn these four terms and the rest follows:

TermWhat it is
<strong>Provider</strong>A controller package (e.g. <code class="inline-code">provider-aws</code>) that knows how to talk to a cloud API
<strong>Managed Resource (MR)</strong>A low-level 1:1 mapping to a cloud resource, like <code class="inline-code">Bucket</code> or <code class="inline-code">RDSInstance</code>
<strong>Composition</strong>A template that bundles several Managed Resources into one higher-level unit
<strong>Claim (XRC)</strong>The namespaced, developer-facing request for a composed resource

A developer writes a small Claim. The Composition expands it into the Managed Resources needed. The Provider calls AWS. ArgoCD only ever syncs the Claim and the platform definitions from Git.

Installing the Provider

Crossplane itself is installed with Helm; the AWS provider is a Kubernetes resource:

apiVersion: pkg.crossplane.io/v1

kind: Provider

metadata:

name: provider-aws-s3

spec:

package: xpkg.upbound.io/upbound/provider-aws-s3:v1.5.0

Credentials are supplied through a ProviderConfig that references a Kubernetes Secret (or, better, IRSA / Workload Identity so no static keys are stored):

apiVersion: aws.upbound.io/v1beta1

kind: ProviderConfig

metadata:

name: default

spec:

credentials:

source: IRSA

Defining a Composition

The platform team authors a Composition once. It describes how an abstract "ObjectStorage" maps to real AWS resources:

apiVersion: apiextensions.crossplane.io/v1

kind: Composition

metadata:

name: objectstorage.aws

spec:

compositeTypeRef:

apiVersion: platform.devopskit.io/v1alpha1

kind: XObjectStorage

resources:

- name: bucket

base:

apiVersion: s3.aws.upbound.io/v1beta1

kind: Bucket

spec:

forProvider:

region: ap-south-1

patches:

- fromFieldPath: spec.bucketName

toFieldPath: metadata.annotations[crossplane.io/external-name]

The Developer-Facing Claim

Application teams never touch the Composition. They write a tiny Claim that lives in the app's Git folder:

apiVersion: platform.devopskit.io/v1alpha1

kind: ObjectStorageClaim

metadata:

name: invoices-bucket

namespace: billing

spec:

bucketName: devopskit-invoices-prod

compositionSelector:

matchLabels:

provider: aws

Commit this file and the bucket is on its way — no console, no CLI, no credentials in anyone's laptop.

Letting ArgoCD Deliver It

ArgoCD watches the Git path containing the Claims and keeps the cluster in sync. The Application manifest below points at the infrastructure folder:

apiVersion: argoproj.io/v1alpha1

kind: Application

metadata:

name: infra-objectstorage

namespace: argocd

spec:

project: platform

source:

repoURL: https://github.com/devopskit/infra.git

targetRevision: main

path: claims/billing

destination:

server: https://kubernetes.default.svc

namespace: billing

syncPolicy:

automated:

prune: true

selfHeal: true

With selfHeal: true, if someone deletes the bucket manually, ArgoCD and Crossplane together recreate it. With prune: true, deleting the Claim from Git deletes the bucket. Git is now the only control plane.

Checking That It Worked

Managed Resources surface their status as standard Kubernetes conditions:

kubectl get objectstorageclaim -n billing

kubectl get bucket

kubectl describe bucket devopskit-invoices-prod

A SYNCED=True READY=True pair means the cloud resource exists and matches the spec.

Common Mistakes to Avoid

  • Letting ArgoCD prune Crossplane CRDs. Add the provider and CRDs to a separate, non-pruned Application or they can be deleted out from under running resources.
  • Storing cloud keys in a Secret in Git. Use IRSA (EKS) or Workload Identity (GKE/AKS) so no static credentials ever land in a repo.
  • Putting Compositions in the same path as Claims. Keep platform definitions and developer Claims in separate Applications with different sync waves.
  • Skipping selfHeal. Without it you lose the drift-correction that makes this stack worthwhile.
  • Deleting a Claim to "clean up" in a hurry. With prune on, that destroys the real cloud resource. Treat Git deletes as production changes.

FAQ

How is Crossplane different from Terraform?

Terraform runs as an out-of-band CLI with its own state file, while Crossplane runs inside Kubernetes as a controller that continuously reconciles. That means Crossplane corrects drift automatically and exposes infrastructure as native Kubernetes resources, so the same RBAC and GitOps tooling applies to apps and infra alike.

Where is the "state" in Crossplane?

There is no separate state file. The cluster's etcd holds the desired state (the Managed Resources) and the external cloud resource is the actual state. The controller reconciles the two on every loop, which removes the state-locking and drift problems common with Terraform.

Why involve ArgoCD at all if Crossplane already reconciles?

Crossplane reconciles the cloud resource against what is in the cluster, but something has to put the Claims into the cluster from Git. ArgoCD is that something: it syncs the desired manifests from Git and self-heals them, giving you a full Git-to-cloud GitOps path.

Can one Claim create multiple AWS resources?

Yes. A Composition can bundle many Managed Resources — for example an RDS instance plus a subnet group plus a security group — behind a single Claim. The developer sees one simple object while the platform team controls the full expansion.