App Compositions Quickstart

On this page

This document is for an unreleased version of Crossplane.

This document applies to the Crossplane master branch and not to the latest release v1.18.

In the previous quickstarts, you learn how to build and access a custom API with Crossplane geared for Cloud infrastructure (such as a bucket). Crossplane’s composition engine is equally suitable for composing resources on a Kubernetes app cluster. In this guide, you’ll learn to create a Composite Resource API that deploys multiple resources together onto a Kubernetes cluster.

Prerequisites

A Kubernetes cluster with Crossplane installed.
kubectl installed.

Create a custom application API

Use the composition feature of Crossplane to define a new Kubernetes API for deploying an application composed of a Deployment, a Service, and an Ingress. The custom API is a Kubernetes object. Below is an example of the API we’ll create.

1apiVersion: application.example.com/v1alpha1
2kind: Application
3metadata:
4  name: my-application
5spec: 
6  image: "nginx"
7  ingress:
8    enabled: false

Apply the API

Apply this XRD to create the custom application API in your Kubernetes cluster.

 1cat <<EOF | kubectl apply -f -
 2apiVersion: apiextensions.crossplane.io/v1
 3kind: CompositeResourceDefinition
 4metadata:
 5  name: xapplications.application.example.com
 6spec:
 7  group: application.example.com
 8  names:
 9    kind: XApplication
10    plural: xapplications
11  versions:
12  - name: v1alpha1
13    schema:
14      openAPIV3Schema:
15        type: object
16        properties:
17          spec:
18            type: object
19            properties:
20              image:
21                type: string
22              ingress:
23                type: object
24                properties:
25                  enabled:
26                    type: boolean
27                    default: true
28            required:
29              - image
30    served: true
31    referenceable: true
32  claimNames:
33    kind: Application
34    plural: applications
35EOF

Tip

For more details on the fields and options of Composite Resource Definitions read the XRD documentation.

View the installed XRD with kubectl get xrd.

1kubectl get xrd
2NAME                                   ESTABLISHED   OFFERED   AGE
3xapplications.application.example.com  True          True      2s

View the new custom API endpoints with kubectl api-resources | grep application

1kubectl api-resources | grep application
2applications                                     application.example.com/v1alpha1       true         Application
3xapplications                                    application.example.com/v1alpha1       false        XApplication

Create a deployment template

Define a composition that takes the API inputs and templates the underlying Kubernetes resources.

This template creates a Deployment, Service, and an Ingress.

This Composition takes the user’s container image input and optionally configures an ingress in the cluster.

Crossplane’s composition engine is flexible and supports a growing list of modules, called composition functions to drive the templatization of resources. You can use:

