crossplane / function-sdk-go

The Go SDK for composition functions

Crossplane is a framework for building cloud native control planes without needing to write code. It has a highly extensible backend that enables you to build a control plane that can orchestrate applications and infrastructure no matter where they run, and a highly configurable frontend that puts you in control of the schema of the declarative API it offers.

Crossplane is a Cloud Native Computing Foundation project.

Get Started

Crossplane's Get Started Docs cover install and cloud provider quickstarts.

Releases

Currently maintained releases, as well as the next few upcoming releases are listed below. For more information take a look at the Crossplane release cycle documentation.

Release	Release Date	EOL
v1.13	Jul 27, 2023	May 2024
v1.14	Nov 1, 2023	Aug 2024
v1.15	Feb 15, 2024	Nov 2024
v1.16	Early May '24	Feb 2025
v1.17	Early Aug '24	May 2025
v1.18	Early Nov '24	Aug 2025

You can subscribe to the community calendar to track all release dates, and find the most recent releases on the releases page.

Roadmap

The public roadmap for Crossplane is published as a GitHub project board. Issues added to the roadmap have been triaged and identified as valuable to the community, and therefore a priority for the project that we expect to invest in.

Milestones assigned to any issues in the roadmap are intended to give a sense of overall priority and the expected order of delivery. They should be considered approximate estimations and are not a strict commitment to a specific delivery timeline.

Crossplane Roadmap

Get Involved

Crossplane is a community driven project; we welcome your contribution. To file a bug, suggest an improvement, or request a new feature please open an issue against Crossplane or the relevant provider. Refer to our contributing guide for more information on how you can help.

• Discuss Crossplane on Slack or our developer mailing list.
• Follow us on Twitter or LinkedIn, or subscribe to our newsletter.
• Contact us via Email.
• Join our regular community meetings.
• Provide feedback on our roadmap and releases board.

The Crossplane community meeting takes place every 4 weeks on Thursday at 10:00am Pacific Time. You can find the up to date meeting schedule on the Community Calendar.

Anyone who wants to discuss the direction of the project, design and implementation reviews, or raise general questions with the broader community is encouraged to join.

• Meeting link: https://zoom.us/j/425148449?pwd=NEk4N0tHWGpEazhuam1yR28yWHY5QT09
• Current agenda and past meeting notes
• Past meeting recordings
• Community Calendar

Special Interest Groups (SIG)

Each SIG collaborates in Slack and some groups have regular meetings, you can find the meetings in the Community Calendar.

• #sig-composition-environments
• #sig-composition-functions
• #sig-deletion-ordering
• #sig-devex
• #sig-e2e-testing
• #sig-observability
• #sig-observe-only
• #sig-provider-families
• #sig-secret-stores
• #sig-upjet

Adopters

A list of publicly known users of the Crossplane project can be found in ADOPTERS.md. We encourage all users of Crossplane to add themselves to this list - we want to see the community's growing success!

License

Crossplane is under the Apache 2.0 license.

function-sdk-go's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

• WARN: Unable to read vulnerability information

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

• Update codecov/codecov-action digest to e0b68c6
• Update kubernetes deps to v0.29.1 (k8s.io/api, k8s.io/apimachinery)
• Update module github.com/crossplane/crossplane-runtime to v1.15.0-rc.1
• Update aquasecurity/trivy-action action to v0.17.0
• Update dependency golang to v1.22.0
• Update dependency golangci/golangci-lint to v1.56.1
• Update module google.golang.org/grpc to v1.61.0
• Update zeebe-io/backport-action action to v2.4.1
• Update golangci/golangci-lint-action action to v4
• Update module github.com/upbound/provider-aws to v1
• 🔐 Create all rate-limited PRs at once 🔐

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update github.com/go-json-experiment/json digest to 2e55bd4
• Update github/codeql-action digest to dc021d4
• Update module github.com/bufbuild/buf to v1.29.0
• Update actions/cache action to v4
• Update github/codeql-action action to v3
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

github-actions

.github/workflows/backport.yml

• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• zeebe-io/backport-action v2.3.0@addffea45a2f0b5682f1d5ba0506f45bc18bf174
• ubuntu 22.04

