OCIFBSD_ORCHESTRATION(3)

NAME

ocifbsd_orchestration — ocifbsd pod, stack, and scheduling library

SYNOPSIS

#include <ocifbsd/orchestration.h>

int
orch_init(struct orch_config *cfg);

void
orch_shutdown(void);

int
pod_create(struct pod_spec *spec);

int
pod_start(const char *name);

int
pod_stop(const char *name, int timeout);

int
pod_delete(const char *name);

int
pod_scale(const char *name, int replicas);

int
stack_deploy(struct stack_spec *spec);

int
health_check_pod(const char *name);

int
rolling_update(struct pod_spec *new_spec);

int
scheduler_place(struct pod_spec *spec, struct node_info *nodes, int n_nodes);

The ocifbsd_orchestration library implements the high-level orchestration primitives used by ocifbsd(8) to manage pods, stacks, and rolling updates. It is not a standalone program; it is linked into the main ocifbsd(8) binary.

The library is organised into seven functional modules:

Pod management (pod.c) creates, starts, stops, deletes, and scales pods (multi-container deployment units, the Ensemble equivalent of a declarative Deployment).
Stack management (stack.c) deploys and tears down stacks — multi-pod application bundles, the Ensemble equivalent of a multi-service stack.
Scheduling (scheduler.c) selects the best node to run a pod on, based on available CPU, memory, and resource quotas.
Health checking (health.c) runs liveness and readiness probes against running pods and reports status to the cluster.
Rolling updates (rolling_update.c) performs zero-downtime updates by replacing pod replicas one at a time.
CLI plumbing (orch_cli.c) implements the ocifbsd pod, ocifbsd stack, and ocifbsd service subcommand handlers.
Lifecycle (orch_init.c) initialises the global orchestration state (mutexes, trees, default config) and shuts it down cleanly.

The library calls the container lifecycle functions (ocifbsd_create_container, ocifbsd_start_container, etc.) that live in the main ocifbsd(8) binary. When the library is loaded standalone, the stubs.c() file in this directory provides stub implementations of those functions so the library can be linked and tested in isolation. When it is linked into the main ocifbsd(8) binary, the real implementations override the stubs.

The full public API is declared in <ocifbsd/orchestration.h>.

Load balancing

A service is fronted by a virtual IP (VIP). The load balancer distributes connections to the VIP across the service's ready replica endpoints using pf(4) redirection pools, native to FreeBSD and requiring no external daemon. service_lb_build_rules() generates the ruleset and service_lb_apply() loads it into a per-service anchor ocifbsd/lb/⟨service⟩. The lb_algorithm selects the pool type: roundrobin (the default) maps to a round-robin pool, iphash (or clientip session affinity) to a source-hash pool, and leastconn falls back to round-robin (pf(4) has no least-connections pool). Only replicas in the REPLICA_STATE_RUNNING state become backends, so the pool works regardless of which node a replica runs on as long as its address is routable.

Scheduling and placement

scheduler_select_node() places each replica on the ready, uncordoned node with the best score, preferring nodes running fewer pods so replicas spread across the cluster. scheduler_add_node() registers a worker; scheduler_set_node_schedulable() cordons or uncordons a node (a cordoned node keeps its pods but receives no new placements); and scheduler_sync_nodes() reconciles the node set with the cluster membership, retiring nodes that have left while never retiring the local node.

FILES

/etc/ocifbsd/orchestration.conf: Orchestration defaults (replica limits, rolling-update parameters, health-check intervals).
/var/run/ocifbsd/pods: Per-pod state directory.
/var/db/ocifbsd/stacks: Stack manifests.

HISTORY

The ocifbsd_orchestration library first appeared in FreeBSD 16.0.

AUTHORS

The ocifbsd_orchestration library was developed by REVYTECH, Inc.