goalstates

type AMDHost struct {
	// GPUDevicePaths lists AMD GPU device paths discovered on the host
	// (e.g. /dev/kfd, /dev/dri/card*, /dev/dri/renderD*). When non-empty the
	// nspawn configuration will bind-mount these devices and grant cgroup access
	// so the AMD Kubernetes device plugin can detect GPUs inside the machine.
	GPUDevicePaths []string

	// SysFSPaths lists host sysfs paths the AMD Kubernetes device plugin reads
	// to discover AMD GPUs and KFD topology inside the nspawn machine.
	SysFSPaths []string
}

type AgentUpgradePaths struct {
	BinaryPath        string
	BluePath          string
	GreenPath         string
	CurrentPath       string
	LastGoodPath      string
	SignalPath        string
	CurrentTargetPath string
}

type AppliedConfigLocation struct {
	// Name is the stem passed to AppliedConfigPath.
	Name string
	// Slot is the blue/green slot the config belongs to.
	Slot string
	// Mode is the isolation mode a config stored under Name runs in.
	Mode isolation.Mode
}

type ContainerImageArchiveStaging struct {
	// HostDir is the source-specific host directory containing staged archives.
	HostDir string
	// URLs lists archive sources to download into HostDir.
	URLs []string
}

type Containerd struct {
	SandboxImage      string
	ContainerdBinPath string
	RuncBinaryPath    string
	CNIBinDir         string
	CNIConfDir        string
	MetricsAddress    string
	NvidiaRuntime     NvidiaRuntime
}

type ContainerdOptions struct {
	SandboxImage   string
	NvidiaRequired bool
	// NvidiaToolkit locates the toolkit for the nvidia runtime handler. The
	// zero value is the default install paths.
	NvidiaToolkit NvidiaToolkit
}

type DownloadOverrides struct {
	// Kubernetes overrides the source for kubelet/kubectl/kube-proxy.
	Kubernetes *DownloadSource
	// Containerd overrides the source for the containerd release tarball.
	Containerd *DownloadSource
	// Runc overrides the source for the runc binary.
	Runc *DownloadSource
	// CNI overrides the source for the CNI plugins release tarball.
	CNI *DownloadSource
	// Crictl overrides the source for the crictl release tarball.
	Crictl *DownloadSource
	// CoreDNS overrides the source for the CoreDNS release tarball.
	CoreDNS *DownloadSource
}

type DownloadSource struct {
	BaseURL string
	URL     string
	Version string
}

type Gantry struct {
	Disabled bool
}

type HostDevices struct {
	// KVM holds the KVM character device path (/dev/kvm) when present.
	KVM []string
	// MSHV holds the Microsoft Hypervisor device path (/dev/mshv) when
	// present. Virtual machine monitors such as Cloud Hypervisor use it in
	// place of /dev/kvm when Linux runs as the MSHV root partition.
	MSHV []string
	// Network holds host networking device paths used by virtualization
	// workloads (for example /dev/net/tun and /dev/vhost-net) when present.
	Network []string
	// Block holds storage block device node paths derived from
	// /sys/class/block (whole disks and partitions, excluding virtual
	// devices such as loop/ram/zram).
	Block []string
	// DeviceDirectories holds whole-directory device mounts (for example
	// /dev/infiniband) that are bind-mounted as directories, with cgroup
	// device permissions covering nodes created after the machine starts.
	DeviceDirectories []config.AdditionalHostMount
	// Additional holds extra host device node paths and systemd device group
	// specifiers requested by config.
	Additional []string
}

type HostPaths struct {
	// Root is the host root these paths are under.
	Root string
	// BinDir is <Root>/bin.
	BinDir string
	// NSpawnLifecycleBinary is the rollback-stable helper invoked by the
	// generated nspawn hook units.
	NSpawnLifecycleBinary string
	// DaemonRecoveryScript is executed by the daemon recovery unit.
	DaemonRecoveryScript string
	// LocalDNSNetworkHelper backs unbounded-localdns-network.service.
	LocalDNSNetworkHelper string
}

type ImageCredentialProvider struct {
	ConfigPath string
	BinDir     string
}

type Kubelet struct {
	// KubeletBinPath is the absolute path to the kubelet binary inside the
	// machine container (e.g. /usr/local/bin/kubelet).
	KubeletBinPath string

	// KubeletAuthInfo holds the authentication configuration for the
	// kubelet when KubeconfigData is empty.
	config.KubeletAuthInfo

	// KubeconfigData is a complete kubeconfig written verbatim for direct
	// kubelet authentication.
	KubeconfigData []byte

	// APIServer is the HTTPS endpoint of the Kubernetes API server
	// (e.g. "https://my-cluster.hcp.eastus.azmk8s.io:443").
	APIServer string

	// CACertData is the PEM-encoded CA certificate of the API server.
	CACertData []byte

	// ClusterDNS is the ClusterIP of the kube-dns service.
	ClusterDNS string

	// ResolvConf is the resolver file kubelet uses for dnsPolicy: Default pods.
	ResolvConf string

	// NodeIP overrides kubelet --node-ip. Supports a single IP or a
	// comma-separated dual-stack pair.
	NodeIP string

	// NodeLabels are key=value labels applied to the node at registration.
	NodeLabels map[string]string

	// RegisterWithTaints are taints applied to the node at registration.
	// Each entry uses the kubelet format: "key=value:effect"
	// (e.g. "dedicated=gpu:NoSchedule").
	RegisterWithTaints []string

	// Configuration is merged over the agent's baseline and rendered as a
	// kubelet.config.k8s.io/v1beta1 KubeletConfiguration.
	Configuration map[string]any

	// ImageCredentialProvider holds optional kubelet exec image credential
	// provider paths inside the nspawn machine.
	ImageCredentialProvider *ImageCredentialProvider
}