.github/workflows/ci.yml

• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• actions/setup-go v5@0c52d547c9bc32b1aa3301fd7a9cb496313a4491
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• fkirc/skip-duplicate-actions v5.3.1@f75f66ce1886f00957d99748a42c724f4330bdcf
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• actions/setup-go v5@0c52d547c9bc32b1aa3301fd7a9cb496313a4491
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• golangci/golangci-lint-action v3@3a919529898de77ec3da873e3063ca4b10e7f5cc
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• actions/setup-go v5@0c52d547c9bc32b1aa3301fd7a9cb496313a4491
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• github/codeql-action v2@8b7fcbfac2aae0e6c24d9f9ebd5830b1290b18e4
• github/codeql-action v2@8b7fcbfac2aae0e6c24d9f9ebd5830b1290b18e4
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• aquasecurity/trivy-action 0.16.1@d43c1f16c00cfd3978dde6c07f4bbcf9eb6993ca
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• actions/setup-go v5@0c52d547c9bc32b1aa3301fd7a9cb496313a4491
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• actions/cache v3@e12d46a63a90f2fae62d114769bbf2a179198b5c
• codecov/codecov-action v4@c4cf8a4f03f0ac8585acb7c1b7ce3460ec15782f
• ubuntu 22.04
• ubuntu 22.04
• ubuntu 22.04
• ubuntu 22.04
• ubuntu 22.04
• ubuntu 22.04

.github/workflows/commands.yml

• xt0rted/slash-command-action v2@bf51f8f5f4ea3d58abc7eca58f77104182b23e88
• actions/github-script v7@60a0d83039c74a4aee543508d2ffcb1c3799cdea
• xt0rted/slash-command-action v2@bf51f8f5f4ea3d58abc7eca58f77104182b23e88
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• zeebe-io/backport-action v2.3.0@addffea45a2f0b5682f1d5ba0506f45bc18bf174
• ubuntu 22.04
• ubuntu 22.04

.github/workflows/promote.yml

• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• docker/login-action v3@343f7c4344506bcbf9b4de18042ae17996df046d
• ubuntu 22.04

.github/workflows/tag.yml

• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• negz/create-tag v1@39bae1e0932567a58c20dea5a1a0d18358503320
• ubuntu 22.04

gomod

go.mod

• go 1.21
• github.com/bufbuild/buf v1.28.1
• github.com/crossplane/crossplane-runtime v1.15.0-rc.0.0.20231215091746-d23a82b3a2f5
• github.com/go-json-experiment/json v0.0.0-20231013223334-54c864be5b8d@54c864be5b8d
• github.com/go-logr/logr v1.4.1
• github.com/go-logr/zapr v1.3.0
• github.com/google/go-cmp v0.6.0
• github.com/pkg/errors v0.9.1
• github.com/upbound/provider-aws v0.47.1
• go.uber.org/zap v1.26.0
• google.golang.org/grpc v1.60.1
• google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.3.0
• google.golang.org/protobuf v1.32.0
• k8s.io/api v0.29.0
• k8s.io/apimachinery v0.29.0
• k8s.io/utils v0.0.0-20240102154912-e7106e64919e@e7106e64919e
• sigs.k8s.io/yaml v1.4.0

regex

.github/workflows/ci.yml

• golang 1.21.6

.github/workflows/ci.yml

• golangci/golangci-lint 1.55.2

Makefile

• golangci/golangci-lint 1.55.2

---

• Check this box to trigger a request for Renovate to run again on this repository

How should we handle logging and errors?

What problem are you facing?

https://pkg.go.dev/github.com/crossplane/[email protected]/pkg/errors
https://pkg.go.dev/github.com/crossplane/[email protected]/pkg/logging

You can think of crossplane-runtime as a "Go SDK" of sorts for parts of Crossplane - i.e. core and providers. We have our own error and logging libraries there. Should Functions use those libraries? Use copies/aliases from this SDK? Use the stdlib or something else?

How could Crossplane help solve your problem?

We should figure out what we want to do here. I can see a case for sticking closer to the stdlib here given that now Go can do the core things our libraries were originally created to do for us (i.e. wrap errors, and emit structured logs).

Some thoughts:

