function-go-templating

README

function-go-templating

This composition function allows you to compose Crossplane resources using Go templates. If you've written a Helm chart before, using this function will be a familiar experience.

Here's an example:

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: example
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1beta1
    kind: XR
  mode: Pipeline
  pipeline:
  - step: create-a-bucket
    functionRef:
      name: function-go-templating
    input:
      apiVersion: gotemplating.fn.crossplane.io/v1beta1
      kind: GoTemplate
      source: Inline
      inline:
        template: |
          apiVersion: s3.aws.upbound.io/v1beta1
          kind: Bucket
          metadata:
            annotations:
              gotemplating.fn.crossplane.io/composition-resource-name: bucket
          spec:
            forProvider:
              region: {{ .observed.composite.resource.spec.region }}
  - step: automatically-detect-ready-composed-resources
    functionRef:
      name: function-auto-ready

Using this function

This function can load templates from two sources: Inline and FileSystem.

Use the Inline source to specify a simple template inline in your Composition. Multiple YAML manifests can be specified using the --- document separator.

Use the FileSystem source to specify a directory of templates. The FileSystem source treats all files under the specified directory as templates.

The templates are passed a RunFunctionRequest as data. This means that you can access the composite resource, any composed resources, and the function pipeline context using notation like:

• {{ .observed.composite.resource.metadata.name }}
• {{ .desired.composite.resource.status.widgets }}
• {{ (index .desired.composed.resource "resource-name").spec.widgets }}
• {{ index .context "apiextensions.crossplane.io/environment" }}

This function supports all of Go's built-in template functions. The above examples use the index function to access keys like resource-name that contain periods, hyphens and other special characters. Like Helm, this function also supports Sprig template functions.

To return desired composite resource connection details, include a template that produces the special CompositeConnectionDetails resource:

apiVersion: meta.gotemplating.fn.crossplane.io/v1alpha1
kind: CompositeConnectionDetails
data:
  connection-secret-key: connection-secret-value

To mark a desired composed resource as ready, use the gotemplating.fn.crossplane.io/ready annotation:

apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
  annotations:
    gotemplating.fn.crossplane.io/composition-resource-name: bucket
    gotemplating.fn.crossplane.io/ready: True
spec: {}

See the example directory for examples that you can run locally using the Crossplane CLI:

$ crossplane beta render xr.yaml composition.yaml functions.yaml

See the composition functions documentation to learn more about crossplane beta render.

Developing this function

This function uses Go, Docker, and the Crossplane CLI to build functions.

# Run code generation - see input/generate.go
$ go generate ./...

# Run tests - see fn_test.go
$ go test ./...

# Build the function's runtime image - see Dockerfile
$ docker build . --tag=runtime

# Build a function package - see package/crossplane.yaml
$ crossplane xpkg build -f package --embed-runtime-image=runtime

Documentation

Overview

Package main implements a Composition Function.