Get Started With Composition - Crossplane

This guide shows how to create a new kind of custom resource named App. When a user calls the custom resource API to create an App, Crossplane creates a Deployment and a Service.

Crossplane calls this composition. The App is composed of the Deployment and the Service.

{{<hint "tip">}} The guide shows how to configure composition using YAML, YAML+CEL, templated YAML, Python, and KCL. You can pick your preferred language. {{</hint>}}

An App custom resource looks like this:

yaml

apiVersion: example.crossplane.io/v1
kind: App
metadata:
  namespace: default
  name: my-app
spec:
  image: nginx
status:
  replicas: 2  # Copied from the Deployment's status
  address: 10.0.0.1  # Copied from the Service's status

The App is the custom API Crossplane users use to configure an app.

When users create an App Crossplane creates this Deployment and Service:

yaml

---
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: default
  name: my-app-dhj3a
  labels:
    example.crossplane.io/app: my-app  # Copied from the App's name
spec:
  replicas: 2
  selector:
    matchLabels:
      example.crossplane.io/app: my-app  # Copied from the App's name
  template:
    metadata:
      labels:
        example.crossplane.io/app: my-app  # Copied from the App's name
    spec:
      containers:
      - name: app
        image: nginx  # Copied from the App's spec
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  namespace: default
  name: my-app-03mda
  labels:
    example.crossplane.io/app: my-app  # Copied from the App's name
spec:
  selector:
    example.crossplane.io/app: my-app  # Copied from the App's name
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 80

Crossplane builds on Kubernetes, so users can use kubectl or any other tool from the Kubernetes ecosystem to work with apps.

{{<hint "tip">}} Kubernetes custom resources are just JSON REST APIs, so users can use any tool that supports REST APIs to work with apps. {{</hint>}}

Prerequisites

This guide requires:

A Kubernetes cluster with at least 2 GB of RAM
Crossplane v2 [installed on the Kubernetes cluster]({{<ref "install">}})

Create the custom resource

Follow these steps to create a new kind of custom resource using Crossplane:

Define the schema of the App custom resource
Install the function you want to use to configure how Crossplane composes apps
Configure how Crossplane composes apps

After you complete these steps you can use the new App custom resource.

Define the schema

Crossplane calls a custom resource that's powered by composition a composite resource, or XR.

{{<hint "note">}} Kubernetes calls user-defined API resources custom resources.

Crossplane calls user-defined API resources that use composition composite resources.

A composite resource is a kind of custom resource. {{</hint>}}

Create this composite resource definition (XRD) to define the schema of the new App composite resource (XR).

Check that Crossplane has established the XRD:

shell

kubectl get -f {{< manifest-url path="get-started/composition/xrd.yaml" >}}
NAME                         ESTABLISHED   OFFERED   AGE
apps.example.crossplane.io   True                    21s

Now that Crossplane has established the XRD, Kubernetes is serving API requests for the new App XR.

Crossplane now knows it's responsible for the new App XR, but it doesn't know what to do when you create or update one. You tell Crossplane what to do by installing a function and configuring a composition.

Install the function

You can use different composition functions to configure what Crossplane does when someone creates or updates a composite resource (XR). Composition functions are like configuration language plugins.

Pick what language to use to configure how Crossplane turns an App XR into a Deployment and a Service.

{{< tab "Templated YAML" >}} Templated YAML is a good choice if you're used to writing Helm charts.

Create this composition function to install templated YAML support:

{{< manifest path="get-started/composition/fn-go-templating.yaml" >}}