Get Started With Composition

On this page

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.

Tip

The guide shows how to configure composition using YAML, YAML+CEL, templated YAML, Python, and KCL. You can pick your preferred language.

An App custom resource looks like this:

 1apiVersion: example.crossplane.io/v1
 2kind: App
 3metadata:
 4  namespace: default
 5  name: my-app
 6spec:
 7  image: nginx
 8status:
 9  replicas: 2  # Copied from the Deployment's status
10  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:

 1---
 2apiVersion: apps/v1
 3kind: Deployment
 4metadata:
 5  namespace: default
 6  name: my-app-dhj3a
 7  labels:
 8    example.crossplane.io/app: my-app  # Copied from the App's name
 9spec:
10  replicas: 2
11  selector:
12    matchLabels:
13      example.crossplane.io/app: my-app  # Copied from the App's name
14  template:
15    metadata:
16      labels:
17        example.crossplane.io/app: my-app  # Copied from the App's name
18    spec:
19      containers:
20      - name: app
21        image: nginx  # Copied from the App's spec
22        ports:
23        - containerPort: 80
24---
25apiVersion: v1
26kind: Service
27metadata:
28  namespace: default
29  name: my-app-03mda
30  labels:
31    example.crossplane.io/app: my-app  # Copied from the App's name
32spec:
33  selector:
34    example.crossplane.io/app: my-app  # Copied from the App's name
35  ports:
36  - protocol: TCP
37    port: 8080
38    targetPort: 80

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

Tip

Kubernetes custom resources are just JSON REST APIs, so users can use any tool that supports REST APIs to work with apps.

Prerequisites

This guide requires:

A Kubernetes cluster with at least 2 GB of RAM
Crossplane v2 installed on the Kubernetes cluster

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.

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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
  name: apps.example.crossplane.io
spec:
  scope: Namespaced
  group: example.crossplane.io
  names:
    kind: App
    plural: apps
  versions:
  - name: v1
    served: true
    referenceable: true
    schema:
     openAPIV3Schema:
       type: object
       properties:
        spec:
          type: object
          properties:
            image:
              description: The app's OCI container image.
              type: string
          required:
          - image
        status:
          type: object
          properties:
            replicas:
              description: The number of available app replicas.
              type: integer
            address:
              description: The app's IP address.
              type: string

1kubectl apply -f https://deploy-preview-1086--crossplane.netlify.app/v2.2/manifests/get-started/composition/xrd.yaml

Check that Crossplane has established the XRD:

1kubectl get -f https://deploy-preview-1086--crossplane.netlify.app/v2.2/manifests/get-started/composition/xrd.yaml
2NAME                         ESTABLISHED   OFFERED   AGE
3apps.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.

Templated YAML is a good choice if you’re used to writing Helm charts.

Create this composition function to install templated YAML support:

1
2
3
4
5
6
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: crossplane-contrib-function-go-templating
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-go-templating:v0.9.2

1kubectl apply -f https://deploy-preview-1086--crossplane.netlify.app/v2.2/manifests/get-started/composition/fn-go-templating.yaml