e2eish

package
v0.15.0 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Overview

Package e2eish runs a policy against a synthetic machine, the way the resource manager drives it, to replay e2e tests as unit tests. See "Replaying test logs as unit tests" in test/e2e/README.md.

Index

Constants

View Source
const (
	DefaultCPU    = "1"
	DefaultMem    = "100M"
	DefaultCPUReq = "1"
	DefaultCPULim = "2"
	DefaultMemReq = "100M"
	DefaultMemLim = "200M"
)

Template defaults of a PodSpec.

View Source
const (
	Guaranteed = "guaranteed"
	Burstable  = "burstable"
	BestEffort = "besteffort"
)

QoS classes of the templates.

View Source
const NoInterrupts = "e2eish: no interrupt matches this"

NoInterrupts is a controllable interrupt pattern which matches no interrupt, to keep a policy off the IRQs of the host.

Variables

View Source
var (
	// Log is the logger of the harness, for the steps of a test.
	Log = logger.NewLogger("e2eish")
)

Functions

func NewMachine

func NewMachine(t *testing.T, topo Topology, host Host) system.System

NewMachine builds the machine qemu gives the e2e VM of the topology. CPUs are numbered package by package, die by die, node by node, core by core, with sibling threads adjacent, and dies are numbered across packages. Node distances are 10 to self, 11 within a die and 21 otherwise, unless NodeDist says else. Each core has its own L1 and L2, and its first CPU is its cluster ID. Each die has an L3. Cache overrides of the host replace these. A kernel with NUMA disabled has no nodes in sysfs.

func PodQOS

func PodQOS(pod *corev1.Pod) string

PodQOS gives the QoS class of a pod, "" for guaranteed.

func Reexec

func Reexec(t *testing.T, env ...string) bool

Reexec runs the test again in a child process with the given VAR=VALUE environment, for variables a package reads when the test binary starts. It returns true in the parent, which has nothing left to do then. The parent logs what the child test logged, and skips if the child skipped.

func Replay

func Replay(t *testing.T, plugin *Plugin)

Replay replays the E2EISH records of the e2e test logs in testdata/e2eish-replay and $E2EISH_REPLAY against the policy of the plugin, each as a subtest. See "Replaying test logs as unit tests" in test/e2e/README.md.

Types

type Container

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

Container is a container of a Pod, built with options.

func NewContainer

func NewContainer(name string, options ...ContainerOption) *Container

NewContainer returns a container with the options.

type ContainerOption

type ContainerOption func(*Container)

ContainerOption is an option of a Container.

func WithExtendedResource

func WithExtendedResource(name, quantity string) ContainerOption

WithExtendedResource gives a container an extended resource, like example.com/foo. Its request is its limit, as kubernetes requires.

func WithLimits

func WithLimits(cpu, mem string) ContainerOption

WithLimits sets the CPU and memory limits of a container, as resource quantities. "" leaves one unset.

func WithRequests

func WithRequests(cpu, mem string) ContainerOption

WithRequests sets the CPU and memory requests of a container, as resource quantities. "" leaves one unset.

type CtrSpec

type CtrSpec struct {
	Pod cache.Pod
	QoS string
	Res Resources
}

CtrSpec is what a container is created from. QoS is "" for guaranteed, burstable or besteffort.

type Group

type Group struct {
	Mem      string      // memory per node, like 2G for 2Gi
	Cores    int         // cores per node, none for memory-only nodes
	Threads  int         // threads per core, 2 by default
	Nodes    int         // nodes per die, 1 by default
	Dies     int         // dies per package, 1 by default
	Packages int         // 1 by default
	NodeDist map[int]int // distances to other nodes, both ways
}

Group is one entry of an e2e topology.var.json. Zero fields take the defaults of test/e2e/lib/topology2qemuopts.py.

type Harness

type Harness struct {
	T       *testing.T
	Plugin  *Plugin
	Machine system.System
	Cache   cache.Cache
	Policy  policyapi.Backend
	Owner   *Owner
	Pods    map[string]cache.Pod       // live pods by name
	Ctrs    map[string]cache.Container // live containers by name
	// contains filtered or unexported fields
}

Harness is one e2e test run of a policy: a machine, and the policy and cache of the policy last launched.

func New

func New(t *testing.T, plugin *Plugin, topo Topology, host Host) *Harness

New returns a harness for the plugin on the machine of the topology.

func (*Harness) Allowed

func (h *Harness) Allowed(name string) (cpuset.CPUSet, string)

Allowed is report allowed: the CPUs and memory nodes a container may use, as the e2e tests see them in /proc/self/status. The memory nodes are a cpuset string, "" for all of them.

func (*Harness) CreateContainer

func (h *Harness) CreateContainer(spec CtrSpec, name string) (cache.Container, error)

