Copy page

Extending the platform

Plugin SDK

The Unikraft Cloud Plugin SDK is a small framework for building plugins in Go. A plugin runs as a sidecar HTTP server next to your app inside an instance, and loads from its own ROM image. It answers the requests that the platform forwards to it over a per-instance, authenticated endpoint.

Every plugin meets the same platform contract. It parses the init command line, adopts the socket the platform hands it, and decodes the JSON config from STDIN. It also stands up a router with middleware and drains in-flight requests on shutdown. The SDK takes care of each step. You write a configuration struct and a route registration function, and pluginsdk.Main does the rest. A complete plugin takes about 25 lines.

Installation

Code
go get unikraft.com/cloud/pluginsdk

Requires Go 1.26.4 or later.

Quickstart

Code
package main

import (
  "context"

  "github.com/gin-gonic/gin"

  "unikraft.com/cloud/pluginsdk"
)

// Config takes its values from the platform `config` JSON on STDIN, through
// each field's `json` tag. A --greeting flag overrides that value; an `env`
// tag would bind an environment variable as well.
type Config struct {
  Greeting string `json:"greeting" default:"Hello"`
}

func main() {
  pluginsdk.Main(&pluginsdk.Plugin[Config]{
    Name: "example",
    Register: func(ctx context.Context, cfg *Config, engine *gin.Engine) error {
      engine.GET("/hello", func(g *gin.Context) {
        data := gin.H{"message": cfg.Greeting + ", world!"}

        env, code, _ := pluginsdk.OK(&data)
        g.JSON(code, env)
      })

      return nil
    },
  })
}

That covers the whole plugin. pluginsdk.Main takes these steps in order:

1. Parses the command line: --api_fd, --api-addr, --log-level, --log-type, and one flag per field of Config.
2. Reads the JSON config from STDIN and decodes it into Config.
3. Configures logging, then runs the optional Setup hook.
4. Adopts the --api_fd socket as its listener.
5. Builds the gin engine with the default middleware and calls Register.
6. Serves until SIGINT or SIGTERM arrives, then drains and shuts down.

Run the plugin locally with --api-addr in place of --api_fd:

Code
echo '{"greeting":"Hey"}' | go run . --api-addr :8080 --log-type text
curl -s localhost:8080/hello

Code
{"status":"success","data":{"message":"Hey, world!"}}

Configuration

A plugin declares its configuration once, as a plain Go struct, and that declaration acts as the single source of truth. It validates the platform config, supplies the defaults, and derives the command-line flags and environment variables.

Where values come from

Four sources feed a plugin's configuration. The SDK merges them in this order, from lowest precedence to highest:

Code
struct default  <  platform config on STDIN  <  environment  <  command-line flag

• Struct default: the fallback that the default tag bakes into the binary.
• Platform config: the JSON you attach to the plugin when you create the instance, which is the production path.
• Environment: any field that carries an env tag.
• Command-line flag: an explicit flag for local development and debugging.

A field that defaults to /tmp stays /tmp unless the platform config sets "workdir":"/data", unless WORKDIR=/srv sits in the environment, unless --workdir /mnt appears on the command line.

Struct tags

A config field carries two kinds of tag. A json tag names the field's key in the platform config, and kong tags govern the command-line flag and the environment override. The two work independently: JSON keys conventionally use snake_case while flags use kebab-case, so json:"source_type" and name:"source-type" routinely sit on the same field.

Tag	Purpose	Example
json:"…"	Key in the platform config on STDIN	json:"source_url"
name:"…"	Flag name, in kebab-case	name:"source-url"
env:"…"	Environment variable to bind the field to	env:"SOURCE_URL"
help:"…"	Help text	help:"Repository URL."
default:"…"	Default value	default:"/tmp"
enum:"a,b,c"	Restrict the value to a set	enum:"git,tar"
placeholder:"…"	Help placeholder	placeholder:"dir"
required:""	Make the flag mandatory	required:""
hidden:""	Hide the flag from --help	hidden:""
kong:"-"	Ignore the field entirely	kong:"-"

The json tag belongs to the SDK rather than to kong. The SDK reads it to map each config key onto a field, and kong owns every other tag. A field without a json tag takes its exact Go field name as the key, so Greeting matches "Greeting" and misses "greeting". That lookup runs case-sensitively, unlike encoding/json, so give every field a json tag. The map covers a struct's own exported fields, so a field inside an embedded struct gets no config key at all.

