Platform Mesh - subroutines

Description

subroutines is a lifecycle engine for Kubernetes controllers built on multicluster-runtime. It offers explicit Result-based flow control, opt-in condition/status management, and built-in observability.

• Subroutine orchestration — chain subroutines with typed Result values (OK, Pending, Stop) instead of plain errors
• Condition management — automatic per-subroutine and aggregate Ready conditions
• Spread scheduling — distribute reconciliation load over configurable time windows to avoid thundering-herd effects
• Finalizer lifecycle — declarative finalizer registration, ordered teardown, and initializer/terminator support
• Observability — built-in Prometheus metrics (duration, errors, requeue) and OpenTelemetry tracing

Getting started

Add the dependency to your Go module:

go get github.com/platform-mesh/subroutines

Quick start

import (
    "github.com/platform-mesh/subroutines/conditions"
    "github.com/platform-mesh/subroutines/lifecycle"
)

lc := lifecycle.New(mgr, "MyController", func() client.Object { return &v1alpha1.MyResource{} },
    subroutine1,
    subroutine2,
).WithConditions(conditions.NewManager())

Each subroutine implements one or more of the core interfaces:

// Processor handles the main reconciliation logic.
type Processor interface {
    Subroutine
    Process(ctx context.Context, obj client.Object) (Result, error)
}

// Finalizer handles cleanup when an object is being deleted.
type Finalizer interface {
    Subroutine
    Finalize(ctx context.Context, obj client.Object) (Result, error)
    Finalizers(obj client.Object) []string
}

Subroutines return a Result to control the chain:

subroutines.OK()                          // continue, no requeue
subroutines.OKWithRequeue(5 * time.Minute) // continue, requeue after duration
subroutines.Pending(30 * time.Second, "waiting for dependency") // continue, set condition to Unknown
subroutines.StopWithRequeue(time.Minute, "rate limited")        // stop chain, requeue
subroutines.Stop("done")                                        // stop chain, no requeue

Packages

Package	Description
subroutines	Core interfaces (Subroutine, Processor, Finalizer, Initializer, Terminator) and Result type
lifecycle	Orchestration engine — executes subroutines, manages finalizers, patches status
conditions	Per-subroutine and aggregate Ready condition management
spread	Reconciliation spreading to distribute load over time
metrics	Prometheus metrics for subroutine execution

Requirements

subroutines requires Go. Check the go.mod for the required Go version.

Contributing

Please refer to the CONTRIBUTING.md file in this repository for instructions on how to contribute to Platform Mesh.

Code of Conduct

Please refer to our Code of Conduct for information on the expected conduct for contributing to Platform Mesh.