This document demonstrates how to use the Crossplane Function SDK for TypeScript to build your own functions.
npm install @crossplane-org/function-sdk-typescriptA function is a plain function handed the request and a response to fill in:
import {
Resource,
normal,
type ComposeFunction,
} from "@crossplane-org/function-sdk-typescript";
export const compose: ComposeFunction = (req, rsp, logger) => {
logger?.info("Processing function request");
rsp.desired.resources["my-config"] = Resource.fromJSON({
resource: {
apiVersion: "v1",
kind: "ConfigMap",
metadata: { name: "my-config" },
data: { key: "value" },
},
});
normal(rsp, "Function completed successfully");
return rsp;
};The response is already initialized from the request, so there is no need to call
to(), and its desired state is guaranteed to be present — you can write
rsp.desired.resources[name] without a non-null assertion. Return the response you
want sent; returning it is required, so forgetting is a compile error rather than an
empty response at runtime.
Note that when the request already carries desired state — as it does for every
function after the first in a pipeline — rsp.desired is the same object as
req.desired, not a copy.
If you would rather implement the full interface, serve() accepts that too:
import {
FunctionHandler,
RunFunctionRequest,
RunFunctionResponse,
Resource,
to,
normal,
fatal,
getObservedCompositeResource,
getDesiredCompositeResource,
getDesiredComposedResources,
setDesiredComposedResources,
} from "@crossplane-org/function-sdk-typescript";
import type { Logger } from "@crossplane-org/function-sdk-typescript";
export class MyFunction implements FunctionHandler {
async RunFunction(
req: RunFunctionRequest,
logger?: Logger,
): Promise<RunFunctionResponse> {
// Initialize response from request
const rsp = to(req);
try {
// Get observed and desired state
const oxr = getObservedCompositeResource(req);
const dxr = getDesiredCompositeResource(req);
let dcds = getDesiredComposedResources(req);
logger?.info("Processing function request");
// Your function logic here
// Example: Create a Deployment resource
dcds["my-deployment"] = Resource.fromJSON({
resource: {
apiVersion: "apps/v1",
kind: "Deployment",
metadata: {
name: "my-deployment",
namespace: "default",
},
spec: {
replicas: 3,
selector: {
matchLabels: {
app: "my-app",
},
},
template: {
metadata: {
labels: {
app: "my-app",
},
},
spec: {
containers: [
{
name: "my-container",
image: "my-image:latest",
},
],
},
},
},
},
});
// Update response with desired composed resources
setDesiredComposedResources(rsp, dcds);
normal(rsp, "Function completed successfully");
return rsp;
} catch (error) {
logger?.error({ error }, "Function failed");
fatal(rsp, error instanceof Error ? error.message : String(error));
return rsp;
}
}
}Create a main.ts that hands your function to serve():
#!/usr/bin/env node
import { serve } from "@crossplane-org/function-sdk-typescript";
import { compose } from "./my-function.js";
serve(compose);That is the whole entry point. serve() parses the standard function flags, builds a
logger from --debug, starts the gRPC server, and shuts it down cleanly on SIGINT
and SIGTERM. It accepts either a ComposeFunction or a FunctionHandler.
Every function served this way accepts the same flags and environment variables, so tooling can configure every function in a pipeline the same way. A flag given on the command line wins over its environment variable, which wins over the default:
| Flag | Env | Default | Description |
|---|---|---|---|
--address |
ADDRESS |
0.0.0.0:9443 |
gRPC listen address |
--debug / -d |
DEBUG |
false |
Emit debug logs |
--insecure |
INSECURE |
false |
Run without mTLS |
--tls-server-certs-dir |
TLS_SERVER_CERTS_DIR |
/tls/server |
mTLS certificate directory |
--max-recv-message-size |
MAX_RECV_MESSAGE_SIZE, MAX_GRPC_MESSAGE_SIZE |
4 |
Max received gRPC message size in MB |
--max-send-message-size |
MAX_SEND_MESSAGE_SIZE |
the receive size | Max sent gRPC message size in MB |
--help / -h |
— | false |
Show help text |
Boolean environment variables are on when set to true or 1. An empty value — a
variable set to "", or an empty argument — is treated as unset, so it falls through to
the default rather than reaching the server. Message sizes must be whole numbers of
megabytes between 1 and 2047; anything else is rejected at startup.
A function rejects any request larger than its receive limit, 4 MB by default. A composite resource with many composed resources can outgrow that, since every request carries the observed and desired state of all of them. Raise it with any of:
--max-recv-message-size 16MAX_RECV_MESSAGE_SIZE=16MAX_GRPC_MESSAGE_SIZE=16
MAX_GRPC_MESSAGE_SIZE is an alias for MAX_RECV_MESSAGE_SIZE, meant for tooling or
platform teams that set one size across every function in a pipeline. Because the send
limit defaults to the receive limit, it raises both. If both variables are set,
MAX_RECV_MESSAGE_SIZE wins.
A size must be a whole number of megabytes between 1 and 2047, the most gRPC's message
size channel arguments can hold; 8, 0008 and 2047 are accepted, 0, 8.5, 8MB
and 4096 are rejected at startup.
Functions run in pods that Crossplane manages, so set the variable through a
DeploymentRuntimeConfig:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
metadata:
name: large-messages
spec:
deploymentTemplate:
spec:
selector: {}
template:
spec:
containers:
- name: package-runtime
env:
- name: MAX_GRPC_MESSAGE_SIZE
value: "16"Three behaviour changes affect functions that call serve() without changing any code:
- Sent messages are now limited. Earlier versions left the send limit at the
grpc-js default, which is unlimited. It now defaults to the receive limit, 4 MB
unless raised. A function that returns responses larger than that must raise
--max-send-message-size/MAX_SEND_MESSAGE_SIZE, or the receive limit. - The standard environment variables are read. Earlier versions of
serve()only read flags. A pod that already setsADDRESS,DEBUG,INSECURE,TLS_SERVER_CERTS_DIRor one of the message size variables for some other reason will now pick it up. An empty value is treated as unset, sovalue: ""in a pod spec falls back to the default rather than replacing it. - A function that cannot bind its address exits 1. Earlier versions logged the bind error and carried on with nothing listening. The container now crashes instead, so the failure is visible to Kubernetes.
serve() takes an options object for the cases where the defaults do not fit:
serve(compose, {
name: "my-function", // Program name shown in --help
argv: ["--insecure"], // Defaults to process.argv.slice(2)
cli: myCLI, // A CLI declaring flags of your own (see below)
logger: myLogger, // Defaults to a pino logger built from --debug
serverOptions: { insecure: true } // Overrides applied on top of the parsed flags
});# Build your function
npm run build
# Run locally (insecure mode for testing)
node dist/main.js --insecure --debug
# Run with mTLS (production)
node dist/main.js --tls-server-certs-dir /path/to/certsIf your function needs its own command-line flags or environment variables, declare
them with the CLI class and hand it to serve(). serve() is built on the same
class, so your function keeps every standard flag, and --help lists yours alongside
them:
#!/usr/bin/env node
import { CLI, serve, type ComposeFunction } from "@crossplane-org/function-sdk-typescript";
const cli = new CLI({
flags: {
"cache-size": {
type: "string",
default: "100",
env: "CACHE_SIZE",
description: "Number of entries to cache.",
},
"verbose": {
type: "boolean",
short: "v",
env: "VERBOSE",
description: "Enable verbose output.",
},
},
});
const compose: ComposeFunction = (req, rsp) => {
// serve() parses the CLI before the server starts, so its values are
// always available by the time a request arrives.
const cacheSize = Number(cli.values["cache-size"]);
// ...
return rsp;
};
serve(compose, { cli });serve() parses the CLI, reports bad flags as usage errors, and handles --help. If you
need the values before the server starts, call cli.parse() yourself first; serve()
then uses those values rather than parsing again, though errors thrown by your own
parse() call are yours to report.
Each custom flag supports:
type—"string"or"boolean".default— Value used when neither the CLI argument nor the env var is set. A boolean flag can only default tofalse, since it could never be turned off.short— Single-character alias (e.g.-v).env— Environment variable name. Resolution order: CLI argument > env var > default.envAliases— Further environment variables, checked in order whenenvis unset.description— Shown in--helpoutput.
The constructor throws if a custom flag reuses a standard flag's name or any other
flag's short alias, has a default whose type doesn't match its type, or is a boolean
flag defaulting to true.
serve() is the recommended entry point, but the pieces it uses are exported, so a
function that needs to own the process — extra flags, a different logger, its own
signal handling — can assemble them directly:
#!/usr/bin/env node
import { pino } from "pino";
import {
FunctionRunner,
newGrpcServer,
parseArgs,
startServer,
type ServerOptions,
} from "@crossplane-org/function-sdk-typescript";
import { MyFunction } from "./my-function.js";
// parseArgs handles the standard flags, so your own parser only has to add to them.
const { help, ...opts } = parseArgs(process.argv.slice(2));
const logger = pino({
level: opts.debug ? "debug" : "info",
formatters: {
level: (label) => ({ severity: label.toUpperCase() }),
},
});
const server = newGrpcServer(new FunctionRunner(new MyFunction(), logger), logger);
// Binding finishes after startServer returns, so a failure such as the port
// being in use arrives through the optional callback. Without one it is only
// logged.
startServer(server, opts as ServerOptions, logger, () => process.exit(1));
process.on("SIGTERM", () => {
server.tryShutdown(() => process.exit(0));
});The SDK works well with the kubernetes-models library for type-safe Kubernetes resource creation:
import { Pod } from "kubernetes-models/v1";
import { Resource } from "@crossplane-org/function-sdk-typescript";
const pod = new Pod({
metadata: {
name: "my-pod",
namespace: "default",
},
spec: {
containers: [
{
name: "app",
image: "nginx:latest",
},
],
},
});
pod.validate();
dcds["my-pod"] = Resource.fromJSON({ resource: pod.toJSON() });You can update the status of the composite resource:
import { setDesiredCompositeStatus } from "@crossplane-org/function-sdk-typescript";
setDesiredCompositeStatus({
rsp,
status: {
ready: true,
message: "All resources created successfully",
},
});Pass data between functions in a pipeline using context:
import { getContextKey, setContextKey } from "@crossplane-org/function-sdk-typescript";
// Read context from previous function
const [resourceId, exists] = getContextKey(req, "resourceId");
if (exists) {
logger?.info({ resourceId }, "Found resource ID from previous function");
}
// Set context for next function
setContextKey(rsp, "resourceId", "my-resource-123");
setContextKey(rsp, "status", { created: true, ready: false });Access credentials passed to the function:
import { getCredentials } from "@crossplane-org/function-sdk-typescript";
try {
const creds = getCredentials(req, "aws-credentials");
const accessKey = creds.credentialData?.data["access-key-id"];
const secretKey = creds.credentialData?.data["secret-access-key"];
if (accessKey && secretKey) {
logger?.info("Successfully retrieved AWS credentials");
// Use credentials to interact with AWS
}
} catch (error) {
fatal(rsp, `Failed to get credentials: ${error.message}`);
}Use the result helpers to report errors and warnings:
import { fatal, warning, normal } from "@crossplane-org/function-sdk-typescript";
// Report a fatal error (stops pipeline)
fatal(rsp, "Critical error occurred");
// Report a warning (continues pipeline)
warning(rsp, "Non-critical issue detected");
// Report normal completion
normal(rsp, "Function completed successfully");ComposeFunction- A plain function given the request and a response to fill inComposeResponse- ARunFunctionResponsewhosedesiredstate is guaranteed presentFunctionHandler- Interface to implement for your function logicFunctionRunner- Wraps your handler with error handling and logginggetServer()- Creates a gRPC server with your function
getObservedCompositeResource(req)- Get the observed composite resource (returnsResource | undefined)getDesiredCompositeResource(req)- Get the desired composite resource (returnsResource | undefined)getDesiredComposedResources(req)- Get map of desired composed resources (returns empty object if none exist)getObservedComposedResources(req)- Get map of observed composed resources (returns empty object if none exist)getInput(req)- Get function input configuration (returnsundefinedif not present)getContextKey(req, key)- Get context value from previous function (returns[value, exists]tuple)getRequiredResources(req)- Get required resources mapgetCredentials(req, name)- Get credentials by name (throws error if not found)
to builds a response. Every other helper below mutates the response it is given and returns nothing, matching the Go and Python SDKs -- call them as statements, not in an assignment.
to(req, ttl?)- Initialize response from request (optional TTL in seconds, defaults to 60)setDesiredComposedResources(rsp, resources)- Set composed resources (merges with existing)updateDesiredComposedResources(cds, namedResource)- Add a named resource to a map of composed resources, returning the map. Operates on the map, not the responsesetDesiredCompositeResource(rsp, resource)- Set the desired composite resourcesetDesiredCompositeStatus({ rsp, status })- Update composite statussetContextKey(rsp, key, value)- Set context for next function in pipelinesetOutput(rsp, output)- Set function output (returned to user)fatal(rsp, message)- Add fatal error result (stops pipeline)warning(rsp, message)- Add warning result (continues pipeline)normal(rsp, message)- Add normal info resultupdate(source, target)- Deep merge resources using ts-deepmerge
new CLI(opts?)- Create a CLI with optional custom flagscli.parse(argv?)- Parse arguments (CLI arg > env var > default)cli.values- The parsed values, keyed by flag name; throws beforeparse()cli.parsed- Whetherparse()has been calledcli.standardOptions()- GetServerOptionsfrom the standard flags; throws beforeparse()cli.logger()- Get a pino Logger configured from--debug; throws beforeparse()cli.helpText()- Generate help text including custom flagscli.name- The program name used in help text
serve(fn, opts?)- Run aComposeFunctionorFunctionHandleras a gRPC server: parses flags, builds a logger, starts the server, handles shutdownfromCompose(compose)- Adapt aComposeFunctionto theFunctionHandlerinterfaceparseArgs(argv)- Parse the standard function flags, for functions adding flags of their ownhelpText(name)- The--helptext for the standard flagsDEFAULT_ADDRESS-0.0.0.0:9443DEFAULT_TLS_SERVER_CERTS_DIR-/tls/servernewGrpcServer(runner, logger, opts?)- Create gRPC server instance;optssetsmaxRecvMessageSizeandmaxSendMessageSizein bytesstartServer(server, opts, logger, onBindError?)- Bind and start the server on specified address;onBindErroris called if binding failsgetServerCredentials(opts)- Create server credentials (TLS or insecure mode)
fromObject(obj)- Create a Resource from a plain JavaScript objecttoObject(resource)- Extract plain object from a ResourceasStruct(obj)- Convert object to protobuf Struct formatasObject(struct)- Convert protobuf Struct to plain objectnewDesiredComposed()- Create a new empty DesiredComposed resourcemustStructObject(obj)- Convert object to Struct, throws on errormustStructJSON(json)- Parse JSON string to Struct, throws on error
my-function/
├── src/
│ ├── main.ts # Entry point
│ └── my-function.ts # Your function implementation
├── package.json
├── tsconfig.json
└── dist/ # Build output