and more. You can find composition functions built by the community on the Upbound Marketplace. The snippet below demonstrates two of these implementations. Pick whichever you prefer and apply the Composition to your cluster.

  1cat <<EOF | kubectl apply -f -
  2apiVersion: apiextensions.crossplane.io/v1
  3kind: Composition
  4metadata:
  5  name: app-composition
  6spec:
  7  mode: Pipeline
  8  pipeline:
  9  - step: patch-and-transform
 10    functionRef:
 11      name: function-patch-and-transform
 12    input:
 13      apiVersion: pt.fn.crossplane.io/v1beta1
 14      kind: Resources
 15      resources:
 16        - name: deployment
 17          base:
 18            apiVersion: kubernetes.crossplane.io/v1alpha2
 19            kind: Object
 20            metadata:
 21              name: app-deployment
 22            spec:
 23              forProvider:
 24                manifest:
 25                  apiVersion: "apps/v1"
 26                  kind: Deployment
 27                  metadata:
 28                    namespace: default
 29                    annotations:
 30                      krm.kcl.dev/composition-resource-name: "deployment"
 31                  spec:
 32                    replicas: 3
 33                    selector:
 34                      matchLabels:
 35                        app: patch-me
 36                    template:
 37                      metadata:
 38                        labels:
 39                          app: patch-me
 40                      spec:
 41                        containers:
 42                        - name: patch-me
 43                          image: patch-me
 44                          ports:
 45                          - containerPort: 80
 46          patches:
 47            - type: FromCompositeFieldPath
 48              fromFieldPath: "metadata.name"
 49              toFieldPath: "spec.forProvider.manifest.spec.selector.matchLabels.app"
 50            - type: FromCompositeFieldPath
 51              fromFieldPath: "metadata.name"
 52              toFieldPath: "spec.forProvider.manifest.spec.template.metadata.labels.app"
 53            - type: FromCompositeFieldPath
 54              fromFieldPath: "metadata.name"
 55              toFieldPath: "spec.forProvider.manifest.spec.template.spec.containers[0].name"
 56            - type: FromCompositeFieldPath
 57              fromFieldPath: "spec.image"
 58              toFieldPath: "spec.forProvider.manifest.spec.template.spec.containers[0].image"
 59        - name: service
 60          base:
 61            apiVersion: kubernetes.crossplane.io/v1alpha2
 62            kind: Object
 63            metadata:
 64              name: app-service
 65            spec:
 66              forProvider:
 67                manifest:
 68                  apiVersion: v1
 69                  kind: Service
 70                  metadata:
 71                    name: patch-me
 72                    namespace: default
 73                  spec:
 74                    selector:
 75                      app: patch-me
 76                    ports:
 77                    - protocol: "TCP"
 78                      port: 80
 79                      targetPort: 80
 80          patches:
 81            - type: FromCompositeFieldPath
 82              fromFieldPath: "metadata.name"
 83              toFieldPath: "spec.forProvider.manifest.metadata.name"
 84              transforms:
 85              - type: string
 86                string:
 87                  type: Format
 88                  fmt: "%s-service"
 89            - type: FromCompositeFieldPath
 90              fromFieldPath: "metadata.name"
 91              toFieldPath: "spec.forProvider.manifest.spec.selector.app"
 92        - name: ingress
 93          base:
 94            apiVersion: kubernetes.crossplane.io/v1alpha2
 95            kind: Object
 96            metadata:
 97              name: app-ingress
 98            spec:
 99              forProvider:
100                manifest:
101                  apiVersion: "networking.k8s.io/v1"
102                  kind: Ingress
103                  metadata:
104                    name: patch-me
105                    namespace: default
106                  annotations:
107                    kubernetes.io/ingress.class: "alb"
108                    alb.ingress.kubernetes.io/scheme: "internet-facing"
109                    alb.ingress.kubernetes.io/target-type: "ip"
110                    alb.ingress.kubernetes.io/healthcheck-path: "/health"
111                    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'
112                    alb.ingress.kubernetes.io/target-group-attributes: "stickiness.enabled=true,stickiness.lb_cookie.duration_seconds=60"
113                  spec:
114                    rules:
115                    - http:
116                        paths:
117                        - path: "/"
118                          pathType: "Prefix"
119                          backend:
120                            service:
121                              name: patch-me
122                              port:
123                                number: 80
124          patches:
125            - type: FromCompositeFieldPath
126              fromFieldPath: "metadata.name"
127              toFieldPath: "spec.forProvider.manifest.metadata.name"
128              transforms:
129              - type: string
130                string:
131                  type: Format
132                  fmt: "%s-ingress"
133            - type: FromCompositeFieldPath
134              fromFieldPath: "metadata.name"
135              toFieldPath: "spec.forProvider.manifest.spec.rules[0].http.paths[0].backend.service.name"
136  - step: filter-composed-resources
137    functionRef:
138      name: function-cel-filter
139    input:
140      apiVersion: cel.fn.crossplane.io/v1beta1
141      kind: Filters
142      filters:
143      - name: ingress
144        expression: observed.composite.resource.spec.ingress.enabled == true
145  compositeTypeRef:
146    apiVersion: application.example.com/v1alpha1
147    kind: XApplication
148EOF

Apply this Function to install function-patch-and-transform:

1cat <<EOF | kubectl apply -f -
2apiVersion: pkg.crossplane.io/v1
3kind: Function
4metadata:
5  name: function-patch-and-transform
6spec:
7  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
8EOF

Apply this Function to install function-cel-filter:

