function-sdk-node

[!WARNING] 🚧 This SDK is under active development and is not yet stable.

The Node.js 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.

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

Overview

Composition functions (or just functions, for short) are custom programs that template Crossplane resources. Crossplane calls composition functions to determine what resources it should create when you create a composite resource (XR). Read the concepts page to learn more about composition functions.

You can write a function to template resources using a general purpose programming language. Using a general purpose programming language allows a function to use advanced logic to template resources, like loops and conditionals. This guide explains how to write a composition function in Node.js.

[!IMPORTANT] It helps to be familiar with how composition functions work before following this guide.

Prerequisites

• Node.js v24.13.0 (LTS) or newer
• Docker Engine This guide uses OrbStack version 2.0.5
• The Crossplane CLI v2.1 or newer.

Initialize the function from a template

Use the crossplane xpkg init command to initialize a new function. When you run this command it initializes your function using a GitHub repository as a template.

crossplane xpkg init function-example https://github.com/tiagat/function-template-node

The crossplane xpkg init command creates a directory named function-xbuckets. When you run the command the new directory should look like this:

ls function-example

!!! 🚧 TBD !!!

FunctionRuntime Class

FunctionRuntime is the base class that must be extended to implement a Crossplane Function in Node.js.

Under the hood, it starts a gRPC server that communicates with Crossplane and the Crossplane CLI. The SDK abstracts away all low-level gRPC details, allowing you to focus entirely on business logic.

What It Does

When your class extends FunctionRuntime, the SDK:

• Starts a gRPC server implementing the Crossplane FunctionRunnerService
• Listens for RunFunction requests from Crossplane (in-cluster) or Crossplane CLI
• Parses and maps the incoming request into typed runtime objects
• Executes all registered @Handler() methods
• Collects and returns the resulting RunFunctionResponse

Basic Usage

import { 
  Logger, FunctionRuntime,
  Handler, Req, Res, Composite,
  Request, Response, Resource
} from '@tiagat/function-sdk-node';


class MyFunction extends FunctionRuntime {
  logger = new Logger();

  @Handler()
  example1(@Req() req: Request, @Res() res: Response): void {
    this.logger.info({ res }, 'Function Request/Response');
  }

  @Handler()
  example2(@Composite() composite?: Resource): void {
    this.logger.info({ composite }, 'Observed Composite Resource');
  }
}

new MyFunction();

Method Decorator

@Handler()

The @Handler() decorator marks a method as a entry point that will be executed when Crossplane invokes your function.

Behavior

• There is no limit to the number of methods that can be decorated with @Handler().
• All decorated methods will be executed when Crossplane calls the function one by one.
• Adding @Handler() to an async method works exactly the same way as with regular function

class MyFunction extends FunctionRuntime {

  @Handler()
  example1() {
    console.log("Fist handler executed");
  }

  @Handler()
  async example2(): Promise<void> {
    await someAsyncOperation();
    console.log("Second handler executed");
  }
}

Parameter Decorators

@Req() and @Res()

The @Req() and @Res() parameter decorators provide direct access to the underlying FunctionRequest and FunctionResponse objects.

These decorators are intended for advanced use cases where the higher-level SDK helpers are not sufficient and you need full control over the request/response lifecycle.

In most cases, you should rely on the built-in decorators and helper methods such as:

• @Composite()
• @Composed()
• @Ctx()
• etc.

However, if you:

• Need to access raw observed or desired state
• Want to manipulate the response at a low level
• Need full control over metadata, TTL, conditions, or results
• Know exactly what you are doing and require complete flexibility

You can inject the raw objects using @Req() and @Res().

@Handler()
example(@Req() req: Request, @Res() res: Response): void {
  logger.info({ req }, 'Received request');
  logger.info({ res }, 'Function Response');
}

@Ctx() and @Env()

The @Ctx() parameter decorator provides access to the current Crossplane Function Context. It allows you to read and modify contextual data that flows between functions in a Composition pipeline.

The @Env() parameter decorator provides access to the pipeline environment configuration.

It is conceptually similar to @Ctx(), but specifically designed for working with environment-level configuration data inside a Crossplane Composition pipeline.