type LocalDNS struct {
	Enabled                bool
	CoreDNSVersion         string
	NodeListenerIP         netip.Addr
	ClusterListenerIP      netip.Addr
	NodeUpstreamIPs        []netip.Addr
	ClusterDNSServiceIP    netip.Addr
	MetricsAddress         string
	CPULimitInMilliCores   int
	MemoryLimitInMB        int
	RequiredPlugins        []string
	Corefile               []byte
	OriginalHostResolvConf []byte
}

type LocalDNSCorefileTemplateData struct {
	NodeListenerIP        string
	ClusterListenerIP     string
	NodeUpstreamIPs       []string
	NodeUpstreamIPsJoined string
	ClusterDNSServiceIP   string
	MetricsAddress        string
}

type MachineGoalState struct {
	RootFS    *RootFS
	NodeStart *NodeStart
}

type NodeStart struct {
	// MachineName is the local systemd-nspawn machine name (e.g. "kube1").
	// Used by nspawn service management.
	MachineName string

	// KubeMachineName is the Kubernetes Machine CR name (e.g. "agent-e2e").
	// This is the name that appears in the cluster and may differ from
	// the local nspawn machine name.
	KubeMachineName string

	// NodeName is the Kubernetes Node name used by kubelet and host-side daemon watches.
	NodeName string

	// MachineDir is the nspawn backend's root directory. It is an intentional
	// nspawn-only goal state field; phases reach it through Root().
	MachineDir string // e.g. /var/lib/machines/node
	Containerd Containerd
	Gantry     Gantry
	Kubelet    Kubelet
	LocalDNS   LocalDNS

	// Nvidia holds NVIDIA GPU state discovered on the host. After the nspawn
	// boots, the setup-nvidia-libraries task uses LibMappings to create
	// symlinks inside the container's library path pointing into the
	// bind-mounted /run/host-nvidia/ directories.
	Nvidia NvidiaHost

	// NvidiaToolkit locates the NVIDIA Container Toolkit tools on the host. It
	// is set only for isolation mode none; the zero value is the default paths.
	NvidiaToolkit NvidiaToolkit

	// RootOverride replaces the nspawn machine root for backends that do not
	// run the node stack in a machine, such as the none backend. Nil means the
	// nspawn root.
	RootOverride isolation.NodeRoot

	// ExecOverride replaces nspawn.Exec for the same backends. Nil means
	// commands run inside the nspawn machine. A non-nil value also marks the
	// node stack as host native, so phases skip nspawn-only files, unless
	// InContainer is also set.
	ExecOverride func(ctx context.Context, log *slog.Logger, args ...string) (string, error)

	// InContainer marks a node stack that runs in its own root filesystem
	// inside an OCI container (the container backend). Its overrides replace
	// the nspawn machine like the none backend's, but the node stack still has
	// a private root, so phases keep writing the rootfs files and use the
	// in-node archive path. PROVISIONAL: see the container backend.
	InContainer bool
}

type NvidiaHost struct {
	// Required records whether NVIDIA capability was selected when the machine
	// was provisioned. Discovery refreshes must preserve this value.
	Required bool

	// GPUDevicePaths lists NVIDIA GPU device paths discovered on the host
	// (e.g. /dev/nvidia0, /dev/nvidiactl, /dev/nvidia-caps,
	// /dev/nvidia-caps-imex-channels, /dev/dri/*).
	// When non-empty the nspawn configuration will bind-mount these devices
	// and grant the container cgroup access to them.
	GPUDevicePaths []string

	// ContainerLibDir is the architecture-specific multiarch library
	// directory inside the nspawn container (e.g. /usr/lib/x86_64-linux-gnu
	// on amd64, /usr/lib/aarch64-linux-gnu on arm64). Symlinks to
	// bind-mounted host NVIDIA libraries are created here.
	ContainerLibDir string

	// LibMappings contains NVIDIA userspace libraries discovered from
	// ldconfig -p and filesystem scans. These are used to create symlinks
	// inside the nspawn container so that the host's NVIDIA driver libraries
	// are accessible.
	LibMappings []NvidiaLibMapping

	// LibDirMounts lists unique host directories containing NVIDIA libraries
	// to be bind-mounted read-only into the nspawn container at
	// /run/host-nvidia/<index>/. After boot, symlinks from the container's
	// standard library path are created by the setup-nvidia-libraries task.
	LibDirMounts []NvidiaLibDirMount

	// I386LibMappings contains optional i386 NVIDIA and GLVND libraries with a
	// driver version matching the active 64-bit driver.
	I386LibMappings []NvidiaLibMapping

	// I386LibDirMounts lists the host directories for I386LibMappings.
	I386LibDirMounts []NvidiaLibDirMount

	// NvidiaSMIPath is the host path to nvidia-smi, when available.
	NvidiaSMIPath string

	// NvidiaIMEXPath is the host path to nvidia-imex, when available.
	NvidiaIMEXPath string

	// NvidiaIMEXCtlPath is the host path to nvidia-imex-ctl, when available.
	NvidiaIMEXCtlPath string

	// DriverVersion is the active NVIDIA kernel driver version. It is used to
	// provide versioned library names when a host installation exposes only
	// unversioned or SONAME aliases through ldconfig.
	DriverVersion string
}

