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.
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:
| Term | What 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
pruneon, 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.