Code
type Config struct {
  Workdir    string `json:"workdir" name:"workdir" env:"WORKDIR" help:"Working directory." default:"/tmp"`
  SourceType string `json:"source_type" name:"source-type" env:"SOURCE_TYPE" help:"Source type." enum:"git,tar" default:"git"`
  Verbose    bool   `json:"verbose" name:"verbose" env:"VERBOSE" help:"Enable verbose output."`

  // Never surfaces as a flag or a config key; code populates it.
  internalToken string `json:"-" kong:"-"`
}

The platform config

Attach a config to the plugin in the create instance request, and it reaches the plugin's init on STDIN:

Code
{
  "name": "example",
  "image": "user/example:latest",
  "config": { "greeting": "Bonjour" }
}

The platform accepts a non-object config as well: a bare string or a number counts as valid JSON. A value of that shape maps onto no fields, so reach for the raw bytes instead:

Code
raw := pluginsdk.RawConfig(ctx) // []byte, exactly as STDIN delivered it

Routing

Register receives the base context, your typed configuration, and the gin engine:

Code
Register: func(ctx context.Context, cfg *Config, engine *gin.Engine) error {
  engine.GET("/files/:name", handleGetFile)
  engine.POST("/files", handleWriteFile)

  v1 := engine.Group("/v1")
  v1.GET("/status", handleStatus)

  return nil
}

Define your routes relative to /. The platform strips the plugins/<plugin_name>/ prefix before the request reaches the plugin, so a call to .../plugins/example/files/list arrives as GET /files/list. A plugin never needs to know its own name to route correctly.

The SDK builds the engine with gin.New() in release mode, turns on HandleMethodNotAllowed, and rejects unknown JSON fields, which keeps generated types strict.

Default middleware

Ahead of your routes, the SDK installs a global middleware stack from unikraft.com/x/middleware:

Middleware	Effect
CORS()	Cross-origin resource sharing headers
ExtraHeaders()	Static response headers
Logger(ctx)	Structured per-request logging
DefaultCacheControl()	Sensible Cache-Control defaults

Append your own middleware, or replace the defaults outright:

Code
pluginsdk.Main(&pluginsdk.Plugin[Config]{
  Name:       "example",
  Register:   register,
  Middleware: []gin.HandlerFunc{myMiddleware()}, // appended to the defaults

  // ...or drop the defaults and bring your own stack:
  // DisableDefaultMiddleware: true,
})

Generated services

Plugins describe their API in TypeSpec and generate a typed gin service interface from it. Register that generated service from inside Register:

Code
Register: func(ctx context.Context, cfg *Config, engine *gin.Engine) error {
  api.RegisterX(engine, handler, nil)

  return nil
}

pluginsdk.OK and pluginsdk.Error return the (payload, status, error) triple that a generated handler method produces, so a handler body often comes down to a single return pluginsdk.OK(&data).

Responses

The platform wraps every response in a standard envelope, and two helpers build it for you:

Code
// Success. OK takes a pointer and returns three values.
env, code, _ := pluginsdk.OK(&data)
g.JSON(code, env)

// Error.
env, code, _ := pluginsdk.Error[any](http.StatusBadRequest, "bad input")
g.JSON(code, env)

A handler that calls OK produces the same shape as the rest of the API:

Code
{
  "status": "success",
  "data": { "message": "Bonjour, world!" }
}

The status field holds success, partial_success, or error. In Go the envelope type is platform.Response[T] from unikraft.com/cloud/sdk/platform, which the Go SDK uses as well.

Global flags

Every plugin accepts these four flags, whatever its own configuration declares:

Flag	Environment	Meaning
--api_fd <n>	API_FD	Serve on file descriptor n, which the platform supplies
--api-addr <addr>	API_ADDR	Serve on a TCP address such as :8080, for local development
--log-level	LOG_LEVEL	One of trace, debug, info, warn, error, fatal
--log-type	LOG_TYPE	Either text or json

The platform spells --api_fd with an underscore, and every other flag uses a hyphen.

Lifecycle

Main runs this sequence:

1. Read the config from STDIN, then parse the command line.
2. Configure logging from --log-level and --log-type.
3. Run the optional Setup hook.
4. Bind the listener: --api_fd in production, --api-addr locally.
5. Build the router with the default and user middleware, then call the registration function.
6. Serve on the listener.
7. Block until a signal arrives or the context cancels.
8. Drain: stop accepting connections, finish in-flight requests, then shut down.

Serve covers step 2, then steps 4 through 8. It takes an already-resolved configuration rather than reading the command line or STDIN, and it runs no Setup hook.

--api_fd wins whenever the command line carries it, and otherwise the SDK falls back to --api-addr. At least one of the two has to resolve, or startup fails with ErrNoListener. Serve can also take a listener directly through WithListener, which outranks both flags. A shutdown gives in-flight requests a 30-second window to drain.