• Admittedly I personally prefer the "UX" for the crossplane-runtime libraries to the stdlib alternatives.
• If stdlib is good enough for Functions, is it good enough for Crossplane now too?

Document `fieldpath` semantics

What happened?

Setting an annotation or label via SetValue using a label or annotation key with a "." is set incorrectly ie: prometheus.io.metrics

It will be set as

metadata:
  labels:
    prometheus:
      io:
        metrics: /metrics

It should result in

metadata:
  labels:
    prometheus.io.metrics: /metrics

This seems to be more of an issue with the SetValue in fieldpath Pave objects.

I understand that you can use SetAnnotations or SetLabels but this requires either merging the existing annotations together, which would often take longer than setting the fields individually, or requires knowing the full annotations or labels at the start. either way it would be nice to use SetValue this way as well. If it is not intended to be used this way, perhaps a comment suggesting alternatives would be good

How can we reproduce it?

using this composed_test file

package composed

import (
	"fmt"
	"testing"

	"sigs.k8s.io/yaml"
)

func TestSetValue(t *testing.T) {
	cd := New()
	cd.SetAPIVersion("example.org/v1")
	cd.SetKind("CoolComposedResource")

	cd.SetValue("metadata.labels.prometheus.io.metrics", "/metrics")
	cd.SetValue("metadata.labels.\"prometheus.io.url\"", "https://exampleprom.io")
	cd.SetValue("metadata.annotations.prometheus.io.metrics", "/metrics")
	cd.SetValue("metadata.annotations.\"prometheus.io.url\"", "https://exampleprom.io")

	y, _ := yaml.Marshal(cd)

	fmt.Println(string(y))
}

you will see the following output

$ go test -v ./...
=== RUN   TestSetValue
apiVersion: example.org/v1
kind: CoolComposedResource
metadata:
  annotations:
    prometheus:
      io:
        metrics: /metrics
        url: https://exampleprom.io
  labels:
    prometheus:
      io:
        metrics: /metrics
        url: https://exampleprom.io

--- PASS: TestSetValue (0.00s)
PASS
ok  	github.com/crossplane/function-sdk-go/resource/composed	0.226s

What environment did it happen in?

Crossplane version: Latest version

Use of deprecated GetNumber() method from Crossplane Runtime

What happened?

resource/composite/composite.go uses GetNumber(), which was deprecated and removed from Crossplane runtime In crossplane/crossplane-runtime@11e9468. This causes downstream functions to break if they update their go.mod.

function-sdk-go/resource/composite/composite.go

Line 312 in 0a4b30c

