petri

README

petri

A real Kubernetes control plane inside go test. The upstream kube-apiserver and controllers are compiled into your test binary, so there is nothing to download and no Docker.

---

[!WARNING] petri is pre-alpha: the API will change between releases.

Install

go get github.com/yyewolf/petri@v0.37
# optional: the envtest drop-in and controller-runtime test helpers
go get github.com/yyewolf/petri/controllerruntime@v0.37

[!IMPORTANT] Use the petri minor that matches your k8s.io/client-go minor. petri v0.37.x embeds Kubernetes 1.37, so it pairs with k8s.io/client-go v0.37.x.

Usage

func TestDeploymentIsReconciled(t *testing.T) {
	t.Parallel()

	cp := petri.Start(t)  // the control plane shared by this test binary
	ns := cp.Namespace(t) // a fresh namespace, deleted when the test ends
	cs := cp.Client()     // an admin clientset; cp.Config() gives a *rest.Config
	cp.EnableControllers(t, petri.DeploymentController)

	labels := map[string]string{"app": "web"}
	deployments := cs.AppsV1().Deployments(ns)
	_, err := deployments.Create(t.Context(), &appsv1.Deployment{
		ObjectMeta: metav1.ObjectMeta{Name: "web"},
		Spec: appsv1.DeploymentSpec{
			Selector: &metav1.LabelSelector{MatchLabels: labels},
			Template: corev1.PodTemplateSpec{
				ObjectMeta: metav1.ObjectMeta{Labels: labels},
				Spec: corev1.PodSpec{
					Containers: []corev1.Container{{Name: "web", Image: "nginx"}},
				},
			},
		},
	}, metav1.CreateOptions{})
	if err != nil {
		t.Fatal(err)
	}

	// The Deployment controller has seen the Deployment once it reports the
	// generation it acted on.
	petri.WaitFor(t, deployments, "web", func(d *appsv1.Deployment) (bool, error) {
		return d != nil && d.Status.ObservedGeneration == d.Generation, nil
	})
}

petri.Start(t) starts one control plane for the whole test binary in about two seconds, and each test works in its own namespace. petri also covers:

• CRDs and webhooks, installed by the test that needs them.
• Built-in controllers. Namespace deletion and garbage collection always run; workload controllers run when a test enables them.
• Simulated Nodes with kube-scheduler, or Pods placed by the test in the style of gomock.
• controller-runtime, and a drop-in for envtest that takes a one-line import change.

Documentation

• yyewolf.github.io/petri has the guides and reference.
• pkg.go.dev has the API.
• CONTRIBUTING.md explains how to work on petri.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package petri runs a real Kubernetes control plane inside go test, with no downloaded binaries, no Docker, and nothing written to disk.

petri is pre-alpha: the API server, the built-in controllers, kube-scheduler and simulated Nodes work, and the API will change without notice.

Pods run on simulated Nodes, kwok-style: a dedicated control plane gets Nodes from ControlPlane.AddNode, and Pods placed on them by SchedulerController or by the test (ControlPlane.Bind, ControlPlane.ExpectPod, ControlPlane.ExpectPods) go Running and Ready at once, with no containers behind them.

Index

• Constants
• func Retry(t testing.TB, cond func(context.Context) (bool, error), opts ...WaitOption)
• func RetryUntil(ctx context.Context, cond func(context.Context) (bool, error), ...) error
• func WaitFor[O runtime.Object](t testing.TB, client ObjectClient[O], name string, cond Condition[O], ...) O
• func WaitUntil[O runtime.Object](ctx context.Context, client ObjectClient[O], name string, cond Condition[O], ...) (O, error)
• type AdmissionWebhookOptions
• type Condition
  • func Deleted[O runtime.Object]() Condition[O]
  • func Exists[O runtime.Object]() Condition[O]
  • func StatusCondition[O runtime.Object](condType string, status metav1.ConditionStatus) Condition[O]