Scale-to-zero

Scale-to-zero puts an idle instance to sleep. A plugin request wakes the instance and keeps it up for the length of that request. Background work that outlives the request has to hold the instance awake on its own.

The scaletozero sub-package keeps a counter for exactly that:

Code
import "unikraft.com/cloud/pluginsdk/scaletozero"

// Hold the instance awake while the work runs.
if err := scaletozero.Increment(); err != nil {
  return err
}
defer scaletozero.Decrement()

A counter rather than a flag means many independent workers increment and decrement without coordinating. Scale-to-zero stays suspended while the count sits above zero and resumes at zero. Set(n), IncrementBy(n), and DecrementBy(n) cover the remaining cases.

Logging

The SDK configures a structured logger from --log-level and --log-type, which default to info and text, and makes it available to your handlers through the request context. The logger comes from unikraft.com/x/log. Pass --log-type json in production.

Project layout

A plugin keeps its API description and its image recipes next to the source:

Code
plugins/<plugin_name>/
├── api.tsp          # TypeSpec API description (optional)
├── openapi.yaml     # generated from api.tsp
├── main.go          # the entrypoint
├── api/             # generated service: interface, models, register function
├── Dockerfile       # builds the single `init` executable into a scratch image
├── Kraftfile        # ROM image recipe
└── go.mod

A small plugin needs no more than main.go, go.mod, a Dockerfile, and a Kraftfile.

Building the plugin image

The deliverable is a ROM image with a single init executable at its root. The platform appends --api_fd <n> and pipes the config JSON to STDIN at launch, so /init has to be the SDK-based binary that understands both.

A plugin runs as a process inside the host instance rather than as its own unikernel, so init has to stand on its own. A static Go build produces that.

Dockerfile

A build stage produces init, and a scratch image carries it:

Code
FROM golang:1.26-bookworm AS build

WORKDIR /plugin
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /plugin/dist/init .

FROM scratch

COPY --from=build /plugin/dist/init /init
ENTRYPOINT ["/init"]

Kraftfile

A plugin ships as a ROM, which carries no kernel of its own. The platform mounts it at /uk/plugins/<plugin_name> inside the host instance and runs its init. Declare the image under roms:

Code
spec: v0.7

targets:
- kraftcloud/x86_64

roms:
- ./Dockerfile

A ROM has no runtime to take an architecture from, so it names one under targets, or you pass --arch on the command line. A build that does neither fails, and each plugin needs the architecture of the instance that hosts it.

Package and push the ROM image:

Code
unikraft build . --output <my-org>/example:latest

Deploying

Attach the plugin when you create the instance, naming the ROM image and an optional config:

Code
unikraft instance create \
  --name my-instance \
  --metro fra \
  --image my-app:latest \
  --plugin 'name=example,image=<my-org>/example:latest,config={"greeting":"Bonjour"}'

Then call the plugin through the instance's authenticated endpoint:

Code
curl -H "Authorization: Bearer $UKC_TOKEN" \
  https://api.fra.unikraft.cloud/v1/instances/<uuid>/plugins/example/hello

The plugins page covers the platform side in full: authorization, adding a plugin to an existing instance, and the limits.

API reference

Entrypoints

Main suits the common case of one plugin and one server. It parses the command line, reads STDIN, serves, blocks, and exits with a non-zero status on error.

Code
func Main[C any](p *Plugin[C])

Serve takes an already-resolved configuration, reads neither the command line nor STDIN, and returns an error instead of exiting. Cancelling ctx triggers the graceful shutdown. Reach for it in tests, when you embed a plugin in a larger program, or when you bring your own command grammar.

Code
func Serve[C any](ctx context.Context, cfg *C, register RegisterFunc[C], opts ...Option) error

The plugin declaration

Code
type Plugin[C any] struct {
  Name                     string
  Version                  string
  Register                 RegisterFunc[C]
  Setup                    SetupFunc[C]
  Middleware               []gin.HandlerFunc
  DisableDefaultMiddleware bool
}

type RegisterFunc[C any] func(ctx context.Context, cfg *C, engine *gin.Engine) error
type SetupFunc[C any]    func(ctx context.Context, cfg *C) error

Field	Description
Name	The plugin name, for logs and diagnostics only, since routing ignores it
Version	An optional version string that the startup logs carry
Register	Attaches the routes, and a non-nil error aborts startup (required)
Setup	An optional hook that runs once after the SDK resolves the configuration and before the server accepts requests
Middleware	Middleware to append to the default stack
DisableDefaultMiddleware	Drops the built-in stack and leaves the plugin in control

Options

