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.
The recommended entry point is simulate.yaml — it records what your operator should produce so the run is repeatable and verifiable:
ork simulate # auto-detects simulate.yaml, then katalog.yaml
ork simulate -f simulate.yaml # explicit — assert mode when expect: is set
ork simulate -f my-katalog.yaml --cr my-cr.yaml
ork simulate ./... # discovers all simulate.yaml files recursively
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
ork simulate --dev-server # start mock dev server for external: examples
ork simulate init # generate simulate.yaml from observed cycle-1 ops
ork simulate init --suite # write a suite aggregator from discovered leaf files
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 ¶
- func ExpectForCRD(expect *orktypes.SimulateExpect, crdName string) *orktypes.SimulateExpect
- type AssertionError
- type CycleResult
- type FakeKubeclient
- func (f *FakeKubeclient) AdvanceCycle()
- func (f *FakeKubeclient) Clientset() kubernetes.Interface
- func (f *FakeKubeclient) Create(_ context.Context, obj sigs.Object) error
- func (f *FakeKubeclient) DynamicClient() dynamic.Interface
- func (f *FakeKubeclient) Get(_ context.Context, namespace, name string, into sigs.Object) error
- func (f *FakeKubeclient) Mapper() meta.RESTMapper
- func (f *FakeKubeclient) MarkDeploymentReady(namespace, name string)
- func (f *FakeKubeclient) Ops() []Op
- func (f *FakeKubeclient) OpsForCycle(cycle int) []Op
- func (f *FakeKubeclient) Patch(_ context.Context, obj sigs.Object, _ kubeclient.Patch) error
- func (f *FakeKubeclient) PatchAnnotations(_ context.Context, obj runtime.Object, annotations map[string]string) error
- func (f *FakeKubeclient) PatchFinalizers(_ context.Context, obj runtime.Object, finalizers []string) error
- func (f *FakeKubeclient) PatchLabels(_ context.Context, obj runtime.Object, base, desired map[string]string) error
- func (f *FakeKubeclient) PatchStatus(_ context.Context, obj domain.Object, _ map[string]interface{}) error
- type Op
- type Result
- type RunOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExpectForCRD ¶ added in v0.7.2
func ExpectForCRD(expect *orktypes.SimulateExpect, crdName string) *orktypes.SimulateExpect
ExpectForCRD returns the expect block for a named CRD. If expect.crds has an entry for crdName, that is returned. Otherwise the top-level expect (default) is returned.
Types ¶
type AssertionError ¶ added in v0.7.2
AssertionError is one failed expectation from Assert.
func Assert ¶ added in v0.7.2
func Assert(result *Result, expect *orktypes.SimulateExpect) []AssertionError
Assert checks a Result against a SimulateExpect. Returns nil when all expectations are satisfied.
func (AssertionError) Error ¶ added in v0.7.2
func (e AssertionError) Error() string
type CycleResult ¶
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) Patch ¶ added in v0.7.7
func (f *FakeKubeclient) Patch(_ context.Context, obj sigs.Object, _ kubeclient.Patch) error
func (*FakeKubeclient) PatchAnnotations ¶
func (*FakeKubeclient) PatchFinalizers ¶
func (*FakeKubeclient) PatchLabels ¶
func (*FakeKubeclient) PatchStatus ¶
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.
Source Files