orchestration

Documentation

Overview

Package orchestration provides the orchestrator-side primitives for the session-pool pattern: a pool of pods, each hosting N sessions, where a caller asks for a session slot and gets back an address + token to reach it.

Backends:

• Local — single-process, for tests and dev.
• Agones — production game-server orchestration (separate sub-package to keep the heavy SDK out of the core import graph).
• K8s — plain k8s, no Agones, label/selector based.

Pod-side wiring lives in kit/orchestration/sdk: a thin wrapper around the per-pod readiness/health/shutdown lifecycle and session-slot bookkeeping.

Index

• Variables
• type AllocateReq
• type Allocation
• type Allocator
• type LocalAllocator
  • func NewLocalAllocator() *LocalAllocator
  • func (a *LocalAllocator) AddPod(pool string, pod *LocalPod)
  • func (a *LocalAllocator) Allocate(_ context.Context, req AllocateReq) (Allocation, error)
  • func (a *LocalAllocator) Release(pool, sessionID string)
• type LocalPod

Variables

var (
	ErrNoCapacity     = errors.New("orchestration: no pod with capacity in pool")
	ErrUnknownPool    = errors.New("orchestration: unknown pool")
	ErrAllocatorClose = errors.New("orchestration: allocator closed")
)

Errors surfaced by allocators.

Types

type AllocateReq

type AllocateReq struct {
	// Pool is the logical pool name (e.g. "vermintide-eu", "tb-strategy").
	Pool string

	// Selectors are arbitrary key/value labels that backends use to
	// filter eligible pods (region, build, gpu, etc.).
	Selectors map[string]string

	// Priority influences pod-selection ordering when multiple pods are
	// eligible. Higher wins.
	Priority int

	// Annotations are attached to the resulting Allocation and visible
	// to the pod (e.g. tenant id, match params).
	Annotations map[string]string
}

AllocateReq is the orchestrator's request for a session slot.

type Allocation

type Allocation struct {
	// PodAddress is host:port the client should dial.
	PodAddress string
	// SessionID is the slot id within the pod.
	SessionID string
	// Token is an opaque, backend-signed credential the pod will
	// verify on session start.
	Token []byte
	// Annotations echo the request's annotations plus any added by
	// the allocator.
	Annotations map[string]string
}

Allocation is the result of a successful Allocate call.

type Allocator

type Allocator interface {
	Allocate(ctx context.Context, req AllocateReq) (Allocation, error)
}

Allocator allocates a session slot on a pod from a pool.

type LocalAllocator

type LocalAllocator struct {
	// contains filtered or unexported fields
}

LocalAllocator is an in-process allocator. Useful for tests and single-binary local dev. Not safe across processes.

func NewLocalAllocator

func NewLocalAllocator() *LocalAllocator

NewLocalAllocator constructs an empty local allocator.

func (*LocalAllocator) AddPod

func (a *LocalAllocator) AddPod(pool string, pod *LocalPod)

AddPod registers a pod in the given pool.

func (*LocalAllocator) Allocate

func (a *LocalAllocator) Allocate(_ context.Context, req AllocateReq) (Allocation, error)

Allocate picks a pod with capacity that matches the selectors.

func (*LocalAllocator) Release

func (a *LocalAllocator) Release(pool, sessionID string)

Release frees a session slot. No-op if unknown.

type LocalPod

type LocalPod struct {
	Address  string
	Capacity int
	Labels   map[string]string
	// contains filtered or unexported fields
}

LocalPod registers a pod with a local allocator.