simulate

package
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 4, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

README

pkg/simulate

simulate runs your operator's reconcile loop against an in-memory fake cluster — no Kubernetes required. Give it a Katalog and a CR file and it shows exactly which resources your operator creates, updates, or deletes, and when it converges.

ork simulate                                   # katalog.yaml + cr.yaml in current dir
ork simulate -f my-katalog.yaml --cr my-cr.yaml
ork simulate -f e2e.yaml                       # reads spec.katalog and spec.cr
ork simulate ./...                             # discovers and runs all e2e.yaml files
ork simulate ./... --skip vendor               # skip patterns during discovery
ork simulate --skip-external                   # stub external: HTTP calls
ork simulate --debug-ops                       # print all recorded ops with cycle numbers

What works

Feature How
Declarative operators (templates, status, conditions) Always — no binary needed
external: HTTP calls Hits real network by default; pass --skip-external to stub
cross: CRD observation Include sibling CRs separated by --- in the CR file
Go hooks (OnReconcile, OnDelete) Build your operator binary with make registry && make build
Custom constructors Same binary requirement as hooks
Multi-CRD Katalogs Multi-doc CR file — each CRD matched to its CR by kind

Developer documentation

I want to… Go to
Read the output and understand what each line means docs/01-output.md
Understand steady state and how to tune cycles docs/02-steady-state.md
Understand what simulate does not cover docs/03-limitations.md
Understand the internals (fake cluster, reactors, indexer, cross: wiring) docs/04-internals.md

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CycleResult

type CycleResult struct {
	Cycle int
	Ops   []Op
	Error error
}

CycleResult is the output of one reconcile cycle.

type FakeKubeclient

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

FakeKubeclient implements kubeclient.KubeClient using k8s fakes. All operations are recorded in Ops() for simulation output.

func NewFakeKubeclient

func NewFakeKubeclient(scheme *runtime.Scheme) *FakeKubeclient

func (*FakeKubeclient) AdvanceCycle

func (f *FakeKubeclient) AdvanceCycle()

AdvanceCycle increments the cycle counter. Call between simulated reconciles.

func (*FakeKubeclient) Clientset

func (f *FakeKubeclient) Clientset() kubernetes.Interface

func (*FakeKubeclient) DynamicClient

func (f *FakeKubeclient) DynamicClient() dynamic.Interface

func (*FakeKubeclient) Mapper

func (f *FakeKubeclient) Mapper() meta.RESTMapper

func (*FakeKubeclient) MarkDeploymentReady

func (f *FakeKubeclient) MarkDeploymentReady(namespace, name string)

MarkDeploymentReady advances simulated state — marks a Deployment as Available. Call after the first reconcile cycle to allow the reconciler to progress through "Deploying" → "Ready" state transitions.

func (*FakeKubeclient) Ops

func (f *FakeKubeclient) Ops() []Op

Ops returns all recorded operations in order.

func (*FakeKubeclient) OpsForCycle

func (f *FakeKubeclient) OpsForCycle(cycle int) []Op

OpsForCycle returns operations from one reconcile cycle.

func (*FakeKubeclient) PatchAnnotations

func (f *FakeKubeclient) PatchAnnotations(_ context.Context, obj runtime.Object, _ schema.GroupVersionResource, annotations map[string]string) error

func (*FakeKubeclient) PatchFinalizers

func (f *FakeKubeclient) PatchFinalizers(_ context.Context, obj runtime.Object, _ schema.GroupVersionResource, finalizers []string) error

func (*FakeKubeclient) PatchLabels

func (f *FakeKubeclient) PatchLabels(_ context.Context, obj runtime.Object, _ schema.GroupVersionResource, base, desired map[string]string) error

func (*FakeKubeclient) PatchStatus

func (f *FakeKubeclient) PatchStatus(_ context.Context, obj domain.Object, _ schema.GroupVersionResource, _ map[string]interface{}) error

type Op

type Op struct {
	Cycle     int
	Verb      string // "create", "update", "delete", "get", "patch"
	Resource  string // "deployments", "services", etc.
	Namespace string
	Name      string
	At        time.Time
}

Op is one recorded cluster operation.

type Result

type Result struct {
	Cycles   []CycleResult
	Steady   bool
	SteadyAt int      // cycle number where steady state was first detected (0 if not reached)
	Notes    []string // informational notes about blocks that could not execute (e.g. constructor body)
	AllOps   []Op     // every op recorded across all cycles, for diagnostic use
}

Result is the output of one simulation run.

func Run

func Run(ctx context.Context, kat *katalog.Katalog, crdName string, cr *unstructured.Unstructured, maxCycles int, opts RunOptions) (*Result, error)

Run simulates the operator against an in-memory cluster.

kat is the parsed Katalog. crdName is the CRD entry to simulate. cr is the CR to reconcile. maxCycles is the maximum number of reconcile cycles.

type RunOptions added in v0.7.1

type RunOptions struct {
	// SkipExternal stubs all external: HTTP calls with an empty 200 response.
	// When false (the default), external calls are attempted against the real network.
	SkipExternal bool

	// Peers holds CRs for sibling CRDs in the same Katalog, keyed by lowercase kind.
	// When set, cross: declarations in the reconciler can observe these CRs
	// via the fake katalog registry instead of returning empty results.
	Peers map[string]*unstructured.Unstructured
}

RunOptions controls optional behaviour for a simulation run.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL