Actors/Packages/Kubernetes/API reference
@sigx/actors-k8s · Preview

API reference#

Exports of @sigx/actors-k8s v0.1.0.

k8sMembership(options?)#

Returns a ClusterMembership. Pair it with a directory provider — this package does not supply one.

TypeScript 
cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(redis) },
    advertise, secret,
});

Options are documented in Installation.

kubeClient(options?)#

The minimal HTTPS + JSON client the provider uses, exported for reuse. Types: KubeClient, KubeClientOptions.

Constants#

ExportValuePurpose
CLUSTER_LABELsigx.dev/clusterselects peers; lets two clusters share a namespace
DESCRIPTOR_ANNOTATIONsigx.dev/descriptorcarries the host descriptor JSON

Types#

K8sMembershipOptions, KubeClient, KubeClientOptions.

Behaviour#

Heartbeat — a merge-patch of spec.renewTime every heartbeatMs. No read-modify-write, so no resourceVersion races.

Discovery — the standard list-then-watch loop over Leases matching this host's labels. A peer is live while its renewTime is within its own declared duration.

Watch events for renewals never bump the membership view's version — only descriptor-set changes do (join, leave, drain, expiry), so heartbeats cause zero onChange traffic.

Self-fencing — renewal failures past ttlMs fire onSelfSuspect once: the host stops claiming actors and deactivates what it holds. See Health & readiness, where this surfaces as the fatal state.

A broken watch never fences. That is staleness, not death, and the relistMs safety net covers it.

Graceful exit — setStatus('leaving') patches the descriptor immediately, so a drain is visible now rather than next beat; leave() deletes the Lease. A crashed host simply stops renewing and ages out.

Versions — view().version is a local monotonic counter. Kubernetes resourceVersion is an opaque watch bookmark and is never interpreted.

State integrity never rests on any of this: the runtime's storage etag CAS remains the floor, exactly as with every other provider.

Next steps#