Skip to content

Latest commit

 

History

History
535 lines (428 loc) · 19.1 KB

USAGE.md

File metadata and controls

535 lines (428 loc) · 19.1 KB

Function SDK Usage Guide

This document demonstrates how to use the Crossplane Function SDK for TypeScript to build your own functions.

Installation

npm install @crossplane-org/function-sdk-typescript

Basic Usage

1. Write Your Function

A 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.

Implementing FunctionHandler Instead

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;
        }
    }
}

2. Create a Main Entry Point

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.

Message size limits

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 16
  • MAX_RECV_MESSAGE_SIZE=16
  • MAX_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"

Upgrading from earlier versions

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 sets ADDRESS, DEBUG, INSECURE, TLS_SERVER_CERTS_DIR or one of the message size variables for some other reason will now pick it up. An empty value is treated as unset, so value: "" 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
});

3. Build and Run

# 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/certs

Advanced Usage

Custom Flags with the Shareable CLI

If 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 to false, 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 when env is unset.
  • description — Shown in --help output.

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.

Building the Server Yourself

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));
});

Using Kubernetes Models

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() });

Setting Composite Resource Status

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",
    },
});

Working with Context

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 });

Working with Credentials

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}`);
}

Error Handling

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");

API Reference

Core Interfaces

  • ComposeFunction - A plain function given the request and a response to fill in
  • ComposeResponse - A RunFunctionResponse whose desired state is guaranteed present
  • FunctionHandler - Interface to implement for your function logic
  • FunctionRunner - Wraps your handler with error handling and logging
  • getServer() - Creates a gRPC server with your function

Request Helpers

  • getObservedCompositeResource(req) - Get the observed composite resource (returns Resource | undefined)
  • getDesiredCompositeResource(req) - Get the desired composite resource (returns Resource | 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 (returns undefined if not present)
  • getContextKey(req, key) - Get context value from previous function (returns [value, exists] tuple)
  • getRequiredResources(req) - Get required resources map
  • getCredentials(req, name) - Get credentials by name (throws error if not found)

Response Helpers

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 response
  • setDesiredCompositeResource(rsp, resource) - Set the desired composite resource
  • setDesiredCompositeStatus({ rsp, status }) - Update composite status
  • setContextKey(rsp, key, value) - Set context for next function in pipeline
  • setOutput(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 result
  • update(source, target) - Deep merge resources using ts-deepmerge

Shareable CLI

  • new CLI(opts?) - Create a CLI with optional custom flags
  • cli.parse(argv?) - Parse arguments (CLI arg > env var > default)
  • cli.values - The parsed values, keyed by flag name; throws before parse()
  • cli.parsed - Whether parse() has been called
  • cli.standardOptions() - Get ServerOptions from the standard flags; throws before parse()
  • cli.logger() - Get a pino Logger configured from --debug; throws before parse()
  • cli.helpText() - Generate help text including custom flags
  • cli.name - The program name used in help text

Runtime

  • serve(fn, opts?) - Run a ComposeFunction or FunctionHandler as a gRPC server: parses flags, builds a logger, starts the server, handles shutdown
  • fromCompose(compose) - Adapt a ComposeFunction to the FunctionHandler interface
  • parseArgs(argv) - Parse the standard function flags, for functions adding flags of their own
  • helpText(name) - The --help text for the standard flags
  • DEFAULT_ADDRESS - 0.0.0.0:9443
  • DEFAULT_TLS_SERVER_CERTS_DIR - /tls/server
  • newGrpcServer(runner, logger, opts?) - Create gRPC server instance; opts sets maxRecvMessageSize and maxSendMessageSize in bytes
  • startServer(server, opts, logger, onBindError?) - Bind and start the server on specified address; onBindError is called if binding fails
  • getServerCredentials(opts) - Create server credentials (TLS or insecure mode)

Resource Helpers

  • fromObject(obj) - Create a Resource from a plain JavaScript object
  • toObject(resource) - Extract plain object from a Resource
  • asStruct(obj) - Convert object to protobuf Struct format
  • asObject(struct) - Convert protobuf Struct to plain object
  • newDesiredComposed() - Create a new empty DesiredComposed resource
  • mustStructObject(obj) - Convert object to Struct, throws on error
  • mustStructJSON(json) - Parse JSON string to Struct, throws on error

Project Structure

my-function/
├── src/
│   ├── main.ts              # Entry point
│   └── my-function.ts       # Your function implementation
├── package.json
├── tsconfig.json
└── dist/                    # Build output