Skip to main content

Get Started With Composition

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, templated YAML, Python, and KCL. You can pick your preferred language.

An App custom resource looks like this:

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:

---
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.

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
  • The Crossplane v2 preview [installed on the Kubernetes cluster]

Create the custom resource​

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

  1. Define the schema of the App custom resource
  2. Install the function you want to use to configure how Crossplane composes apps
  3. 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).

apiVersion: apiextensions.crossplane.io/v2alpha1
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

Save the XRD as xrd.yaml and apply it:

kubectl apply -f xrd.yaml

Check that Crossplane has established the XRD:

kubectl get -f 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.

YAML is a good choice for small, static compositions. It doesn't support loops or conditionals.

Create this composition function to install YAML support:

apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
  name: crossplane-contrib-function-patch-and-transform
spec:
  package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2

Save the function as fn.yaml and apply it:

kubectl apply -f fn.yaml

Check that Crossplane installed the function:

kubectl get -f fn.yaml
NAME                                              INSTALLED   HEALTHY   PACKAGE                                                                     AGE
crossplane-contrib-function-patch-and-transform   True        True      xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2   10s

Configure the composition​

A composition tells Crossplane what functions to call when you create or update a composite resource (XR).

Create a composition to tell Crossplane what to do when you create or update an App XR.

Create this composition to use YAML to configure Crossplane:

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: app-yaml
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: App
  mode: Pipeline
  pipeline:
  - step: create-deployment-and-service
    functionRef:
      name: crossplane-contrib-function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      resources:
      - name: deployment
        base:
          apiVersion: apps/v1
          kind: Deployment
          spec:
            replicas: 2
            template:
              spec:
                containers:
                - name: app
                  ports:
                  - containerPort: 80
        patches:
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: metadata.labels[example.crossplane.io/app]
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: spec.selector.matchLabels[example.crossplane.io/app]
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: spec.template.metadata.labels[example.crossplane.io/app]
        - type: FromCompositeFieldPath
          fromFieldPath: spec.image
          toFieldPath: spec.template.spec.containers[0].image
        - type: ToCompositeFieldPath
          fromFieldPath: status.availableReplicas
          toFieldPath: status.replicas
        readinessChecks:
        - type: MatchCondition
          matchCondition:
            type: Available
            status: "True"
      - name: service
        base:
          apiVersion: v1
          kind: Service
          spec:
            ports:
            - protocol: TCP
              port: 8080
              targetPort: 80
        patches:
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: metadata.labels[example.crossplane.io/app]
        - type: FromCompositeFieldPath
          fromFieldPath: metadata.name
          toFieldPath: spec.selector[example.crossplane.io/app]
        - type: ToCompositeFieldPath
          fromFieldPath: spec.clusterIP
          toFieldPath: status.address
        readinessChecks:
        - type: NonEmpty
          fieldPath: spec.clusterIP

Save the composition as composition.yaml and apply it:

kubectl apply -f composition.yaml

A composition can include multiple functions.

Functions can change the results of earlier functions in the pipeline. Crossplane uses the result returned by the last function.

tip

If you edit this composition to include a different kind of resource you might need to grant Crossplane access to compose it. Read [the composition documentation] to learn how to grant Crossplane access.

Use the custom resource​

Crossplane now understands App custom resources.

Create an App:

apiVersion: example.crossplane.io/v1
kind: App
metadata:
  namespace: default
  name: my-app
spec:
  image: nginx

Save the App as app.yaml and apply it:

kubectl apply -f app.yaml

Check that the App is ready:

kubectl get -f app.yaml
NAME     SYNCED   READY   COMPOSITION   AGE
my-app   True     True    app-yaml      56s
note

The COMPOSITION column shows what composition the App is using.

You can create multiple compositions for each kind of XR. [Read the XR page] to learn how to select which composition Crossplane uses.

Check that Crossplane created a Deployment and a Service:

kubectl get deploy,service -l example.crossplane.io/app=my-app
NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/my-app-2r2rk   2/2     2            2           11m

NAME                   TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
service/my-app-xfkzg   ClusterIP   10.96.148.56   <none>        8080/TCP   11m
tip

Use kubectl edit -f app.yaml to edit the App's image. Crossplane updates the Deployment's image to match.

Delete the App.

kubectl delete -f app.yaml

When you delete the App, Crossplane deletes the Deployment and Service.

Next steps​

Managed resources (MRs) are ready-made Kubernetes custom resources.

Crossplane has an extensive library of managed resources you can use to manage almost any cloud provider, or cloud native software.

[Get started with managed resources] to learn more about them.

You can use MRs with composition. Try updating your App composition to include an MR.