Environment data is most commonly populated by the: function-environment-configs This function reads EnvironmentConfig resources and injects their values into the pipeline context so that subsequent functions can consume them.

  @Handler()
  example1(@Ctx() ctx: Record<string, unknown>): void {
    logger.info({ ctx }, 'Function Context');
    ctx['myValue'] = 'example';
  }

  @Handler()
  example2(@Env() env: Record<string, unknown>): void {
    logger.info({ env }, 'Environment Config');
    env['myValue'] = 'example';
  }

@Input()

The @Input() parameter decorator provides access to the function’s input block defined in the Crossplane Composition pipeline.

It allows you to retrieve strongly-typed input data that is passed to your function from the Composition.

@Handler()
example(@Input() input?: Record<string, unknown>): void {
  logger.info({ input }, 'Function Input');
}

@Composite()

The @Composite() parameter decorator provides read-only access to the Composite Resource (XR) currently being processed.

@Handler()
example(@Composite() composite?: Resource): void {
  logger.info({ composite }, 'Observed Composite Resource');
}

@Composed(name:string)

The @Composed() parameter decorator provides read-only access to the resources created by the Composition.

While @Composite() gives you the high-level XR (Composite Resource), @Composed() lets you inspect the individual composed resources that were created as part of that Composition.

@Handler()
example(@Composed('bucket') composed?: Resource): void {
  if (!composed) return;
  logger.info({ composed }, 'Observed Composed Resource');
}

Required Resources

SDK allows a function to declare additional Kubernetes resources that must be requested by Crossplane before the function is executed.

Functions can receive required resources in three ways:

1. Static Configuration : @Required(name: string) composition pipeline + parameter decorator

# composition.yaml
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: example-composition
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: ExampleClaim
  mode: Pipeline
  pipeline:
    - step: render-template
      requirements:
        requiredResources:
        - requirementName: app-config-static
          apiVersion: v1
          kind: ConfigMap
          namespace: default
          name: simple-config
      functionRef:
        name: function-example

@Handler()
example(@Required('app-config-static') required?: Resource[]): void {
  if (!required || required.length === 0) return;
  const resource = required[0];
  logger.info({ resource }, 'Required Resource (loaded by composition configuration)');
}

2. Static Request : @Handler({ required: [] }) method decorator + parameter decorator

@Handler({
  required: [
    {
      requirementName: 'app-config-dynamic-1',
      apiVersion: 'v1',
      kind: 'ConfigMap',
      namespace: 'default',
      matchName: 'app-config-dynamic'
    }
  ]
})
example(@Required('app-config-dynamic-1') required?: Resource[]): void {
  if (!required || required.length === 0) return;
  const resource = required[0];
  logger.info({ resource }, 'Required Resource (loaded by handler configuration)');
}

3. Dynamic Request : requiredResource(selector: ResourceSelector) helper function

@Handler()
example(): void {
  const selector: ResourceSelector = {
    requirementName: 'app-config-dynamic-2',
    apiVersion: 'v1',
    kind: 'ConfigMap',
    namespace: 'default',
    matchName: 'app-config-dynamic'
  };

  const required = requiredResource(selector);
  if (!required || required.length === 0) {
    return;
  }

  const resource = required[0];
  logger.info({ resource }, 'Required Resource (loaded by helper function)');
}

Create Resources

The composedResource(name: string, resource: Records<string, unknown>) helper is used to create a new composed resource and add it to the desired state.

While decorators like @Composite() and @Composed() provide read-only access to observed resources, composedResource() is the proper way to declare new resources that should be created or updated by Crossplane.

@Handler()
example(): void {
  const resource = {
    apiVersion: 's3.aws.m.upbound.io/v1beta1',
    kind: 'Bucket',
    annotations: {
      'crossplane.io/external-name:': 'bucket-primary.example.io'
    },
    spec: {
      forProvider: {
        region: 'eu-west-1'
      }
    }
  };
  const bucket = composedResource('bucket-primary', resource);
  logger.info({ bucket: bucket.resource }, 'Desired State');
}