Crossplane First Look: What Most People Get Wrong (and How to Get it Right)

Starting at the bottom layer in the diagram, we have:

• Cloud provider infrastructure and services are all of the resources you think of when you go to your cloud provider of choice and browse the available services they offer, such as Amazon S3 buckets, Google CloudSQL database, Azure AKS clusters, etc. These exist in the real world outside of Crossplane.
• Managed resources are the next layer up and are how Crossplane brings this real world infrastructure into the control plane to expose them as extensions to the Kubernetes API. Much like Kubernetes has built-in objects for Pod, ConfigMap and Deployment, Crossplane exposes objects for S3, CloudSQL, AKS, etc.
• Composite resources are built on top of managed resources by the platform engineer. They compose together multiple resources along with configuration and policy into their own custom abstraction or API that is then exposed to their developers for self-service access to infrastructure.
• Claims are the highest layer of functionality and are what the end user developers work with directly. When they need infrastructure alongside their applications, they simply create a claim and the underlying layers will ensure a real-world instance is provisioned and ready for consumption.

Now that we have cleared up the relationships between the key concepts of Crossplane, we’ll leave you with another tip for successfully adopting this resource model. Crossplane is all about extending the control plane with new types that represent real-world infrastructure and services. Similarly, the composite resources that you define for your platform also extend the surface area of the control plane’s API, so it’s helpful to also think of these abstractions as first-class citizens of the API too,  just like Pods and ConfigMaps.

Getting Our Hands Dirty

One of the most effective ways to start internalizing these concepts is to see them in action by trying out Crossplane for yourself. The Crossplane documentation has a getting started guide, which walks you through a practical exercise that uses all the layers of functionality we just explored together.

Let’s break down what you will have accomplished by the end of this guide:

• Install Crossplane into your cluster to extend the control plane with infrastructure management capabilities
• Connect the control plane to your cloud provider of choice so it can provision and manage resources in the cloud on your behalf
• Define a new custom abstraction for Postgres that composes together infrastructure resources and exposes them as a simple declarative API for your developers
• Provision a new Postgres instance using the new API you defined, as well as an application that consumes this new database
   

One important yet often overlooked nuance of this simple flow is that it blends together a couple of distinct personas. Crossplane supports a strong separation of concerns between the platform builder and the platform consumer. The builder has full permissions to configure and compose the granular resources into abstractions as part of an API, while the consumer has limited access to just these APIs, allowing them to provision new infrastructure for their applications according to the guardrails that their platform builder specified.  It is helpful to be mindful of this separation and multiple personas when first getting your hands dirty with Crospslane within this streamlined flow.

When it Doesn’t Work out as Planned

Configuring cloud provider infrastructure and services can be a complicated task that doesn’t always result in success on the first attempt.  We’ve seen new users sometimes struggle with identifying the root cause of runtime issues they encounter while building their platforms, so we wanted to share a few tips to help you get to the bottom of any problems, should they arise.

1. Status and conditions — Crossplane has a very consistent resource model for all objects within the control plane, so you can expect every resource to have a status section that will give you up-to-date details about the most recent observed state from the real world.  This status section should be your first place to check for errors, especially the conditions list, which can give you insight into why a resource isn’t provisioning or getting to a “ready” state.
2. Events tell a story — Like many well-behaved Kubernetes objects, all Crossplane objects will emit events that detail noteworthy milestones within its life cycle.  These events will tell a story of the history of the object and often help you understand the most recent action taken and the result.
3. Follow the chain of references — We saw earlier that Crossplane has multiple “layers.” One of the most important troubleshooting concepts is that you sometimes need to follow the references between the layers to get to the root cause.  For instance, starting with the developer- facing claim, you often need to check the composite resource that it references, and subsequently the managed resources that it is composed of.  You should always try to follow this chain of references, like peeling back the layers of an onion, to get deeper insight into the objects within lower layers of Crossplane’s layered functionality.