An Option customizes Serve. A later option overwrites an earlier one that sets the same field. WithMiddleware appends instead of overwriting, and the listener keeps a fixed priority whatever the order: WithListener, then WithAPIFD, then WithAddr.

Option	Effect
WithOptions(o Options)	Seeds the runtime from the parsed global flags
WithAPIFD(fd int)	Forces the listener to adopt a file descriptor
WithAddr(addr string)	Forces a TCP listen address
WithListener(ln net.Listener)	Serves on a listener you supply
WithMiddleware(mw ...gin.HandlerFunc)	Appends global middleware
WithoutDefaultMiddleware()	Drops the default middleware stack
WithRawConfig(raw []byte)	Supplies the raw STDIN config for RawConfig

Options itself holds the four global flags as an embeddable kong struct: APIFd, APIAddr, LogLevel, and LogType. Embed it in your own command grammar to keep the standard flags.

Context and config helpers

Every request context descends from the base context, so these helpers work inside a handler through g.Request.Context().

Symbol	Description
FromContext[C any](ctx) *C	Retrieves the typed configuration from a request context
RawConfig(ctx) []byte	The raw platform config bytes from STDIN
APIFD(ctx) (int, bool)	The adopted file descriptor, and whether one exists
ReadConfig(stdin io.Reader) []byte	Reads the STDIN config verbatim
NewConfigResolver[C any](raw []byte) (kong.Resolver, bool)	Builds the kong resolver for a custom grammar

Response helpers

Symbol	Description
OK[T any](data *T) (*platform.Response[T], int, error)	A success envelope that wraps data
Error[T any](status int, msg string) (platform.Response[T], int, error)	An error envelope

Other exported symbols

Symbol	Description
ShutdownTimeout	The graceful-drain bound, at 30 seconds
ReadHeaderTimeout	The bound on waiting for request headers, at 30 seconds
ErrNoListener	Neither --api_fd nor --api-addr resolved
ErrNoRegister	A plugin reached Serve without a registration function
ErrInvalidAPIFD	The --api_fd descriptor yielded no usable file

Bring your own command grammar

Main wires one command line for you. A plugin that needs subcommands or extra pre-serve work defines its own kong grammar and calls Serve from the subcommand:

Code
type CLI struct {
  pluginsdk.Options // --api_fd, --api-addr, --log-level, --log-type

  Config Config `embed:""`

  Run RunCmd `cmd:"" help:"Fetch source, then serve."`
}

type RunCmd struct {
  SourceURL string `name:"source-url" env:"SOURCE_URL" help:"Repository to clone."`
}

func (c *RunCmd) Run(ctx context.Context, cli *CLI, raw rawConfig) error {
  if err := fetchSource(ctx, c.SourceURL); err != nil {
    return err
  }

  return pluginsdk.Serve(ctx, &cli.Config, register,
    pluginsdk.WithOptions(cli.Options),
    pluginsdk.WithRawConfig(raw),
  )
}

Two exported building blocks tie it together in main. ReadConfig reads the platform config off STDIN, and NewConfigResolver turns those bytes into the kong resolver that gives you the standard precedence:

Code
type rawConfig []byte

func main() {
  ctx, cancel := signal.NotifyContext(context.Background(),
    syscall.SIGINT, syscall.SIGTERM)
  defer cancel()

  raw := pluginsdk.ReadConfig(os.Stdin)

  var cli CLI

  opts := []kong.Option{
    kong.Name("example"),
    kong.UsageOnError(),
    kong.BindTo(ctx, (*context.Context)(nil)),
    kong.Bind(rawConfig(raw)),
  }
  if resolver, ok := pluginsdk.NewConfigResolver[Config](raw); ok {
    opts = append(opts, kong.Resolvers(resolver))
  }

  k := kong.Parse(&cli, opts...)
  k.FatalIfErrorf(k.Run())
}

pluginsdk.Options contributes the standard global flags and WithOptions feeds them to Serve, so the listener selection and the logging match Main with your own command tree on top. Extra middleware alone calls for no custom grammar, since Middleware and DisableDefaultMiddleware on Plugin already cover that.

Source

The SDK source lives at github.com/unikraft-cloud/plugin-sdk, and the API reference at pkg.go.dev/unikraft.com/cloud/pluginsdk.

Learn more

• Plugins: the platform feature that this SDK targets.
• ROMs: the image format that a plugin ships as.
• Scale-to-zero: how an idle instance wakes to serve a plugin request.
• Go SDK: the client library for the platform API itself.
• JavaScript SDK: the same platform API from JavaScript and TypeScript.
• Python SDK: the same platform API from Python.
• Instances: create and manage the instances that host plugins.