1cat <<EOF | kubectl apply -f -
2apiVersion: pkg.crossplane.io/v1beta1
3kind: Function
4metadata:
5  name: function-cel-filter
6spec:
7  package: xpkg.upbound.io/crossplane-contrib/function-cel-filter:v0.1.1
8EOF

Tip

Read the Composition documentation for more information on configuring Compositions and all the available options.

Read the Patch and Transform function documentation for more information on how it uses patches to map user inputs to Composition resource templates.

Save the following to a file called composition-kcl.yaml locally, then apply it to your cluster:

  1apiVersion: apiextensions.crossplane.io/v1
  2kind: Composition
  3metadata:
  4  name: app-composition
  5spec:
  6  mode: Pipeline
  7  pipeline:
  8  - step: compose-kcl
  9    functionRef:
 10      name: function-kcl
 11    input:
 12      apiVersion: krm.kcl.dev/v1alpha1
 13      kind: KCLInput
 14      metadata:
 15        name: basic
 16      spec:
 17        target: Resources
 18        source: |
 19          oxr = option("params").oxr
 20          deployment = {
 21              apiVersion: "kubernetes.crossplane.io/v1alpha2"
 22              kind: "Object"
 23              metadata.name = "app-deployment"
 24              spec.forProvider.manifest = {
 25                apiVersion: "apps/v1"
 26                kind: "Deployment"
 27                metadata.namespace: "default"
 28                metadata.annotations: {
 29                  "krm.kcl.dev/composition-resource-name" = "deployment"
 30                }
 31                spec = {
 32                  replicas: 3
 33                  selector.matchLabels.app: oxr?.metadata?.name
 34                  template = {
 35                    metadata.labels.app: oxr?.metadata?.name
 36                    spec = {
 37                      containers = [{
 38                        name: oxr?.metadata?.name
 39                        image: oxr?.spec?.image
 40                        ports = [{
 41                          containerPort: 80
 42                        }]
 43                      }]
 44                    }
 45                  }
 46                }
 47              }
 48          } 
 49          service = {
 50              apiVersion: "kubernetes.crossplane.io/v1alpha2"
 51              kind: "Object"
 52              metadata.name = "app-service"
 53              metadata.annotations: {
 54                "krm.kcl.dev/composition-resource-name" = "service"
 55              }
 56              spec.forProvider.manifest = {
 57                apiVersion: "v1"
 58                kind: "Service"
 59                metadata.name: '${oxr.metadata.name}-service'
 60                metadata.namespace: "default"
 61                spec = {
 62                  selector.app: oxr?.metadata?.name
 63                  ports: [{
 64                    protocol: "TCP"
 65                    port: 80
 66                    targetPort: 80
 67                  }]
 68                }
 69              }
 70          }
 71          ingress = [{
 72              apiVersion: "kubernetes.crossplane.io/v1alpha2"
 73              kind: "Object"
 74              metadata.name = "app-ingress"
 75              metadata.annotations: {
 76                "krm.kcl.dev/composition-resource-name" = "ingress"
 77              }
 78              spec.forProvider.manifest = {
 79                apiVersion: "networking.k8s.io/v1"
 80                kind: "Ingress"
 81                metadata.name: '${oxr.metadata.name}-ingress'
 82                metadata.namespace: "default"
 83                annotations = {
 84                  "kubernetes.io/ingress.class": "alb"
 85                  "alb.ingress.kubernetes.io/scheme": "internet-facing"
 86                  "alb.ingress.kubernetes.io/target-type": "ip"
 87                  "alb.ingress.kubernetes.io/healthcheck-path": "/health"
 88                  "alb.ingress.kubernetes.io/listen-ports": '[{"HTTP": 80}]'
 89                  "alb.ingress.kubernetes.io/target-group-attributes": "stickiness.enabled=true,stickiness.lb_cookie.duration_seconds=60"
 90                }
 91                spec.rules = [{
 92                  http.paths = [{
 93                    path: "/"
 94                    pathType: "Prefix"
 95                    backend.service = {
 96                      name: oxr?.metadata?.name 
 97                      port.number: 80
 98                    }
 99                  }]
100                }]
101              }
102          }] if oxr?.spec.ingress.enabled else []
103          _items = [deployment, service]
104          _items += ingress
105          items = _items          
106  compositeTypeRef:
107    apiVersion: application.example.com/v1alpha1
108    kind: XApplication