• type ControlPlane
  • func New(ctx context.Context, opts ...Option) (*ControlPlane, error)
  • func Start(t testing.TB) *ControlPlane
  • func (cp *ControlPlane) AddNode(t testing.TB, opts NodeOptions) *Node
  • func (cp *ControlPlane) AddNodeCtx(ctx context.Context, opts NodeOptions) (*Node, error)
  • func (cp *ControlPlane) Bind(t testing.TB, pod *corev1.Pod, node *Node)
  • func (cp *ControlPlane) BindCtx(ctx context.Context, pod *corev1.Pod, node *Node) error
  • func (cp *ControlPlane) Client() *kubernetes.Clientset
  • func (cp *ControlPlane) CompletePod(t testing.TB, pod *corev1.Pod)
  • func (cp *ControlPlane) CompletePodCtx(ctx context.Context, pod *corev1.Pod) error
  • func (cp *ControlPlane) Config() *rest.Config
  • func (cp *ControlPlane) EnableControllers(t testing.TB, cs ...Controller)
  • func (cp *ControlPlane) Evict(t testing.TB, pod *corev1.Pod)
  • func (cp *ControlPlane) EvictCtx(ctx context.Context, pod *corev1.Pod) error
  • func (cp *ControlPlane) ExpectPod(t testing.TB, matchers ...PodMatcher) *corev1.Pod
  • func (cp *ControlPlane) ExpectPodCtx(ctx context.Context, matchers ...PodMatcher) (*corev1.Pod, error)
  • func (cp *ControlPlane) ExpectPods(t testing.TB, matchers ...PodMatcher) *PodExpectation
  • func (cp *ControlPlane) ExpectPodsCtx(ctx context.Context, matchers ...PodMatcher) (*PodExpectation, error)
  • func (cp *ControlPlane) FailPod(t testing.TB, pod *corev1.Pod, exitCode int32)
  • func (cp *ControlPlane) FailPodCtx(ctx context.Context, pod *corev1.Pod, exitCode int32) error
  • func (cp *ControlPlane) InstallAdmissionWebhooks(t testing.TB, opts AdmissionWebhookOptions, sources ...any)
  • func (cp *ControlPlane) InstallAdmissionWebhooksCtx(ctx context.Context, opts AdmissionWebhookOptions, sources ...any) (func() error, error)
  • func (cp *ControlPlane) InstallCRDs(t testing.TB, sources ...any)
  • func (cp *ControlPlane) InstallCRDsCtx(ctx context.Context, sources ...any) error
  • func (cp *ControlPlane) InstallConversionWebhooks(t testing.TB, opts ConversionWebhookOptions, crdNames ...string)
  • func (cp *ControlPlane) InstallConversionWebhooksCtx(ctx context.Context, opts ConversionWebhookOptions, crdNames ...string) error
  • func (cp *ControlPlane) Namespace(t testing.TB) string
  • func (cp *ControlPlane) NewNamespace(ctx context.Context) (string, error)
  • func (cp *ControlPlane) ServingCertDir(t testing.TB) string
  • func (cp *ControlPlane) SetPodReady(t testing.TB, pod *corev1.Pod, ready bool)
  • func (cp *ControlPlane) SetPodReadyCtx(ctx context.Context, pod *corev1.Pod, ready bool) error
  • func (cp *ControlPlane) Stop() error
  • func (cp *ControlPlane) StrictPods(t testing.TB)
  • func (cp *ControlPlane) StrictPodsCtx(ctx context.Context) error
  • func (cp *ControlPlane) UnexpectedPods() []string
  • func (cp *ControlPlane) WebhookCABundle() []byte
  • func (cp *ControlPlane) WriteServingCert(dir string) error
• type Controller
  • func WorkloadControllers() []Controller
• type ConversionWebhookOptions
• type Node
  • func (n *Node) Cordon(t testing.TB)
  • func (n *Node) CordonCtx(ctx context.Context) error
  • func (n *Node) Delete(t testing.TB)
  • func (n *Node) DeleteCtx(ctx context.Context) error
  • func (n *Node) Drain(t testing.TB, opts ...WaitOption)
  • func (n *Node) DrainCtx(ctx context.Context, opts ...WaitOption) error
  • func (n *Node) Name() string
  • func (n *Node) SetReady(t testing.TB, ready bool)
  • func (n *Node) SetReadyCtx(ctx context.Context, ready bool) error
  • func (n *Node) Taint(t testing.TB, taints ...corev1.Taint)
  • func (n *Node) TaintCtx(ctx context.Context, taints ...corev1.Taint) error
  • func (n *Node) Uncordon(t testing.TB)
  • func (n *Node) UncordonCtx(ctx context.Context) error
  • func (n *Node) Untaint(t testing.TB, taints ...corev1.Taint)
  • func (n *Node) UntaintCtx(ctx context.Context, taints ...corev1.Taint) error
• type NodeOptions
• type ObjectClient
  • func DynamicResource(ri dynamic.ResourceInterface) ObjectClient[*unstructured.Unstructured]
• type Option
  • func WithoutDefaultControllers() Option
• type PodExpectation
  • func (e *PodExpectation) AnyTimes() *PodExpectation
  • func (e *PodExpectation) BindTo(node *Node) *PodExpectation
  • func (e *PodExpectation) Do(action func(ctx context.Context, pod *corev1.Pod) error) *PodExpectation
  • func (e *PodExpectation) Pods() []*corev1.Pod
  • func (e *PodExpectation) Times(n int) *PodExpectation
  • func (e *PodExpectation) Verify(ctx context.Context) error
  • func (e *PodExpectation) Wait(t testing.TB, opts ...WaitOption)
  • func (e *PodExpectation) WaitCtx(ctx context.Context, opts ...WaitOption) error
• type PodMatcher
  • func InNamespace(namespace string) PodMatcher
  • func Labeled(key, value string) PodMatcher
  • func OwnedBy(owner metav1.Object) PodMatcher
  • func PodMatching(desc string, match func(*corev1.Pod) bool) PodMatcher
  • func (m PodMatcher) String() string
