kbakdev / function-go-templating

A Go templating composition function

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-name").resource.spec.widgets }}
• {{ index .context "apiextensions.crossplane.io/environment" }}
• {{ index .extraResources "some-bucket-by-name" }}

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 as well as additional 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

Note: The value of the connection secret value must be base64 encoded. This is already the case if you are referencing a key from a mananged resource's connectionDetails field. However, if you want to include a connection secret value from somewhere else, you will need to use the b64enc Sprig function:

apiVersion: meta.gotemplating.fn.crossplane.io/v1alpha1
kind: CompositeConnectionDetails
data:
  server-endpoint: {{ (index $.observed.resources "my-server").resource.status.atProvider.endpoint | b64enc }}

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.

ExtraResources

By defining one or more special ExtraResources, you can ask Crossplane to retrieve additional resources from the local cluster and make them available to your templates. See the docs for more information.

apiVersion: meta.gotemplating.fn.crossplane.io/v1alpha1
kind: ExtraResources
requirements:
  some-foo-by-name:
    # Resources can be requested either by name
    apiVersion: example.com/v1beta1
    kind: Foo
    matchName: "some-extra-foo"
  some-foo-by-labels:
    # Or by label.
    apiVersion: example.com/v1beta1
    kind: Foo
    matchLabels:
      app: my-app
  some-bar-by-a-computed-label:
    # But you can also generate them dynamically using the template, for example:
    apiVersion: example.com/v1beta1
    kind: Bar
    matchLabels:
      foo: {{ .observed.composite.resource.name }}

This will result in Crossplane retrieving the requested resources and making them available to your templates under the extraResources key, with the following format:

{
  "extraResources": {
    "some-foo-by-name": [
      // ... the requested bucket if found, empty otherwise ...
    ],
    "some-foo-by-labels": [
      // ... the requested buckets if found, empty otherwise ...
    ],
    // ... any other requested extra resources ...
  }
}

So, you can access the retrieved resources in your templates like this, for example:

{{ someExtraResources := index .extraResources "some-extra-resources-key" }}
{{- range $i, $extraResource := $someExtraResources }}
#
# Do something for each retrieved extraResource
#
{{- end }}

Additional functions

Name	Description
randomChoice	Randomly selects one of a given strings
toYaml	Marshals any object into a YAML string
fromYaml	Unmarshals a YAML string into an object
getResourceCondition	Helper function to retreive conditions of resources
getComposedResouce	Helper function to retrieve observed composed resources
getCompositeResource	Helper function to retreive the observed composite resource
setResourceNameAnnotation	Returns the special resource-name annotation with given name
include	Outputs template as a string

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