CreateContainer does what the resource manager does for CreateContainer and StartContainer. A container which fails allocation is left stale.

func (*Harness) CreateFromPod

func (h *Harness) CreateFromPod(ns string, pod *corev1.Pod)

CreateFromPod creates a pod and starts its containers as the kubelet would for the pod object, init containers first, one at a time to completion. Containers which fail allocation are left stale.

func (*Harness) DeletePods

func (h *Harness) DeletePods(names ...string)

DeletePods is kubectl delete pods.

func (*Harness) InsertContainer

func (h *Harness) InsertContainer(spec CtrSpec, name string) cache.Container

InsertContainer adds a container to the cache, as the resource manager does first for CreateContainer, with the resources the kubelet would give it.

func (*Harness) InsertPod

func (h *Harness) InsertPod(ns, name, qos string, labels, annotations map[string]string) cache.Pod

InsertPod does what the resource manager does for RunPodSandbox. qos is "" for guaranteed, burstable or besteffort.

func (*Harness) Launch

func (h *Harness) Launch(cfg any)

Launch is helm-launch: it starts a fresh policy with the configuration. Like helm-terminate, it drops the state of any earlier policy.

func (*Harness) LaunchFails

func (h *Harness) LaunchFails(cfg any)

LaunchFails is expect-launch-failure.

func (*Harness) LaunchMayFail

func (h *Harness) LaunchMayFail(cfg any) bool

LaunchMayFail is helm-launch with expect_error=1. It tells if the policy started.

func (*Harness) Running

func (h *Harness) Running() []string

Running gives the names of the running containers, sorted.

func (*Harness) Spec

func (h *Harness) Spec(name string) CtrSpec

Spec returns what a container was created from.

func (*Harness) StopContainer

func (h *Harness) StopContainer(c cache.Container)

StopContainer does what the resource manager does for StopContainer and RemoveContainer.

type Host

type Host struct {
	Caches   string // the OVERRIDE_SYS_CACHES JSON of an e2e helm config
	NoNUMA   bool   // the kernel has NUMA disabled
	Isolated string // CPUs isolated on the kernel command line
}

Host is what the e2e VM changes of the machine of its topology.

type Owner

type Owner struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Owner is the owner of the policy, the resource manager. It keeps the DRA devices the policy publishes.

func (*Owner) DRAListAttributesSupported

func (*Owner) DRAListAttributesSupported() bool

DRAListAttributesSupported implements policyapi.Owner. It is true, as the harness has no API server which could reject a list attribute.

func (*Owner) Devices

func (o *Owner) Devices() []resourceapi.Device

Devices returns the DRA devices the policy published last.

func (*Owner) PublishDRADevices

func (o *Owner) PublishDRADevices(devices []resourceapi.Device) error

PublishDRADevices implements policyapi.Owner.

func (*Owner) UpdateContainers

func (*Owner) UpdateContainers() error

UpdateContainers implements policyapi.Owner.

type Plugin

type Plugin struct {
	// Name is the name of its helm chart, in deployment/helm.
	Name string
	// CRD is the file of its configuration CRD in the crds of the chart.
	CRD string
	// New creates a policy.
	New func() policyapi.Backend
	// Config returns a new, empty configuration, for a launch to unmarshal
	// the configuration into.
	Config func() any
	// OffHost returns a copy of a configuration with NoInterrupts as its
	// only controllable interrupts.
	OffHost func(cfg any) any
	// Unsupported tells why the replay cannot follow a configuration or a
	// pod, if it cannot. Either can be nil.
	UnsupportedConfig func(cfg any) string
	UnsupportedPod    func(pod *corev1.Pod) string
}

Plugin is what the harness needs to know of a policy.

func (*Plugin) HelmConfig

func (p *Plugin) HelmConfig(values ...json.RawMessage) (any, map[string]string, error)

HelmConfig returns the configuration and the extra environment a helm launch of the plugin with the given values files gives the policy. The values of the chart are merged with the given ones in order, as helm does, and the defaults of the CRD are applied to the configuration, as the API server does.

type Pod

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

Pod is a pod of a Script step, built with options.

func NewPod

func NewPod(name string, options ...PodOption) *Pod

NewPod returns a pod in the default namespace with the options.

type PodOption

type PodOption func(*Pod)

PodOption is an option of a Pod.

func InNamespace

func InNamespace(ns string) PodOption

InNamespace puts a pod in a namespace.

func WithAnnotations

func WithAnnotations(annotations map[string]string) PodOption

WithAnnotations gives a pod annotations.

func WithContainers

func WithContainers(ctrs ...*Container) PodOption

WithContainers gives a pod containers.

func WithInitContainers

func WithInitContainers(ctrs ...*Container) PodOption

WithInitContainers gives a pod init containers.

func WithLabels