type NvidiaLibDirMount = isolation.LibDirMount

type NvidiaLibMapping struct {
	HostPath         string // e.g. "/usr/lib/x86_64-linux-gnu/libcuda.so.1", original discovered name
	ResolvedHostPath string // e.g. "/usr/lib/nvidia/libcuda.so.580.126.09", real bind-mount source
	ContainerPath    string // e.g. "/run/host-nvidia/0/libcuda.so.580.126.09", bind-mount source
	LinkPath         string // e.g. "/usr/lib/x86_64-linux-gnu/libcuda.so.1", symlink in container
}

type NvidiaRuntime struct {
	Enabled                    bool
	RuntimeClassName           string
	RuntimePath                string
	DisableSetAsDefaultRuntime bool
}

type NvidiaToolkit struct {
	// CTKPath is the nvidia-ctk executable. Empty means NvidiaCTKPath.
	CTKPath string
	// ContainerRuntimePath is the nvidia-container-runtime executable. Empty
	// means NvidiaContainerRuntimePath.
	ContainerRuntimePath string
}

type OfflineArtifactManifest = bootstrapartifacts.Manifest

type OfflineArtifactVersions = bootstrapartifacts.Versions

type OfflineTemplateData struct {
	KubernetesVersion    string
	KubernetesVersionNoV string
}

type ResolvedOfflineArtifacts struct {
	SourceRoot string
	Manifest   OfflineArtifactManifest
	// contains filtered or unexported fields
}

type RootFS struct {
	// MachineDir is the nspawn backend's root directory. It is an intentional
	// nspawn-only goal state field; phases reach it through Root().
	MachineDir             string
	NSpawnConfigFile       string // e.g. /etc/systemd/nspawn/node.nspawn
	ServiceOverrideFile    string // e.g. /etc/systemd/system/systemd-nspawn@node.service.d/override.conf
	ConfigRegenerationFile string // host systemd pre-start unit
	HostArch               string
	HostKernel             string // running kernel version from uname -r, e.g. "6.8.0-45-generic"
	Hostname               string // host hostname, written into the rootfs so the nspawn container inherits it
	ContainerdVersion      string
	RunCVersion            string
	CNIPluginVersion       string
	KubernetesVersion      string
	LocalDNS               LocalDNS

	// Downloads optionally overrides the download sources for binaries
	// the agent installs into the nspawn rootfs (kubelet, containerd,
	// runc, CNI plugins, crictl). Nil means upstream defaults apply.
	Downloads *DownloadOverrides

	// OCIImage is an OCI registry reference, local OCI layout, or HTTPS URL
	// to a tarred OCI image layout used to bootstrap the machine rootfs. The
	// single tagged image reference in an HTTPS archive is selected automatically.
	// The image must use OCI media types and include a platform manifest
	// matching the host architecture.
	OCIImage string

	// Nvidia holds NVIDIA GPU state discovered on the host: device paths,
	// driver library mappings, and bind-mount specifications for the nspawn
	// container. Empty on non-GPU hosts.
	Nvidia NvidiaHost

	// AMD holds AMD GPU state discovered on the host. Empty on non-AMD GPU hosts.
	AMD AMDHost

	// HostDevices holds host device nodes to be bind-mounted into the
	// nspawn container, grouped by category (KVM, network virtualization,
	// block storage, InfiniBand HCA). Device nodes are discovered at agent
	// startup. Empty on hosts without any supported devices.
	HostDevices HostDevices

	// AdditionalHostMounts holds configured non-device host paths to be
	// bind-mounted into the nspawn container.
	AdditionalHostMounts []config.AdditionalHostMount

	// NSpawnLifecycle holds the configured lifecycle hook commands. Nil means
	// the hooks run the lifecycle helper, which provisioning installs.
	NSpawnLifecycle *config.NSpawnLifecycleConfig

	// RootOverride replaces the nspawn machine root for backends that install
	// onto the host instead of into a machine. Nil means the nspawn root.
	RootOverride isolation.NodeRoot
}