Apply it to your cluster:

1kubectl apply -f composition-kcl.yaml

Apply this Function to install function-kcl:

1cat <<EOF | kubectl apply -f -
2apiVersion: pkg.crossplane.io/v1
3kind: Function
4metadata:
5  name: function-kcl
6spec:
7  package: xpkg.upbound.io/crossplane-contrib/function-kcl:v0.11.1
8EOF

Tip

Read the Composition documentation for more information on configuring Compositions and all the available options.

View the Composition with kubectl get composition

1kubectl get composition
2NAME              XR-KIND        XR-APIVERSION                      AGE
3app-composition   XApplication   application.example.com/v1alpha1   5s

Install and configure provider-kubernetes

This guide uses provider-kubernetes to compose resources running in the same cluster where Crossplane is installed. Install the provider in your cluster:

1cat <<EOF | kubectl apply -f -
2apiVersion: pkg.crossplane.io/v1
3kind: Provider
4metadata:
5  name: provider-kubernetes
6spec:
7  package: xpkg.upbound.io/upbound/provider-kubernetes:v0
8EOF

Configure the provider to have permission to create resources in the cluster.

 1SA=$(kubectl -n crossplane-system get sa -o name | grep provider-kubernetes | sed -e 's|serviceaccount\/|crossplane-system:|g')
 2kubectl create clusterrolebinding provider-kubernetes-admin-binding --clusterrole cluster-admin --serviceaccount="${SA}"
 3cat <<EOF | kubectl apply -f -
 4apiVersion: kubernetes.crossplane.io/v1alpha1
 5kind: ProviderConfig
 6metadata:
 7  name: default
 8spec:
 9  credentials:
10    source: InjectedIdentity
11EOF

The composition above uses provider-kubernetes to compose other resources in the same Kubernetes cluster where Crossplane’s installed. Whereas many other Crossplane providers define several high-fidelity Managed Resources, provider-kubernetes defines a kind: Object. This API type can be used to manage any Kubernetes object–not just Kubernetes core resources, but also other Custom Resources defined by any Kubernetes Operator or Controller installed on the same cluster.

Tip

Crossplane compositions natively compose Crossplane Managed Resources and provider-kubernetes is crucial for enabling Crossplane to compose other types of Kubernetes resource. In the Crossplane V2 proposal, Crossplane compositions will natively support any Kubernetes resource, not just Managed Resources.

Read the provider-kubernetes documentation on GitHub to learn about advanced configuration options.

Access the custom API

With the custom API (XRD) installed and associated to a resource template (Composition) users can access the API to create resources.

Create an Application object to create the cloud resources.

 1cat <<EOF | kubectl apply -f -
 2apiVersion: application.example.com/v1alpha1
 3kind: XApplication
 4metadata:
 5  name: my-app
 6spec: 
 7  image: "nginx"
 8  ingress:
 9    enabled: true
10EOF

View the resource with kubectl get xapplications.

1kubectl get xapplications
2NAME    SYNCED   READY   COMPOSITION       AGE
3my-app  True     True    app-composition   14s

This object is a Crossplane composite resource (also called an XR).
It’s a single object representing the collection of resources created from the Composition template.

View the individual resources with kubectl get managed

1kubectl get managed
2NAME                                             KIND         PROVIDERCONFIG   SYNCED   READY   AGE
3object.kubernetes.crossplane.io/app-deployment   Deployment   default          True     True    45s
4object.kubernetes.crossplane.io/app-ingress      Ingress      default          True     True    45s
5object.kubernetes.crossplane.io/app-service      Service      default          True     True    45s

Delete the resources with kubectl delete xapplication.

1kubectl delete xapplication my-app
2xapplication.application.example.com "my-app" deleted

Verify Crossplane deleted the resources with kubectl get managed

1kubectl get managed
2No resources found