func WithLabels(labels map[string]string) PodOption

WithLabels gives a pod labels.

func WithRunning

func WithRunning(names ...string) PodOption

WithRunning tells which containers of a runtime pod run. By default all of them do.

type PodSpec

type PodSpec struct {
	Name        string // pod<N> by default, with N pods created before
	Namespace   string
	ContCount   int               // 1 by default
	IContCount  int               // init containers
	CPU, Mem    string            // guaranteed, 1 and 100M by default
	CPUReq      string            // burstable, 1 by default
	CPULim      string            // burstable, 2 by default, "0" for none
	MemReq      string            // burstable, 100M by default, "0" for none
	MemLim      string            // burstable, 200M by default, "0" for none
	Labels      map[string]string // besides app
	Annotations map[string]string
}

PodSpec is a pod as the guaranteed, burstable and besteffort templates of the e2e tests create it: containers NAMEc0, NAMEc1..., init containers NAMEc0i..., all with the same resources, and the label app=NAME. Unset fields take the defaults of the templates.

type Resources

type Resources struct {
	CPUReq, CPULim int64 // in milli-CPUs, 0 for unset
	MemReq, MemLim int64 // in bytes, 0 for unset
}

Resources are the resources of a container, as the kubelet gives them.

func ResourcesOf

func ResourcesOf(c *corev1.Container) Resources

ResourcesOf gives the resources of a container. A request left out is the limit.

type Script

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

Script runs the steps of an e2e test, one method for each kind of record of its log. Replay drives it from the records of a log, a generated test calls it directly. Helm values are given as YAML, pods as Pods.

func NewScript

func NewScript(t *testing.T, plugin *Plugin) *Script

NewScript returns a script for the plugin. A test with overrides read when the binary starts runs the script in a Reexec child.

func (*Script) Consts

func (s *Script) Consts(code string)

Consts is the py_consts code for the verify expressions after it.

func (*Script) CreateBestEffort

func (s *Script) CreateBestEffort(spec PodSpec)

CreateBestEffort is create besteffort, of the pod of the spec.

func (*Script) CreateBurstable

func (s *Script) CreateBurstable(spec PodSpec)

CreateBurstable is create burstable, of the pod of the spec.

func (*Script) CreateGuaranteed

func (s *Script) CreateGuaranteed(spec PodSpec)

CreateGuaranteed is create guaranteed, of the pod of the spec.

func (*Script) CreatePod

func (s *Script) CreatePod(name string, options ...PodOption)

CreatePod is kubectl create of a pod.

func (*Script) DeleteAllPodsIn

func (s *Script) DeleteAllPodsIn(ns string)

DeleteAllPodsIn is kubectl delete of all the pods in the namespace.

func (*Script) DeletePods

func (s *Script) DeletePods(ns string, names ...string)

DeletePods is kubectl delete of pods in the namespace. Pods not there are left alone.

func (*Script) Harness

func (s *Script) Harness() *Harness

Harness is the harness of the script, nil before the first launch.

func (*Script) Launch

func (s *Script) Launch(topo Topology, values ...string)

Launch is helm-launch of the plugin on the topology, with helm values files merged in order, as helm merges them.

func (*Script) LaunchFails

func (s *Script) LaunchFails(topo Topology, values ...string)

LaunchFails is expect-launch-failure and the helm-launch after it.

func (*Script) LaunchMayFail

func (s *Script) LaunchMayFail(topo Topology, values ...string)

LaunchMayFail is helm-launch with expect_error=1.

func (*Script) ResumeWithRuntimePods

func (s *Script) ResumeWithRuntimePods(pods ...*Pod)

ResumeWithRuntimePods ends a skipped block, with the pods running in the runtime then. The pods and containers gone since the skip are deleted.

func (*Script) SetCmdline

func (s *Script) SetCmdline(cmdline string)

SetCmdline sets the kernel command line, for the next launch. Only isolcpus is supported.

func (*Script) SetNUMA

func (s *Script) SetNUMA(enabled bool)

SetNUMA enables or disables NUMA on the kernel command line, for the next launch.

func (*Script) Skip

func (s *Script) Skip(reason string)

Skip starts a block of the e2e test the replay cannot follow. The pod changes and assertions of the block are ignored.

func (*Script) SyncWithRuntimePods

func (s *Script) SyncWithRuntimePods(pods ...*Pod)

SyncWithRuntimePods is the Synchronize of a starting plugin, with the pods running in the runtime then.

func (*Script) Terminate

func (s *Script) Terminate()

Terminate is helm-terminate.

func (*Script) VerifyPy

func (s *Script) VerifyPy(expr string)

VerifyPy is verify of a python expression which held in the e2e test.

type Topology

type Topology []Group

Topology is an e2e topology.var.json.

Jump to

Keyboard shortcuts

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