e2eish

package
v0.15.1 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2026 License: Apache-2.0 Imports: 57 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 Disjoint added in v0.15.1 

func Disjoint(sets ...Set) bool

Disjoint is disjoint_sets: no two of the sets share a name.

func Generate added in v0.15.1 

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

Generate writes a Go test for each e2e test log of the plugin in $E2EISH_GENERATE, one e2eish-gen-TOPOLOGY_test.go file for each topology, in the package directory. Build with the e2eish_generate tag, which leaves out the files generated before. The tests run a Script, with the variable e2eishPlugin of the package as the plugin. See "Generating unit tests from test logs" in test/e2e/README.md.

func IDs added in v0.15.1 

func IDs(s Set) []int

IDs is the *_ids helpers: the numbers of the names, sorted. Every name must end in a number of its own, like cpu03, node1 or package0, which is what the names of cpus, nodes, mems and packages do. The composite names of cores, threads and dies, like node1/core3, have no number of their own and panic.

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.

func RequireDisjoint added in v0.15.1 

func RequireDisjoint(t require.TestingT, sets ...Set)

RequireDisjoint requires that no two of the sets share a name.

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 WithClaim added in v0.15.1 

func WithClaim(claim, request string) ContainerOption

WithClaim gives a container a claim of its pod. An empty request gives it everything the claim holds, a named one only what that request of the claim holds.

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
	CDIDevices []string
}

CtrSpec is what a container is created from. QoS is "" for guaranteed, burstable or besteffort. CDIDevices are the qualified names of the CDI devices the runtime reports for the container, those of its DRA claims.

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
	// DRAEnabled is what the configuration of the next launch says, which
	// the Owner of that launch publishes the devices of the policy by.
	DRAEnabled bool
	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, cdiDevices map[string][]string)

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.

  • ns: the namespace of the pod
  • pod: the pod object
  • cdiDevices: the CDI devices of each container, by container name, those the prepared DRA claims of the pod granted it

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) PrepareClaim added in v0.15.1 

func (h *Harness) PrepareClaim(claim *resourceapi.ResourceClaim, results []resourceapi.DeviceRequestAllocationResult)

PrepareClaim does what the resource manager does for a claim the kubelet prepares: the policy allocates the resources of it.

func (*Harness) ReleaseClaims added in v0.15.1 

func (h *Harness) ReleaseClaims(uids ...types.UID)

ReleaseClaims does what the resource manager does for the claims the kubelet unprepares.

func (*Harness) ResizeContainer added in v0.15.1 

func (h *Harness) ResizeContainer(pod, name string, res Resources)

ResizeContainer does what the resource manager does for UpdateContainer: it gives a container of a pod the resources of an in-place resize, and has the policy update what it allocated when they really changed.

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) DRAEnabled added in v0.15.1 

func (o *Owner) DRAEnabled() bool

DRAEnabled implements policyapi.Owner.

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
	// DRADriver is the name of the DRA driver of the policy. An empty one
	// means the replay cannot follow the resource claims of a pod.
	DRADriver 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) (cfg any, env map[string]string, draEnabled bool, err error)

HelmConfig returns the configuration, the extra environment, and whether DRA is enabled, as a helm launch of the plugin with the given values files gives them to 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.

draEnabled is not part of the policy's own configuration: the resource manager reads it, and it is what decides whether the devices the policy publishes reach a cluster at all.

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 FromClaimTemplate added in v0.15.1 

func FromClaimTemplate(claim, template string) PodOption

FromClaimTemplate gives a pod a DRA resource claim of its own, created from the named ResourceClaimTemplate. Its containers hold it by the claim name with WithClaim.

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 NewE2EScript added in v0.15.1 

func NewE2EScript(t *testing.T, plugin *Plugin, target string) *Script

NewE2EScript returns a script for the plugin which is also the source of an e2e test, the target, like n4c16/test50-name, of the test suite of the plugin. A passing test writes it, with E2EISH_EMIT set. See "Generating e2e tests from unit tests" in test/e2e/README.md.

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) CPUIDs added in v0.15.1 

func (s *Script) CPUIDs(ids ...int) Set

CPUIDs is the set of the CPUs, as topology.py names them on the machine.

func (*Script) CPUs added in v0.15.1 

func (s *Script) CPUs(ctr string) Set

CPUs is cpus["ctr"] of e2e verify expressions, and the others likewise.

func (*Script) Consts 

func (s *Script) Consts(code string)

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

func (*Script) Cores added in v0.15.1 

func (s *Script) Cores(ctr string) Set

Cores is cores["ctr"].

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) CreateClaimTemplate added in v0.15.1 

func (s *Script) CreateClaimTemplate(ns, y string)

CreateClaimTemplate is kubectl create of the DRA ResourceClaimTemplate of the YAML, in the namespace, which the claims of a pod naming it are created from.

func (*Script) CreateDeviceClass added in v0.15.1 

func (s *Script) CreateDeviceClass(y string)

CreateDeviceClass is kubectl create of the DRA DeviceClass of the YAML, which the device requests of a claim select devices through.

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) Dies added in v0.15.1 

func (s *Script) Dies(ctr string) Set

Dies is dies["ctr"].

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) Mems added in v0.15.1 

func (s *Script) Mems(ctr string) Set

Mems is mems["ctr"].

func (*Script) NodeIDs added in v0.15.1 

func (s *Script) NodeIDs(ids ...int) Set

NodeIDs is the set of the nodes, as topology.py names them on the machine.

func (*Script) Nodes added in v0.15.1 

func (s *Script) Nodes(ctr string) Set

Nodes is nodes["ctr"].

func (*Script) PackageIDs added in v0.15.1 

func (s *Script) PackageIDs(ids ...int) Set

PackageIDs is the set of the packages, as topology.py names them.

func (*Script) Packages added in v0.15.1 

func (s *Script) Packages(ctr string) Set

Packages is packages["ctr"].

func (*Script) ResizeContainer added in v0.15.1 

func (s *Script) ResizeContainer(ns, pod, ctr string, res Resources)

ResizeContainer is an in-place resize of the resources of a container of a pod, which the runtime gives the policy as a resource update.

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) Threads added in v0.15.1 

func (s *Script) Threads(ctr string) Set

Threads is threads["ctr"].

func (*Script) VerifyPy 

func (s *Script) VerifyPy(expr string)

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

type Set added in v0.15.1 

type Set map[string]struct{}

Set is a set of topology.py names, like the sets of the variables e2e verify expressions see. testify asserts work on it as on any map.

func Difference added in v0.15.1 

func Difference(a, b Set) Set

Difference returns the names of a which b does not have.

func Intersection added in v0.15.1 

func Intersection(sets ...Set) Set

Intersection returns the names of all the sets.

func NewSet added in v0.15.1 

func NewSet(names ...string) Set

NewSet returns a set of the names.

func Union added in v0.15.1 

func Union(sets ...Set) Set

Union returns the names of any of the sets.

func (Set) Equal added in v0.15.1 

func (s Set) Equal(o Set) bool

Equal tells if the sets have the same names.

func (Set) Has added in v0.15.1 

func (s Set) Has(name string) bool

Has tells if the set has the name.

func (Set) IsSubset added in v0.15.1 

func (s Set) IsSubset(o Set) bool

IsSubset tells if o has every name of the set.

func (Set) String added in v0.15.1 

func (s Set) String() string

type Topology 

type Topology []Group

Topology is an e2e topology.var.json.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.