function

README

function-sdk-go

The Go SDK for writing composition functions.

This SDK is currently a beta. We try to avoid breaking changes, but it will not have a stable API until it reaches v1.0.0. It follows the same contributing guidelines as Crossplane.

To learn how to use this SDK:

• Follow the guide to writing a composition function in Go
• Learn about how composition functions work
• Read the package documentation

If you just want to jump in and get started, consider using the function-template-go template repository.

Documentation

Overview

Package function is an SDK for building Composition Functions.

Example

// Create a response to the request passed to your RunFunction method.
rsp := response.To(req, response.DefaultTTL)

// Get the observed composite resource (XR) from the request.
oxr, _ := request.GetObservedCompositeResource(req)

// Read the desired number of widgets from our observed XR.
widgets, _ := oxr.Resource.GetInteger("spec.widgets")

// Get any existing desired composed resources from the request.
// Desired composed resources would exist if a previous Function in the
// pipeline added them.
desired, _ := request.GetDesiredComposedResources(req)

// Create a desired composed resource using unstructured data.
desired["new"] = &resource.DesiredComposed{Resource: composed.New()}
desired["new"].Resource.SetAPIVersion("example.org/v1")
desired["new"].Resource.SetKind("CoolResource")

// Set the desired composed resource's widgets to the value extracted from
// the observed XR.
desired["new"].Resource.SetInteger("spec.widgets", widgets)

// Create a desired composed resource using structured data.
// db, _ := composed.From(&v1.Instance{})
// desired["database"] = &resource.DesiredComposed{Resource: db}

// Add a label to our new desired resource, and any other.
for _, r := range desired {
	r.Resource.SetLabels(map[string]string{"coolness": "high"})
}

// Set our updated desired composed resource in the response we'll return.
if err := response.SetDesiredComposedResources(rsp, desired); err != nil {
	// You can set a custom status condition on the claim. This allows you to
	// communicate with the user. See the link below for status condition
	// guidance.
	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
	response.ConditionFalse(rsp, "FunctionSuccess", "InternalError").
		WithMessage("Something went wrong.").
		TargetCompositeAndClaim()

	// You can emit an event regarding the claim. This allows you to communicate
	// with the user. Note that events should be used sparingly and are subject
	// to throttling; see the issue below for more information.
	// https://github.com/crossplane/crossplane/issues/5802
	response.Warning(rsp, errors.New("something went wrong")).
		TargetCompositeAndClaim()
} else {
	response.ConditionTrue(rsp, "FunctionSuccess", "Success").
		TargetCompositeAndClaim()
}

j, _ := protojson.Marshal(rsp)
fmt.Println(string(j))

Output:

{"meta":{"ttl":"60s"},"desired":{"resources":{"new":{"resource":{"apiVersion":"example.org/v1","kind":"CoolResource","metadata":{"labels":{"coolness":"high"}},"spec":{"widgets":9001}}}}},"conditions":[{"type":"FunctionSuccess","status":"STATUS_CONDITION_TRUE","reason":"Success","target":"TARGET_COMPOSITE_AND_CLAIM"}]}

Index

• Constants
• func NewLogger(debug bool) (logging.Logger, error)
• func Serve(fn v1.FunctionRunnerServiceServer, o ...ServeOption) error
• type BetaServer
  • func ServeBeta(s v1.FunctionRunnerServiceServer) *BetaServer
  • func (s *BetaServer) RunFunction(ctx context.Context, req *v1beta1.RunFunctionRequest) (*v1beta1.RunFunctionResponse, error)
• type ServeOption
  • func Insecure(insecure bool) ServeOption
  • func Listen(network, address string) ServeOption
  • func MTLSCertificates(dir string) ServeOption
  • func MaxRecvMessageSize(sz int) ServeOption
• type ServeOptions

Examples

• Package

Constants

const (
	DefaultNetwork        = "tcp"
	DefaultAddress        = ":9443"
	DefaultMaxRecvMsgSize = 1024 * 1024 * 4
)

Default ServeOptions.

Functions

func NewLogger

func NewLogger(debug bool) (logging.Logger, error)

NewLogger returns a new logger.

func Serve

func Serve(fn v1.FunctionRunnerServiceServer, o ...ServeOption) error

Serve the supplied Function by creating a gRPC server and listening for RunFunctionRequests. Blocks until the server returns an error.

Types

type BetaServer

type BetaServer struct {
	v1beta1.UnimplementedFunctionRunnerServiceServer
	// contains filtered or unexported fields
}

A BetaServer is a v1beta1 FunctionRunnerServiceServer that wraps an identical v1 FunctionRunnerServiceServer. This requires the v1 and v1beta1 protos to be identical.

Functions were promoted from v1beta1 to v1 in Crossplane v1.17. Crossplane v1.16 and earlier only sends v1beta1 RunFunctionRequests. Functions should use the BetaServer for backward compatibility, to support Crossplane v1.16 and earlier.

func ServeBeta

func ServeBeta(s v1.FunctionRunnerServiceServer) *BetaServer

ServeBeta returns a v1beta1.FunctionRunnerServiceServer that wraps the suppled v1.FunctionRunnerServiceServer.

func (*BetaServer) RunFunction

func (s *BetaServer) RunFunction(ctx context.Context, req *v1beta1.RunFunctionRequest) (*v1beta1.RunFunctionResponse, error)

RunFunction calls the RunFunction method of the wrapped v1.FunctionRunnerServiceServer. It converts from v1beta1 to v1 and back by round-tripping through protobuf marshaling.

type ServeOption

type ServeOption func(o *ServeOptions) error

A ServeOption configures how a Function is served.

func Insecure

func Insecure(insecure bool) ServeOption

Insecure specifies whether this Function should be served insecurely - i.e. without mTLS authentication. This is only useful for testing and development. Crossplane will always send requests using mTLS.

func Listen

func Listen(network, address string) ServeOption

Listen configures the network, address and maximum message size on which the Function will listen for RunFunctionRequests.

func MTLSCertificates

func MTLSCertificates(dir string) ServeOption

MTLSCertificates specifies a directory from which to load mTLS certificates. The directory must contain the server certificate (tls.key and tls.crt), as well as a CA certificate (ca.crt) that will be used to authenticate clients.

func MaxRecvMessageSize

func MaxRecvMessageSize(sz int) ServeOption

MaxRecvMessageSize returns a ServeOption to set the max message size in bytes the server can receive. If this is not set, gRPC uses the default limit.

type ServeOptions

type ServeOptions struct {
	Network        string
	Address        string
	MaxRecvMsgSize int
	Credentials    credentials.TransportCredentials
}

ServeOptions configure how a Function is served.