• type WaitOption
  • func WithTimeout(d time.Duration) WaitOption

Constants

const (
	// DefaultWaitTimeout bounds a wait whose context has no deadline.
	DefaultWaitTimeout = 30 * time.Second
)

const KubernetesVersion = "1.37"

KubernetesVersion is the Kubernetes minor version this release line of petri targets. petri tags mirror the k8s.io staging modules: petri v0.37.x builds against k8s.io/* v0.37.x, which is Kubernetes 1.37.

Functions

func Retry

func Retry(t testing.TB, cond func(context.Context) (bool, error), opts ...WaitOption)

Retry is RetryUntil for tests: it fails the test when the condition never holds or errors.

func RetryUntil

func RetryUntil(ctx context.Context, cond func(context.Context) (bool, error), opts ...WaitOption) error

RetryUntil runs cond until it holds, it errors, or the timeout expires. It is the escape hatch for waiting on something that is not a single object: discovery, an informer, a side effect.

func WaitFor

func WaitFor[O runtime.Object](
	t testing.TB, client ObjectClient[O], name string, cond Condition[O], opts ...WaitOption,
) O

WaitFor is WaitUntil for tests: it fails the test when the condition never holds or errors, and returns the last observed object.

func WaitUntil

func WaitUntil[O runtime.Object](
	ctx context.Context, client ObjectClient[O], name string, cond Condition[O], opts ...WaitOption,
) (O, error)

WaitUntil waits until cond holds for the object named name, watched through client, and returns the last observed object (nil if it never existed).

The wait reads the object first and starts the watch from that resourceVersion, so a change made just before the wait is not missed. When the initial get finds nothing, the watch starts from "now" and a confirming re-get closes the window in which the object could have appeared. Watch expiry and disconnects are handled by re-getting and re-watching, so the wait only ends when the condition holds, the context is done, or the timeout expires.

The condition receives nil only for an object that is not there, which is what the Deleted condition waits for.

Types

type AdmissionWebhookOptions

type AdmissionWebhookOptions struct {
	// Host and Port of the local webhook server that service-based webhooks
	// are pointed at.
	Host string
	Port int
	// Namespace limits every webhook to one namespace through a
	// metadata.name label selector, merged into any selector the manifest
	// already had. Leave it empty only for webhooks that must see the whole
	// cluster: on the shared control plane an unscoped webhook fires for
	// every test's objects.
	Namespace string
}

AdmissionWebhookOptions configures InstallAdmissionWebhooks.

type Condition

type Condition[O runtime.Object] func(O) (bool, error)

Condition reports whether obj satisfies a wait. It must be a pure predicate: the wait may evaluate it on the same object more than once. It receives nil only for an object that is not there.

func Deleted

func Deleted[O runtime.Object]() Condition[O]

Deleted holds once the object is gone, including when it never existed.

func Exists

func Exists[O runtime.Object]() Condition[O]

Exists holds once the object is there.

func StatusCondition

func StatusCondition[O runtime.Object](condType string, status metav1.ConditionStatus) Condition[O]

StatusCondition holds once the object's status.conditions contain condType with the given status. It reads any condition shape with string Type and Status fields, from metav1.Condition to CustomResourceDefinitionCondition, and reads *unstructured.Unstructured objects directly, so it works for custom resources fetched through DynamicResource.

Objects whose conditions live elsewhere need a condition written by hand.

type ControlPlane

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

ControlPlane is a kube-apiserver running in this process over an in-memory store. Get the shared one with Start, or a dedicated one with New.

func New

func New(ctx context.Context, opts ...Option) (*ControlPlane, error)

New starts a dedicated control plane. ctx bounds startup only; call Stop to shut it down.

By default the plane runs the namespace controller and the garbage collector, and New returns only once their informers are synced, so the first object a test creates right after startup is seen by both. The guarantee covers the manager's factory informers: the collector's per-resource monitors sync asynchronously after that, with their initial lists covering the practical guarantee. Pass WithoutDefaultControllers to start without them.

func Start

func Start(t testing.TB) *ControlPlane

Start returns the control plane shared by every test in the binary, starting it on first use. If startup fails, every caller fails; only the first one prints the startup logs. The shared control plane lives until the test binary exits.

func (*ControlPlane) AddNode

func (cp *ControlPlane) AddNode(t testing.TB, opts NodeOptions) *Node

AddNode creates a simulated Node, ready and schedulable unless opts say otherwise, and deletes it when the test finishes. Pods reach it through kube-scheduler (SchedulerController) or through ControlPlane.Bind.

A Node belongs to the whole cluster, so AddNode only works on a dedicated control plane from New: the shared one refuses it.

func (*ControlPlane) AddNodeCtx

func (cp *ControlPlane) AddNodeCtx(ctx context.Context, opts NodeOptions) (*Node, error)

AddNodeCtx is AddNode for callers that manage their own lifecycle: the caller owns deletion.

func (*ControlPlane) Bind

func (cp *ControlPlane) Bind(t testing.TB, pod *corev1.Pod, node *Node)

Bind places a Pending Pod on a Node through the pods/binding subresource, exactly as kube-scheduler does. The Node's kubelet then starts it. Bind needs a dedicated control plane without SchedulerController.

func (*ControlPlane) BindCtx

func (cp *ControlPlane) BindCtx(ctx context.Context, pod *corev1.Pod, node *Node) error

BindCtx is Bind returning the error.

func (*ControlPlane) Client

func (cp *ControlPlane) Client() *kubernetes.Clientset

Client returns an admin (system:masters) clientset for the control plane. It is built once and shared; clientsets are safe for concurrent use.

func (*ControlPlane) CompletePod

func (cp *ControlPlane) CompletePod(t testing.TB, pod *corev1.Pod)

CompletePod ends a running Pod's containers with exit code 0 and moves the Pod to Succeeded, as a kubelet reports a finished Job Pod. The kubelet simulator never overrides it.

func (*ControlPlane) CompletePodCtx

func (cp *ControlPlane) CompletePodCtx(ctx context.Context, pod *corev1.Pod) error

CompletePodCtx is CompletePod returning the error.

func (*ControlPlane) Config

func (cp *ControlPlane) Config() *rest.Config

Config returns a new admin (system:masters) client config for the control plane on every call, with high client-side rate limits. Like envtest, it leaves the content type empty so clients default to JSON, which every type, CRDs included, can encode.

func (*ControlPlane) EnableControllers

func (cp *ControlPlane) EnableControllers(t testing.TB, cs ...Controller)

EnableControllers enables built-in controllers on the control plane and returns once the last one's informers have synced, so an object created right afterwards is seen by every enabled controller. A controller that already runs is left alone, and the calls are safe to make concurrently: parallel tests can enable the same controllers without racing, and on the shared control plane controllers stay enabled once enabled, the same model as InstallCRDs. A plane started with WithoutDefaultControllers can enable them too. The opt-out is for tests that want strict envtest semantics, and it is final: such a plane never registers the namespace controller or the garbage collector, and no exported Controller names them, so they cannot be enabled afterwards.

Enabling a controller never enables another: Deployment without ReplicaSet creates ReplicaSets but no Pods. With no controllers named, EnableControllers does nothing.

Errors fail the test, in the style of Start.

func (*ControlPlane) Evict

func (cp *ControlPlane) Evict(t testing.TB, pod *corev1.Pod)

Evict evicts a Pod through the Eviction API, which honours PodDisruptionBudgets: an eviction a budget refuses fails the test. Use EvictCtx to assert on the refusal, a TooManyRequests error.

func (*ControlPlane) EvictCtx

func (cp *ControlPlane) EvictCtx(ctx context.Context, pod *corev1.Pod) error

EvictCtx is Evict returning the error, which wraps the API error so apierrors.IsTooManyRequests reports a PodDisruptionBudget refusal.

func (*ControlPlane) ExpectPod

func (cp *ControlPlane) ExpectPod(t testing.TB, matchers ...PodMatcher) *corev1.Pod

ExpectPod waits for a Pending Pod that no node was picked for yet, matching every matcher, and returns it. Each Pod is handed out once: the next call waits for another one, so a test expects three replicas with three calls. Pods the declarative expectations of ControlPlane.ExpectPods claim are never returned. The test then decides the Pod's fate, typically with ControlPlane.Bind; until then it stays Pending.

It needs a dedicated control plane without SchedulerController, and fails the test after DefaultWaitTimeout.

func (*ControlPlane) ExpectPodCtx

func (cp *ControlPlane) ExpectPodCtx(ctx context.Context, matchers ...PodMatcher) (*corev1.Pod, error)

ExpectPodCtx is ExpectPod returning the error. It waits until ctx's deadline, or DefaultWaitTimeout when ctx has none.

func (*ControlPlane) ExpectPods

func (cp *ControlPlane) ExpectPods(t testing.TB, matchers ...PodMatcher) *PodExpectation

ExpectPods registers a declarative expectation, in the style of gomock: it claims Pending Pods matching every matcher as they arrive, one by default (see PodExpectation.Times), and applies its action to each (see PodExpectation.BindTo and PodExpectation.Do); without one, claimed Pods stay Pending. When the test finishes, an expectation that claimed fewer Pods than its count, or whose action failed, fails the test.

Expectations claim Pods before ControlPlane.ExpectPod does, in the order they were registered. ExpectPods needs a dedicated control plane without SchedulerController.

func (*ControlPlane) ExpectPodsCtx

func (cp *ControlPlane) ExpectPodsCtx(ctx context.Context, matchers ...PodMatcher) (*PodExpectation, error)

ExpectPodsCtx is ExpectPods for suites without a testing.TB, such as Ginkgo's: nothing is checked when the test finishes, so call PodExpectation.Verify at the end. ctx bounds the start of the Pod watch only.

func (*ControlPlane) FailPod

func (cp *ControlPlane) FailPod(t testing.TB, pod *corev1.Pod, exitCode int32)

FailPod ends a running Pod's containers with exitCode, which must not be 0, and moves the Pod to Failed. The kubelet simulator never overrides it.

func (*ControlPlane) FailPodCtx

func (cp *ControlPlane) FailPodCtx(ctx context.Context, pod *corev1.Pod, exitCode int32) error

FailPodCtx is FailPod returning the error.

func (*ControlPlane) InstallAdmissionWebhooks

func (cp *ControlPlane) InstallAdmissionWebhooks(
	t testing.TB, opts AdmissionWebhookOptions, sources ...any,
)

InstallAdmissionWebhooks installs Mutating and ValidatingWebhookConfiguration manifests from the same kinds of sources InstallCRDs takes, rewires each service-based webhook to the local server on Host:Port, keeps the path, and sets the control plane CA as the caBundle. Manifests that carry their own URL are left untouched.

Each configuration is installed under its manifest name plus a unique suffix, so parallel tests can install the same manifests, and the configurations are deleted when the test finishes.

func (*ControlPlane) InstallAdmissionWebhooksCtx

func (cp *ControlPlane) InstallAdmissionWebhooksCtx(
	ctx context.Context, opts AdmissionWebhookOptions, sources ...any,
) (func() error, error)

InstallAdmissionWebhooksCtx is InstallAdmissionWebhooks for callers that manage their own lifecycle, such as the envtest drop-in: it returns the cleanup that deletes the installed configurations.

func (*ControlPlane) InstallCRDs

func (cp *ControlPlane) InstallCRDs(t testing.TB, sources ...any)

InstallCRDs installs CRDs from sources into the control plane and returns once every one is Established and its resources appear in discovery, so a RESTMapper built right afterwards resolves them.

Sources are file and directory paths, an fs.FS (so //go:embed works), and *apiextensionsv1.CustomResourceDefinition objects. YAML and JSON manifests are read, including multi-document files; documents that are not CRDs are skipped, as envtest does.

A CRD that is already installed with an equivalent spec, compared after the server's defaulting, is left alone; a different spec fails the test with a readable diff. CRDs are never deleted: other tests on the shared control plane may still be using them.

func (*ControlPlane) InstallCRDsCtx

func (cp *ControlPlane) InstallCRDsCtx(ctx context.Context, sources ...any) error

InstallCRDsCtx is InstallCRDs for callers that need the error instead of a failed test, such as Ginkgo suites and the envtest drop-in.

func (*ControlPlane) InstallConversionWebhooks

func (cp *ControlPlane) InstallConversionWebhooks(
	t testing.TB, opts ConversionWebhookOptions, crdNames ...string,
)

InstallConversionWebhooks patches the named CRDs' webhook conversion to point at the local server on Host:Port, keeping the path and setting the control plane CA as the caBundle. Manifests that carry their own URL are left untouched.

A CRD applies to the whole control plane, so conversion webhooks are only allowed on a dedicated control plane from New: on the shared one, a CRD rewrite would change what every other test sees.

func (*ControlPlane) InstallConversionWebhooksCtx

func (cp *ControlPlane) InstallConversionWebhooksCtx(
	ctx context.Context, opts ConversionWebhookOptions, crdNames ...string,
) error

InstallConversionWebhooksCtx is InstallConversionWebhooks for callers that need the error instead of a failed test.

func (*ControlPlane) Namespace

func (cp *ControlPlane) Namespace(t testing.TB) string

Namespace creates a namespace named after the test plus a random suffix and deletes it when the test finishes. The namespace controller runs by default, so the cleanup actually frees the namespace: once its contents are deleted, the namespace itself is removed rather than lingering as Terminating. Start a plane with WithoutDefaultControllers for envtest's behaviour, where deleted namespaces stay Terminating forever.

func (*ControlPlane) NewNamespace

func (cp *ControlPlane) NewNamespace(ctx context.Context) (string, error)

NewNamespace creates a namespace with a random name and no test-name prefix, for helpers and tests that manage their own lifecycle: the caller owns deletion. It retries on name collisions like Namespace does.

func (*ControlPlane) ServingCertDir

func (cp *ControlPlane) ServingCertDir(t testing.TB) string

ServingCertDir writes a serving certificate and key for 127.0.0.1 and localhost, signed by the control plane CA, into a directory that dies with the test. A controller-runtime webhook server loads the pair directly from CertDir; this is petri's only disk use.

func (*ControlPlane) SetPodReady

func (cp *ControlPlane) SetPodReady(t testing.TB, pod *corev1.Pod, ready bool)

SetPodReady sets a running Pod's readiness, its containers' included, as a readiness probe starting or stopping to pass would. The kubelet simulator never overrides it.

func (*ControlPlane) SetPodReadyCtx

func (cp *ControlPlane) SetPodReadyCtx(ctx context.Context, pod *corev1.Pod, ready bool) error

SetPodReadyCtx is SetPodReady returning the error.

func (*ControlPlane) Stop

func (cp *ControlPlane) Stop() error

Stop shuts the control plane down and waits for it. It is safe to call more than once and from several goroutines.

func (*ControlPlane) StrictPods

func (cp *ControlPlane) StrictPods(t testing.TB)

StrictPods makes the control plane fail the test, when it finishes, for every Pending Pod no expectation claimed: a Pod nobody expected, in the style of a strict mock. Pods bound with ControlPlane.Bind count as expected. It needs a dedicated control plane without SchedulerController.

func (*ControlPlane) StrictPodsCtx

func (cp *ControlPlane) StrictPodsCtx(ctx context.Context) error

StrictPodsCtx is StrictPods for suites without a testing.TB, such as Ginkgo's: it starts tracking Pods, and the suite checks ControlPlane.UnexpectedPods at the end. ctx bounds the start of the Pod watch only.

func (*ControlPlane) UnexpectedPods

func (cp *ControlPlane) UnexpectedPods() []string

UnexpectedPods returns, as namespace/name and sorted, every Pending Pod the control plane observed since Pod expectations started that nobody claimed: what ControlPlane.StrictPods fails the test with. Pods bound with ControlPlane.Bind count as claimed.

func (*ControlPlane) WebhookCABundle

func (cp *ControlPlane) WebhookCABundle() []byte

WebhookCABundle returns the PEM-encoded certificate authority the control plane generated at startup. The install helpers set it as every webhook's caBundle; a webhook whose manifest carries its own URL needs it to have its serving certificate trusted.

func (*ControlPlane) WriteServingCert

func (cp *ControlPlane) WriteServingCert(dir string) error

WriteServingCert is ServingCertDir for callers that own their directory, such as the envtest drop-in.

type Controller

type Controller string

Controller identifies a built-in controller that ControlPlane.EnableControllers can run on a control plane. The names follow kube-controller-manager's --controllers flag values.

const (
	DeploymentController       Controller = controllers.DeploymentName
	ReplicaSetController       Controller = controllers.ReplicaSetName
	StatefulSetController      Controller = controllers.StatefulSetName
	DaemonSetController        Controller = controllers.DaemonSetName
	JobController              Controller = controllers.JobName
	CronJobController          Controller = controllers.CronJobName
	TTLAfterFinishedController Controller = controllers.TTLAfterFinishedName
)

The workload controllers.

Without Nodes (ControlPlane.AddNode) Pods never leave Pending, so on a nodeless plane each controller stops where node state would be needed:

• Deployment creates ReplicaSets. Enabling it alone creates no Pods: enabling a controller never enables another. Enable ReplicaSet too for the Pods.
• ReplicaSet realizes spec.replicas as Pending Pods, scaling included.
• StatefulSet with the default OrderedReady policy creates Pod 0 and stops there: Pod 0 can never become Ready.
• DaemonSet creates no Pods at all, because there are no nodes to run its Pods on.
• Job creates Pending Pods up to spec.parallelism; the Job never completes.
• CronJob schedules by wall clock, and upstream injects no clock, so tests that need a Job now create one from the CronJob's spec.jobTemplate themselves.
• TTLAfterFinished deletes Jobs ttlSecondsAfterFinished seconds after a Complete or Failed condition marks them finished.

On a dedicated plane with Nodes, the chain runs end to end: Deployments become Available, StatefulSets roll out Pod after Pod, DaemonSets place a Pod per eligible Node, and Jobs complete once the test completes their Pods with ControlPlane.CompletePod.

const (
	EndpointSliceController       Controller = controllers.EndpointSliceName
	ServiceAccountController      Controller = controllers.ServiceAccountName
	ServiceAccountTokenController Controller = controllers.ServiceAccountTokenName
	ResourceQuotaController       Controller = controllers.ResourceQuotaName
	DisruptionController          Controller = controllers.DisruptionName
)

The remaining built-in controllers.

• EndpointSlice gives every Service with a selector an EndpointSlice owned by it, with no endpoints: no Pod is ever Ready on a nodeless plane. The legacy Endpoints controller and the mirroring controller are not registered — see internal/controllers/endpointslice.go for the scoping decision.
• ServiceAccount keeps a default ServiceAccount in every namespace. The ServiceAccount admission plugin stays disabled: it applies to the whole API server, and enabling it would make Pod creation race against ServiceAccount creation in new namespaces.
• ServiceAccountToken fills the tokens of legacy service-account token Secrets with a JWT signed by the API server's own in-memory signing key, so a TokenReview authenticates them. It does not mint a Secret per ServiceAccount any more (1.37 removed that with bound tokens).
• ResourceQuota keeps a quota's status.used tracking reality; the ResourceQuota admission plugin is on by default, so hard limits are enforced even while the controller is off.
• Disruption drives PodDisruptionBudget statuses from Pod facts. Without ready Pods every budget settles on zero disruptionsAllowed, the safe nodeless value.

const SchedulerController Controller = controllers.SchedulerName

SchedulerController runs upstream kube-scheduler with its default profile, placing Pods on the Nodes from ControlPlane.AddNode by their requests, taints and tolerations, node selectors, affinities and topology spread, as on a real cluster. It is only available on a dedicated control plane, and it excludes placing Pods by hand: a plane uses either the scheduler or ControlPlane.Bind and Pod expectations, never both.

func WorkloadControllers

func WorkloadControllers() []Controller

WorkloadControllers returns the workload controllers as a fresh slice, so a test can enable the whole set:

cp.EnableControllers(t, petri.WorkloadControllers()...)

type ConversionWebhookOptions

type ConversionWebhookOptions struct {
	// Host and Port of the local conversion webhook server.
	Host string
	Port int
}

ConversionWebhookOptions configures InstallConversionWebhooks.

type Node

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

Node is a simulated Node petri created on a dedicated control plane. Its kubelet is petri's simulator: Pods bound to it start at once and deleted Pods go away at once, while the Node is Ready. Use its methods to change it the way a cluster operator or a failing kubelet would.

func (*Node) Cordon

func (n *Node) Cordon(t testing.TB)

Cordon marks the Node unschedulable, as kubectl cordon does.

func (*Node) CordonCtx

func (n *Node) CordonCtx(ctx context.Context) error

CordonCtx is Cordon returning the error.

func (*Node) Delete

func (n *Node) Delete(t testing.TB)

Delete deletes the Node and force-deletes the Pods bound to it, as the Pod garbage collector does for Pods on a Node that no longer exists.

func (*Node) DeleteCtx

func (n *Node) DeleteCtx(ctx context.Context) error

DeleteCtx is Delete returning the error. Deleting a Node that is already gone succeeds.

func (*Node) Drain

func (n *Node) Drain(t testing.TB, opts ...WaitOption)

Drain cordons the Node and evicts its Pods through the Eviction API, as kubectl drain --ignore-daemonsets does, retrying evictions a PodDisruptionBudget refuses. It returns once the evicted Pods are gone, failing the test after the wait timeout.

func (*Node) DrainCtx

func (n *Node) DrainCtx(ctx context.Context, opts ...WaitOption) error

DrainCtx is Drain returning the error.

func (*Node) Name

func (n *Node) Name() string

Name returns the Node's name.

func (*Node) SetReady

func (n *Node) SetReady(t testing.TB, ready bool)

SetReady sets the Node's Ready condition, as a kubelet that stopped or resumed reporting would, and keeps the not-ready NoSchedule taint in step, as the node lifecycle controller does. While the Node is not Ready its kubelet does nothing: bound Pods do not start and deleted Pods stay Terminating. Nothing is evicted: petri runs no taint-eviction controller.

func (*Node) SetReadyCtx

func (n *Node) SetReadyCtx(ctx context.Context, ready bool) error

SetReadyCtx is SetReady returning the error.

func (*Node) Taint

func (n *Node) Taint(t testing.TB, taints ...corev1.Taint)

Taint adds taints to the Node, replacing any with the same key and effect. A NoExecute taint does not evict anything: petri runs no taint-eviction controller.

func (*Node) TaintCtx

func (n *Node) TaintCtx(ctx context.Context, taints ...corev1.Taint) error

TaintCtx is Taint returning the error.

func (*Node) Uncordon

func (n *Node) Uncordon(t testing.TB)

Uncordon marks the Node schedulable again.

func (*Node) UncordonCtx

func (n *Node) UncordonCtx(ctx context.Context) error

UncordonCtx is Uncordon returning the error.

func (*Node) Untaint

func (n *Node) Untaint(t testing.TB, taints ...corev1.Taint)

Untaint removes the Node's taints matching the given ones by key and effect; their values are ignored.

func (*Node) UntaintCtx

func (n *Node) UntaintCtx(ctx context.Context, taints ...corev1.Taint) error

UntaintCtx is Untaint returning the error.

type NodeOptions

type NodeOptions struct {
	// Name is the Node's name; empty picks petri-node-<random>.
	Name string
	// Labels are added to the well-known labels a kubelet sets
	// (kubernetes.io/hostname, kubernetes.io/os, kubernetes.io/arch), and
	// override them.
	Labels map[string]string
	// Annotations are added to the Node's annotations.
	Annotations map[string]string
	// Taints are the Node's taints from the start, so no Pod that does not
	// tolerate them is ever scheduled there.
	Taints []corev1.Taint
	// Capacity overrides the default capacity per resource: 32 CPUs, 256Gi
	// of memory, 1Ti of ephemeral storage and 110 Pods. Allocatable equals
	// capacity.
	Capacity corev1.ResourceList
	// Unschedulable creates the Node cordoned.
	Unschedulable bool
}

NodeOptions describes a Node for ControlPlane.AddNode. The zero value is a ready, schedulable Node with a generated name and default capacity.

type ObjectClient

type ObjectClient[O runtime.Object] interface {
	Get(ctx context.Context, name string, opts metav1.GetOptions) (O, error)
	Watch(ctx context.Context, opts metav1.ListOptions) (watch.Interface, error)
}

ObjectClient is the part of a client-go resource interface that the wait helpers need. Every typed resource client satisfies it as-is, for example cs.AppsV1().Deployments(ns) or an apiextensions CRD client. For the dynamic client, wrap its ResourceInterface with DynamicResource.

func DynamicResource

func DynamicResource(ri dynamic.ResourceInterface) ObjectClient[*unstructured.Unstructured]

DynamicResource adapts a dynamic.ResourceInterface so waits can follow resources that have no typed client, CRDs included.

type Option

type Option func(*startOptions)

Option adjusts how New starts a dedicated control plane.

func WithoutDefaultControllers

func WithoutDefaultControllers() Option

WithoutDefaultControllers starts the control plane without the built-in controllers petri runs by default, the namespace controller and the garbage collector. Deleted namespaces then stay Terminating with their contents, and deleting an owner leaves its dependents behind: the semantics of envtest, which runs no controllers. Use it for tests that rely on envtest behaviour; with the defaults, a deleted namespace really goes away and ownerReferences cascade. The opt-out is final: the plane never registers the two controllers, and no exported Controller names them, so ControlPlane.EnableControllers cannot enable them afterwards.

The shared control plane (Start) always runs the defaults; the envtest drop-in runs them too, unless its environment opts out.

type PodExpectation

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

PodExpectation is a declarative expectation from ControlPlane.ExpectPods: it claims matching Pending Pods as they arrive, up to its count, and applies its action to each. Its methods configure it and return it, for chaining; they are safe to call while Pods arrive, and an action set late still applies to the Pods already claimed.

func (*PodExpectation) AnyTimes

func (e *PodExpectation) AnyTimes() *PodExpectation

AnyTimes makes the expectation claim every matching Pod and require none.

func (*PodExpectation) BindTo

func (e *PodExpectation) BindTo(node *Node) *PodExpectation

BindTo binds every claimed Pod to node, as ControlPlane.Bind does.

func (*PodExpectation) Do

func (e *PodExpectation) Do(action func(ctx context.Context, pod *corev1.Pod) error) *PodExpectation

Do runs action on every claimed Pod, once per Pod, in a goroutine of its own; an error fails the test when it finishes. It replaces any earlier action for the Pods not acted on yet.

func (*PodExpectation) Pods

func (e *PodExpectation) Pods() []*corev1.Pod

Pods returns copies of the Pods the expectation claimed so far, in arrival order, as they were when claimed.

func (*PodExpectation) Times

func (e *PodExpectation) Times(n int) *PodExpectation

Times sets how many Pods the expectation claims and requires, 1 by default. Times(0) claims none, so with ControlPlane.StrictPods a matching Pod fails the test.

func (*PodExpectation) Verify

func (e *PodExpectation) Verify(ctx context.Context) error

Verify waits, bounded by ctx, for the actions in flight and returns what ExpectPods would fail the test with: too few Pods claimed, or failed actions.

func (*PodExpectation) Wait

func (e *PodExpectation) Wait(t testing.TB, opts ...WaitOption)

Wait waits until the expectation claimed its count of Pods and their actions finished, failing the test on a timeout or a failed action.

func (*PodExpectation) WaitCtx

func (e *PodExpectation) WaitCtx(ctx context.Context, opts ...WaitOption) error

WaitCtx is Wait returning the error.

type PodMatcher

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

PodMatcher selects Pods for ControlPlane.ExpectPod and ControlPlane.ExpectPods. A Pod matches a list of matchers when it matches every one. Build one with InNamespace, Labeled, OwnedBy or PodMatching.

func InNamespace

func InNamespace(namespace string) PodMatcher

InNamespace matches the Pods of one namespace.

func Labeled

func Labeled(key, value string) PodMatcher

Labeled matches the Pods carrying a label with the given value.

func OwnedBy

func OwnedBy(owner metav1.Object) PodMatcher

OwnedBy matches the Pods with an owner reference to owner, such as the ReplicaSet, Job or StatefulSet that created them.

func PodMatching

func PodMatching(desc string, match func(*corev1.Pod) bool) PodMatcher

PodMatching returns a matcher from a predicate. desc describes it in failure messages, as in "expected 3 Pods <desc>".

func (PodMatcher) String

func (m PodMatcher) String() string

String returns the matcher's description.

type WaitOption

type WaitOption func(*waitConfig)

WaitOption adjusts a wait or a retry.

func WithTimeout

func WithTimeout(d time.Duration) WaitOption

WithTimeout overrides how long the wait or retry may take. A context with a shorter deadline still wins.