if f64, err := fieldpath.Pave(xr.Object).GetNumber(path); err == nil {

Handle context timeouts

What problem are you facing?

I think gRPC will propagate any deadline set by the client to the context.Context our RunFunction method is passed. It's unclear to me whether we have to check manually whether the deadline was exceeded before we run the Function, or whether gRPC will take care of that for us.

https://grpc.io/docs/what-is-grpc/core-concepts/#deadlines

How could Crossplane help solve your problem?

Determine whether we need to be concerned with cancelled deadlines, and if so perhaps add a RunFunction wrapper that handles them (i.e. by avoiding doing work we don't need to do).

Automatically `fieldpath.Pave` unstructured resources

What problem are you facing?

The Go SDK uses the composite.Unstructured and composed.Unstructured types from crossplane-runtime pretty heavily. These are light wrappers around the Kubernetes unstructured.Unstructured type (which is itself pretty much a wrapper around map[string]any). The result is an object with getters and setters for common Kubernetes object metadata (e.g. GetName()) as well as common Crossplane metadata (e.g. GetClaimReference().

These getters and setters don't allow folks to access the arbitrary data their APIs can support - for example if you create an XR that has spec.widgets you can't get/set that field without reaching into the underlying map[string]any.

How could Crossplane help solve your problem?

We have another wrapper, fieldpath.Paved, in crossplane-runtime. This allows field path based getters and setters, like SetInt("spec.widgets", 8). I think it would be handy to automatically expose such methods.

Creating a Desired Composed Resource with []map[string]interface{} fails when setting Object

What happened?

When trying to set a composed desired resource like

func GenerateS3SesConfig(desired *resource.DesiredComposed, oxr *resource.Composite){
	desired.Resource.Object = map[string]interface{}{
		"apiVersion": "s3.aws.upbound.io/v1beta1",
		"kind": "BucketServerSideEncryptionConfiguration",
		"metadata": map[string]interface{}{
			"name": oxr.Resource.GetClaimReference().Name,
			"namespace": oxr.Resource.GetClaimReference().Namespace,
		},
		"spec": map[string]interface{}{
			"deletionPolicy": "Retain",
			"forProvider": map[string]interface{}{
				"region": "us-east-2",
				"bucketSelector": map[string]interface{}{
					"matchControllerRef": true,
				},
				"rule": []map[string]interface{}{
					{
						"applyServerSideEncryptionByDefault": []map[string]interface{}{
							{
								"sseAlgorithm": "AES256",
							},
						},
					},
				},
			},
			"providerConfigRef": map[string]interface{}{
				"name": "aws-provider",
			},
		},
	}
}

The following error occurs when running crossplane beta render

crossplane: error: cannot render composite resource: pipeline step "run-example-function" returned a fatal result: cannot set desired composed resources in *v1beta1.RunFunctionResponse: cannot create new Struct from *composed.Unstructured: proto: invalid type: []map[string]interface {}

When changing the code to

	desired.Resource.SetValue("spec.rule", []map[string]interface{}{
		{
			"applyServerSideEncryptionByDefault": []map[string]interface{}{
				{
					"sseAlgorithm": "AES256",
				},
			},
		},
	})

It works with no errors.

How can we reproduce it?

What environment did it happen in?

Crossplane version:

require (
	github.com/alecthomas/kong v0.8.1
	github.com/crossplane/crossplane-runtime v1.14.0-rc.1
	github.com/crossplane/function-sdk-go v0.0.0-20231027134439-0745c2a72577
	github.com/google/go-cmp v0.6.0
	google.golang.org/protobuf v1.31.0
	k8s.io/apimachinery v0.28.3
	sigs.k8s.io/controller-tools v0.13.0
)

Improve support of typed objects

What problem are you facing?

We've been using the composition functions basically since day one. When starting with them, we had lengthy discussions how to handle the objects.

We decided to use and import the already available go structs that most providers have (provider-kubernetes, provider-helm, etc.). This makes working with the objects a lot more comfortable, as the compiler will help with type checking.

While there's a composed.From(rutnime.Object) function there's no function for the other way round e.g. composed.To() witch could marshal the composed resources directly into a typed object.

Additionally, it might make sense to change composed.From(rutnime.Object) to composed.From(resource.Managed) to avoid adding a plain k8s object to the desired state. We've had the issues before that someone added plain k8s objects without wrapping them in a objects.kubernetes.crossplane.io first. Which can lead to very annoying to debug bugs.

Also, it might be worth adding functions to response to directly add objects to the desired map.

For example:

response.AddDesiredComposedResource(resp RunFuntionResponse, o resource.Managed, name string)

Which would do the marshalling and add (or override) the given object in the desired composed objects map.

IMHO these changes would greatly improve the developer experience of the SDK. It also helps to avoid errors like here: #68

I've already implemented such typed functions in our framework: https://github.com/vshn/appcat/blob/change/xplane114/pkg/comp-functions/runtime/function_mgr.go#L282
And it's working great so far, it's already a lot better than the previous runtime.RawExtension in the FunctionIO.

How could Crossplane help solve your problem?

It already does, these are just suggestions to make it even better. :)

Rename proto/v1beta1/Resource.Resource field to improve clarity

There is a struct Resource containing field Resource. The doc says it is the json representation of the given resource. Could we rename the field to reflect that?

Automatically setup basic otel/prometheus metrics

What problem are you facing?

It would be neat if we could automatically wrap Functions with some basic observability (e.g. metrics, tracing). Ideally we'll need a format that could be consistent across Functions built in other in-demand languages - e.g. Python.

How could Crossplane help solve your problem?

There's a bunch of stuff in https://github.com/grpc-ecosystem - perhaps this SDK should start a gRPC server that uses one of the interceptors there to add at least basic Prometheus-style metrics?