stepspec

type CheckHost struct {
	// Named checks to run against the local host.
	// @deck.example [os,arch,swap]
	Checks []string `json:"checks"`
	// Binary names to verify are present in `PATH`.
	// @deck.example [kubeadm,kubelet,kubectl]
	Binaries []string `json:"binaries"`
	// Stop on the first failing check rather than running all checks.
	// @deck.example true
	FailFast *bool `json:"failFast"`
}

type ClusterCheck struct {
	// Kubeconfig path used for kubectl-based checks.
	// @deck.example /etc/kubernetes/admin.conf
	Kubeconfig string `json:"kubeconfig"`
	// Duration between poll attempts while waiting for cluster state to converge.
	// @deck.example 5s
	Interval string `json:"interval"`
	// Optional delay before the first poll attempt.
	// @deck.example 10s
	InitialDelay string `json:"initialDelay"`
	// Maximum total duration to keep polling before the step fails.
	// @deck.example 10m
	Timeout string `json:"timeout"`
	// Optional checks for cluster node count and readiness.
	// @deck.example {total:1,ready:1,controlPlaneReady:1}
	Nodes ClusterCheckNodes `json:"nodes"`
	// Optional checks for Kubernetes component versions.
	// @deck.example {server:v1.31.0,kubelet:v1.31.0}
	Versions ClusterCheckVersions `json:"versions"`
	// Optional checks for kube-system pod readiness.
	// @deck.example {readyNames:[etcd-control-plane]}
	KubeSystem ClusterCheckKubeSystem `json:"kubeSystem"`
	// Optional file-content assertions evaluated on every poll attempt.
	// @deck.example [{path:/etc/containerd/config.toml,contains:[registry.k8s.io/pause:3.10]}]
	FileChecks []ClusterCheckFileCheck `json:"fileAssertions"`
	// Optional paths for writing node and cluster state reports.
	// @deck.example {nodesPath:/tmp/deck/reports/bootstrap-nodes.txt}
	Reports ClusterCheckReports `json:"reports"`
}

type ClusterCheckFileCheck struct {
	// Path of the local file whose content should be checked.
	// @deck.example /etc/containerd/config.toml
	Path string `json:"path"`
	// Strings that must all be present in the file content.
	// @deck.example [registry.k8s.io/pause:3.10]
	Contains []string `json:"contains"`
}

type ClusterCheckKubeSystem struct {
	// Exact kube-system pod names that must be present and fully Ready.
	// @deck.example [etcd-control-plane,kube-apiserver-control-plane]
	ReadyNames []string `json:"readyNames"`
	// Pod-name prefixes for which at least one matching Ready pod must exist.
	// @deck.example [kube-proxy-]
	ReadyPrefixes []string `json:"readyPrefixes"`
	// Prefix-based readiness requirements with minimum Ready pod counts.
	// @deck.example [{prefix:coredns-,minReady:2}]
	ReadyPrefixMinimums []ClusterCheckReadyPrefixMinimum `json:"readyPrefixMinimums"`
	// Optional text report path for `kubectl get pods -n kube-system`.
	// @deck.example /tmp/deck/reports/kube-system-pods.txt
	ReportPath string `json:"reportPath"`
	// Optional JSON report path for `kubectl get pods -n kube-system -o json`.
	// @deck.example /tmp/deck/reports/kube-system-pods.json
	JSONReportPath string `json:"jsonReportPath"`
}

type ClusterCheckNodes struct {
	// Expected total node count returned by `kubectl get nodes`.
	// @deck.example 1
	Total *int `json:"total"`
	// Expected count of Ready nodes.
	// @deck.example 1
	Ready *int `json:"ready"`
	// Expected count of Ready control-plane nodes.
	// @deck.example 1
	ControlPlaneReady *int `json:"controlPlaneReady"`
}

type ClusterCheckReadyPrefixMinimum struct {
	// Pod-name prefix to match inside `kube-system`.
	// @deck.example coredns-
	Prefix string `json:"prefix"`
	// Minimum number of matching Ready pods required for the prefix.
	// @deck.example 2
	MinReady int `json:"minReady"`
}

type ClusterCheckReports struct {
	// Optional report file path for `kubectl get nodes` output.
	// @deck.example /tmp/deck/reports/bootstrap-nodes.txt
	NodesPath string `json:"nodesPath"`
	// Optional second node report path for shared cluster node reports.
	// @deck.example /tmp/deck/reports/cluster-nodes.txt
	ClusterNodesPath string `json:"clusterNodesPath"`
}

type ClusterCheckVersions struct {
	// Target Kubernetes version written into the optional version report file.
	// @deck.example v1.31.0
	TargetVersion string `json:"targetVersion"`
	// Expected API server version from `kubectl version -o json`.
	// @deck.example v1.31.0
	Server string `json:"server"`
	// Expected kubelet version for the selected node.
	// @deck.example v1.31.0
	Kubelet string `json:"kubelet"`
	// Expected local kubeadm version from `kubeadm version -o short`.
	// @deck.example v1.31.0
	Kubeadm string `json:"kubeadm"`
	// Node name used when reading kubelet version.
	// @deck.example control-plane
	NodeName string `json:"nodeName"`
	// Optional report file that records target, server, kubelet, and kubeadm versions.
	// @deck.example /tmp/deck/reports/upgrade-version.txt
	ReportPath string `json:"reportPath"`
}

type Command struct {
	// Command vector to execute. The first element is the binary and the rest are arguments.
	// @deck.example [systemctl,restart,containerd]
	Command []string `json:"command"`
	// Additional environment variables passed to the command process as key-value pairs.
	// @deck.example {KUBECONFIG:/etc/kubernetes/admin.conf}
	Env map[string]string `json:"env"`
	// Prepend `sudo` before the command vector. Defaults to `false`.
	// @deck.example false
	Sudo bool `json:"sudo"`
	// Maximum duration for the command before it is killed. Overrides the step-level `timeout`.
	// @deck.example 30s
	Timeout string `json:"timeout"`
}

type ConfigureRepository struct {
	// Repository file format to write.
	// @deck.example deb
	Format string `json:"format"`
	// Explicit output path for the generated repository file.
	// @deck.example /etc/apt/sources.list.d/offline.list
	Path string `json:"path"`
	// File permissions applied to the generated repository file.
	// @deck.example 0644
	Mode string `json:"mode"`
	// Replace an existing repository file at the target path.
	// @deck.example true
	ReplaceExisting bool `json:"replaceExisting"`
	// Disable all existing repository definitions before writing the new one.
	// @deck.example true
	DisableExisting bool `json:"disableExisting"`
	// Paths to back up before modifying.
	// @deck.example [/etc/apt/sources.list]
	BackupPaths []string `json:"backupPaths"`
	// Paths to remove before writing the new definition.
	// @deck.example [/etc/apt/sources.list.d/ubuntu.list]
	CleanupPaths []string `json:"cleanupPaths"`
	// Repository entries to write.
	// @deck.example [{baseurl:http://repo.local/debian,trusted:true}]
	Repositories []RepositoryEntry `json:"repositories"`
}

type Confirm struct {
	// Prompt shown to the local operator.
	// @deck.example Continue with kubeadm init?
	Message string `json:"message"`
	// Default answer used for empty input and required in non-interactive mode.
	// @deck.example false
	Default *bool `json:"default"`
	// Behavior when the operator answers no. Defaults to `fail`.
	// @deck.example continue
	OnNo string `json:"onNo"`
}

type ContainerdConfigSetting struct {
	// Edit operation.
	// @deck.example set
	Op string `json:"op"`
	// Optional logical containerd config key.
	// @deck.example runtime.runtimes.runc.options.SystemdCgroup
	Key string `json:"key"`
	// Optional direct TOML path for advanced use cases.
	// @deck.example plugins."io.containerd.grpc.v1.cri".registry.config_path
	RawPath string `json:"rawPath"`
	// Typed value for the edit.
	// @deck.example true
	Value any `json:"value,omitempty"`
}

type ContainerdRegistryHost struct {
	// Registry namespace whose `hosts.toml` file will be written.
	// @deck.example registry.k8s.io
	Registry string `json:"registry"`
	// Upstream registry server URL recorded in the generated `hosts.toml` file.
	// @deck.example https://registry.k8s.io
	Server string `json:"server"`
	// Mirror host URL that containerd should contact.
	// @deck.example http://registry.local:5000
	Host string `json:"host"`
	// Capabilities granted to the mirror host.
	// @deck.example [pull,resolve]
	Capabilities []string `json:"capabilities"`
	// Skip TLS verification for the mirror host.
	// @deck.example true
	SkipVerify bool `json:"skipVerify"`
}

type CopyFile struct {
	// Structured source descriptor for the file to copy.
	// @deck.example {path:/etc/kubernetes/admin.conf}
	Source FileSource `json:"source"`
	// Optional transport policy when the source must be fetched first.
	// @deck.example {offlineOnly:true}
	Fetch FileFetch `json:"fetch"`
	// Destination path on the node.
	// @deck.example /home/vagrant/.kube/config
	Path string `json:"path"`
	// File permissions in octal notation applied after the copy completes.
	// @deck.example 0644
	Mode string `json:"mode"`
}

type CreateSymlink struct {
	// Path where the symbolic link will be created.
	// @deck.example /usr/bin/runc
	Path string `json:"path"`
	// Path that the symbolic link points to.
	// @deck.example /usr/local/sbin/runc
	Target string `json:"target"`
	// Remove an existing file or link at `path` before creating the new link.
	// @deck.example true
	Force bool `json:"force"`
	// Create parent directories for `path` if needed.
	// @deck.example true
	CreateParent bool `json:"createParent"`
	// Fail if `target` does not exist when the link is created.
	// @deck.example true
	RequireTarget bool `json:"requireTarget"`
	// Treat a missing target as a no-op instead of an error.
	// @deck.example true
	IgnoreMissingTarget bool `json:"ignoreMissingTarget"`
}

type DownloadFile struct {
	// Optional list form for batching multiple download items in one step.
	// @deck.example [{source:{url:https://mirror.example.com/runc},outputPath:files/bin/runc,mode:0755}]
	Items []DownloadFileItem `json:"items,omitempty"`
	// Structured source descriptor for the download.
	// @deck.example {url:https://mirror.example.com/runc,sha256:abc123...}
	Source FileSource `json:"source"`
	// Optional transport policy for the download.
	// @deck.example {offlineOnly:true}
	Fetch FileFetch `json:"fetch"`
	// Bundle-relative output path for the downloaded artifact.
	// @deck.example files/bin/runc
	OutputPath string `json:"outputPath"`
	// File permissions in octal notation applied after the download completes.
	// @deck.example 0755
	Mode string `json:"mode"`
	// Optional per-transfer timeout for the download.
	// @deck.example 30s
	Timeout string `json:"timeout"`
}

type DownloadFileItem struct {
	// Source descriptor for this item.
	// @deck.example {url:https://mirror.example.com/runc}
	Source FileSource `json:"source"`
	// Optional transport policy for this item.
	// @deck.example {offlineOnly:true}
	Fetch FileFetch `json:"fetch"`
	// Bundle-relative output path for this item.
	// @deck.example files/bin/runc
	OutputPath string `json:"outputPath"`
	// File permissions applied after this item is written.
	// @deck.example 0755
	Mode string `json:"mode"`
}

type DownloadImage struct {
	// Fully qualified image references to download.
	// @deck.example [registry.k8s.io/pause:3.9]
	Images []string `json:"images"`
	// Optional target platforms in os/arch or os/arch/variant form.
	// @deck.example [linux/amd64,linux/arm64]
	Platforms []ImagePlatform `json:"platforms"`
	// Optional registry authentication entries used during download.
	// @deck.example [{registry:registry.example.com,basic:{username:robot,password:${REGISTRY_PASSWORD}}}]
	Auth []ImageAuth `json:"auth"`
	// Backend-specific download settings.
	// @deck.example {engine:go-containerregistry}
	Backend ImageBackend `json:"backend"`
	// Optional bundle-relative directory for per-image tar archives.
	// @deck.example images/control-plane
	OutputDir string `json:"outputDir"`
	// Optional total timeout for the download step.
	// @deck.example 10m
	Timeout string `json:"timeout"`
}

type DownloadPackage struct {
	// Package names to download.
	// @deck.example [kubelet,kubeadm,kubectl]
	Packages []string `json:"packages"`
	// Target container platform for package resolution in os/arch or os/arch/variant form.
	// @deck.example linux/amd64
	Platform PackagePlatform `json:"platform"`
	// Target distribution hint used to select resolver behavior.
	// @deck.example {family:rhel,release:rocky9}
	Distro DownloadPackageDistro `json:"distro"`
	// Repository settings applied before download.
	// @deck.example {type:rpm,modules:[{name:container-tools,stream:4.0}]}
	Repo DownloadPackageRepo `json:"repo"`
	// Required container-based download backend configuration.
	// @deck.example {mode:container,runtime:docker,image:rockylinux:9}
	Backend DownloadPackageBackend `json:"backend"`
	// Optional bundle-relative output directory for downloaded package artifacts.
	// @deck.example packages/kubernetes
	OutputDir string `json:"outputDir"`
	// Maximum total duration for package download operations.
	// @deck.example 30m
	Timeout string `json:"timeout"`
}

type DownloadPackageBackend struct {
	// Download backend mode.
	// @deck.example container
	Mode string `json:"mode"`
	// Preferred container runtime for the download helper container.
	// @deck.example docker
	Runtime string `json:"runtime"`
	// Container image used for package resolution in download mode.
	// @deck.example rockylinux:9
	Image string `json:"image"`
}

type DownloadPackageDistro struct {
	// Distribution family used to resolve package tooling.
	// @deck.example rhel
	Family string `json:"family"`
	// Distribution release used for resolver and repo layout selection.
	// @deck.example rocky9
	Release string `json:"release"`
}

type DownloadPackageRepo struct {
	// Repository output type for download repo mode.
	// @deck.example rpm
	Type string `json:"type"`
	// Generate repository metadata after collecting packages.
	// @deck.example true
	Generate bool `json:"generate"`
	// Subdirectory under the generated repo root where packages are written.
	// @deck.example pkgs
	PkgsDir string `json:"pkgsDir"`
	// RPM module streams to enable before resolving downloads.
	// @deck.example [{name:container-tools,stream:4.0}]
	Modules []DownloadPackageRepoModule `json:"modules"`
}

type DownloadPackageRepoModule struct {
	// RPM module name to enable.
	// @deck.example container-tools
	Name string `json:"name"`
	// Module stream version paired with the module name.
	// @deck.example 4.0
	Stream string `json:"stream"`
}

type EditFile struct {
	// File path to edit in place.
	// @deck.example /etc/containerd/config.toml
	Path string `json:"path"`
	// Create a `.bak` copy before overwriting the original file.
	// @deck.example true
	Backup *bool `json:"backup"`
	// Ordered match/replace rules applied sequentially.
	// @deck.example [{match:SystemdCgroup = false,replaceWith:SystemdCgroup = true}]
	Edits []EditFileRule `json:"edits"`
	// File permissions in octal notation applied after the edit completes.
	// @deck.example 0644
	Mode string `json:"mode"`
}

type EditFileRule struct {
	// Literal string or pattern to search for in the file.
	// @deck.example SystemdCgroup = false
	Match string `json:"match"`
	// Replacement string applied where `match` is found.
	// @deck.example SystemdCgroup = true
	ReplaceWith string `json:"replaceWith"`
	// Edit operation type. Defaults to `replace`.
	// @deck.example replace
	Op string `json:"op"`
}

type EditJSON struct {
	// JSON file path to edit in place.
	// @deck.example /etc/cni/net.d/10-custom.conflist
	Path string `json:"path"`
	// Create a new empty JSON object when the file does not exist.
	// @deck.example true
	CreateIfMissing *bool `json:"createIfMissing"`
	// Ordered list of structured edits applied sequentially.
	// @deck.example [{op:set,rawPath:plugins.0.type,value:bridge}]
	Edits []StructuredEdit `json:"edits"`
	// Optional file permissions to apply after the edit completes.
	// @deck.example 0644
	Mode string `json:"mode"`
}

type EditTOML struct {
	// TOML file path to edit in place.
	// @deck.example /etc/containerd/config.toml
	Path string `json:"path"`
	// Create a new empty TOML document when the file does not exist.
	// @deck.example true
	CreateIfMissing *bool `json:"createIfMissing"`
	// Ordered list of structured edits applied sequentially.
	// @deck.example [{op:set,rawPath:plugins."io.containerd.grpc.v1.cri".registry.config_path,value:/etc/containerd/certs.d}]
	Edits []StructuredEdit `json:"edits"`
	// Optional file permissions to apply after the edit completes.
	// @deck.example 0644
	Mode string `json:"mode"`
}

type EditYAML struct {
	// YAML file path to edit in place.
	// @deck.example /etc/kubernetes/kubeadm-config.yaml
	Path string `json:"path"`
	// Create a new empty YAML document when the file does not exist.
	// @deck.example true
	CreateIfMissing *bool `json:"createIfMissing"`
	// Ordered list of structured edits applied sequentially.
	// @deck.example [{op:set,rawPath:spec.template.spec.containers.0.image,value:registry.local/app:v1}]
	Edits []StructuredEdit `json:"edits"`
	// Optional file permissions to apply after the edit completes.
	// @deck.example 0644
	Mode string `json:"mode"`
}

type EnsureDirectory struct {
	// Directory path to create if it does not already exist.
	// @deck.example /var/lib/deck
	Path string `json:"path"`
	// Directory permissions in octal notation.
	// @deck.example 0755
	Mode string `json:"mode"`
}

type ExtractArchive struct {
	// Structured source descriptor for the archive to extract.
	// @deck.example {path:/tmp/cni-plugins.tgz}
	Source FileSource `json:"source"`
	// Optional transport policy when the archive must be fetched first.
	// @deck.example {offlineOnly:true}
	Fetch FileFetch `json:"fetch"`
	// Destination directory on the node.
	// @deck.example /opt/cni/bin
	Path string `json:"path"`
	// Optional archive members to extract.
	// @deck.example [bridge,loopback]
	Include []string `json:"include"`
	// File permissions in octal notation applied to extracted files when supported.
	// @deck.example 0755
	Mode string `json:"mode"`
}

type FileBundleRef struct {
	// Bundle root category to read from (`files`, `images`, or `packages`).
	// @deck.example files
	Root string `json:"root"`
	// Relative path within the selected bundle root.
	// @deck.example bin/linux/amd64/runc
	Path string `json:"path"`
}

type FileFetch struct {
	// Restrict fetches to offline-safe sources only.
	// @deck.example true
	OfflineOnly bool `json:"offlineOnly"`
	// Ordered list of source candidates tried for the fetch.
	// @deck.example [{type:url,url:https://mirror.example.com/runc}]
	Sources []FileFetchSource `json:"sources"`
}

type FileFetchSource struct {
	// Source selector type for multi-source fetches.
	// @deck.example url
	Type string `json:"type"`
	// Local path source used when `type` is `path`.
	// @deck.example /opt/cache/runc
	Path string `json:"path"`
	// Remote URL source used when `type` is `url`.
	// @deck.example https://mirror.example.com/runc
	URL string `json:"url"`
}

type FileSource struct {
	// URL to fetch the file from during prepare.
	// @deck.example https://mirror.example.com/runc
	URL string `json:"url"`
	// Local filesystem path used as the source.
	// @deck.example /opt/cache/runc
	Path string `json:"path"`
	// Expected SHA-256 checksum for the fetched or copied file.
	// @deck.example abc123...
	SHA256 string `json:"sha256"`
	// Reference to a file already present in the bundle.
	// @deck.example {root:files,path:bin/linux/amd64/runc}
	Bundle *FileBundleRef `json:"bundle"`
}

type ImageAuth struct {
	// Registry host matched against each image reference.
	// @deck.example registry.example.com
	Registry string `json:"registry"`
	// Explicit basic-auth credentials used for the matched registry.
	// @deck.example {username:robot,password:${REGISTRY_PASSWORD}}
	Basic ImageAuthBasic `json:"basic"`
}

type ImageAuthBasic struct {
	// Registry username used for basic authentication.
	// @deck.example robot
	Username string `json:"username"`
	// Registry password or access token paired with `username`.
	// @deck.example ${REGISTRY_PASSWORD}
	Password string `json:"password"`
}

type ImageBackend struct {
	// Image download engine implementation.
	// @deck.example go-containerregistry
	Engine string `json:"engine"`
}

type ImagePlatform string

type Input struct {
	// Prompt shown to the local operator.
	// @deck.example Node advertise address
	Message string `json:"message"`
	// Default value used for empty input and non-interactive mode.
	// @deck.example 192.0.2.10
	Default *string `json:"default"`
	// Require a non-empty value. Defaults to `true`.
	// @deck.example true
	Required *bool `json:"required"`
	// Treat the value as secret. Secret values require `register`, are available to later steps in memory, and are not persisted in state.
	// @deck.example false
	Secret bool `json:"secret"`
}

type InstallAptPackage struct {
	// Local repository source used for the installation.
	// @deck.example {type:local-repo,path:/opt/deck/repos/kubernetes}
	Source *InstallPackageSource `json:"source"`
	// Package names to install.
	// @deck.example [kubelet,kubeadm,kubectl]
	Packages []string `json:"packages"`
	// Limit apt visibility to these source list files.
	// @deck.example [/etc/apt/sources.list.d/offline.list]
	RestrictToRepos []string `json:"restrictToRepos"`
	// Apt source list files to exclude from package resolution.
	// @deck.example [/etc/apt/sources.list.d/updates.list]
	ExcludeRepos []string `json:"excludeRepos"`
	// Apt-specific installation options.
	// @deck.example {installRecommends:false,fixBroken:true}
	Apt InstallAptPackageOptions `json:"apt"`
	// Maximum total duration for package installation.
	// @deck.example 20m
	Timeout string `json:"timeout"`
}

type InstallAptPackageOptions struct {
	// Attempt to correct broken dependencies during apt installation.
	// @deck.example true
	FixBroken bool `json:"fixBroken"`
	// Install recommended packages. Omit to use the operating system default.
	// @deck.example false
	InstallRecommends *bool `json:"installRecommends"`
	// Additional dpkg force options passed through apt-get.
	// @deck.example [force-confdef,force-confold]
	DPKGOptions []string `json:"dpkgOptions"`
	// Default apt release used for package selection.
	// @deck.example jammy
	DefaultRelease string `json:"defaultRelease"`
	// Allow installing a lower package version than the installed version.
	// @deck.example true
	AllowDowngrade bool `json:"allowDowngrade"`
	// Fail if apt would remove packages as part of dependency resolution.
	// @deck.example true
	FailOnAutoremove bool `json:"failOnAutoremove"`
}

type InstallDnfPackage struct {
	// Local repository source used for the installation.
	// @deck.example {type:local-repo,path:/opt/deck/repos/kubernetes}
	Source *InstallPackageSource `json:"source"`
	// Package names to install.
	// @deck.example [kubelet,kubeadm,kubectl]
	Packages []string `json:"packages"`
	// Limit dnf visibility to these repository IDs.
	// @deck.example [offline-kubernetes]
	RestrictToRepos []string `json:"restrictToRepos"`
	// Dnf repository IDs to exclude from package resolution.
	// @deck.example [updates]
	ExcludeRepos []string `json:"excludeRepos"`
	// Dnf-specific installation options.
	// @deck.example {skipBroken:true,allowErasing:true}
	Dnf InstallDnfPackageOptions `json:"dnf"`
	// Maximum total duration for package installation.
	// @deck.example 20m
	Timeout string `json:"timeout"`
}

type InstallDnfPackageOptions struct {
	// Skip unavailable packages or packages with broken dependencies.
	// @deck.example true
	SkipBroken bool `json:"skipBroken"`
	// Allow erasing installed packages to resolve dependencies.
	// @deck.example true
	AllowErasing bool `json:"allowErasing"`
	// Install weak dependencies. Omit to use the distribution default.
	// @deck.example false
	InstallWeakDeps *bool `json:"installWeakDeps"`
	// Disable GPG signature checking for this transaction.
	// @deck.example true
	DisableGPGCheck bool `json:"disableGpgCheck"`
	// Prefer best available versions. Omit to use the distribution default.
	// @deck.example false
	Best *bool `json:"best"`
	// Use only cached metadata and packages.
	// @deck.example true
	CacheOnly bool `json:"cacheOnly"`
	// Package name patterns to exclude from the transaction.
	// @deck.example [kernel*]
	ExcludePackages []string `json:"excludePackages"`
}

type InstallPackage struct {
	// Package manager to use. `auto` resolves from the runtime OS family.
	// @deck.example auto
	Manager InstallPackageManager `json:"manager"`
	// Local repository source used for the installation.
	// @deck.example {type:local-repo,path:/opt/deck/repos/kubernetes}
	Source *InstallPackageSource `json:"source"`
	// Package names to install.
	// @deck.example [kubelet,kubeadm,kubectl]
	Packages []string `json:"packages"`
	// Limit package manager visibility to these repository selectors.
	// @deck.example [offline-kubernetes]
	RestrictToRepos []string `json:"restrictToRepos"`
	// Repository selectors to exclude from package resolution.
	// @deck.example [updates]
	ExcludeRepos []string `json:"excludeRepos"`
	// Apt-specific installation options. Requires `manager: apt` when set.
	// @deck.example {installRecommends:false,fixBroken:true}
	Apt InstallAptPackageOptions `json:"apt"`
	// Dnf-specific installation options. Requires `manager: dnf` when set.
	// @deck.example {skipBroken:true,allowErasing:true}
	Dnf InstallDnfPackageOptions `json:"dnf"`
	// Maximum total duration for package installation.
	// @deck.example 20m
	Timeout string `json:"timeout"`
}

type InstallPackageManager string

type InstallPackageSource struct {
	// Source type. Currently only `local-repo` is supported.
	// @deck.example local-repo
	Type string `json:"type"`
	// Filesystem path to the pre-prepared local package repository.
	// @deck.example /opt/deck/repos/kubernetes
	Path string `json:"path"`
}

type KernelModule struct {
	// Single module name to manage. Use `name` or `names`, not both.
	// @deck.example br_netfilter
	Name string `json:"name"`
	// Multiple module names managed in one step. Use `name` or `names`, not both.
	// @deck.example [overlay,br_netfilter]
	Names []string `json:"names"`
	// Run `modprobe` to load the module immediately.
	// @deck.example true
	Load *bool `json:"load"`
	// Persist the module under `/etc/modules-load.d/`.
	// @deck.example true
	Persist *bool `json:"persist"`
	// Path to the persistence file written when `persist` is true.
	// @deck.example /etc/modules-load.d/k8s.conf
	PersistFile string `json:"persistFile"`
	// Maximum total duration for module operations.
	// @deck.example 2m
	Timeout string `json:"timeout"`
}

type KubeadmInit struct {
	// Path where the generated join command is written after init.
	// @deck.example /tmp/deck/join.txt
	OutputJoinFile string `json:"outputJoinFile"`
	// Skip init if `/etc/kubernetes/admin.conf` already exists.
	// @deck.example true
	SkipIfAdminConfExists *bool `json:"skipIfAdminConfExists"`
	// CRI socket path passed to kubeadm.
	// @deck.example unix:///run/containerd/containerd.sock
	CriSocket string `json:"criSocket"`
	// Kubernetes version string passed to kubeadm.
	// @deck.example v1.30.1
	KubernetesVersion string `json:"kubernetesVersion"`
	// Path to an explicit kubeadm config file.
	// @deck.example /tmp/deck/kubeadm.conf
	ConfigFile string `json:"configFile"`
	// Inline kubeadm config template or `default`.
	// @deck.example default
	ConfigTemplate string `json:"configTemplate"`
	// CIDR range for the pod network.
	// @deck.example 10.244.0.0/16
	PodNetworkCIDR string `json:"podNetworkCIDR"`
	// API server advertise address or `auto`.
	// @deck.example auto
	AdvertiseAddress string `json:"advertiseAddress"`
	// Preflight checks to suppress.
	// @deck.example [swap]
	IgnorePreflightErrors []string `json:"ignorePreflightErrors"`
	// Additional flags passed directly to kubeadm.
	// @deck.example [--skip-phases=addon/kube-proxy]
	ExtraArgs []string `json:"extraArgs"`
	// Maximum total duration for the init step.
	// @deck.example 15m
	Timeout string `json:"timeout"`
}

type KubeadmJoin struct {
	// Path to the join command file produced by a prior init run.
	// @deck.example /tmp/deck/join.txt
	JoinFile string `json:"joinFile"`
	// Path to an explicit kubeadm join config file.
	// @deck.example /tmp/deck/kubeadm-join.yaml
	ConfigFile string `json:"configFile"`
	// Join as an additional control-plane member instead of a worker.
	// @deck.example false
	AsControlPlane bool `json:"asControlPlane"`
	// Additional flags passed directly to kubeadm join.
	// @deck.example [--skip-phases=preflight]
	ExtraArgs []string `json:"extraArgs"`
	// Maximum total duration for the join step.
	// @deck.example 15m
	Timeout string `json:"timeout"`
}

type KubeadmReset struct {
	// Pass `--force` to kubeadm reset.
	// @deck.example true
	Force bool `json:"force"`
	// Continue with cleanup even if kubeadm reset itself fails.
	// @deck.example true
	IgnoreErrors bool `json:"ignoreErrors"`
	// Stop kubelet before running reset.
	// @deck.example true
	StopKubelet *bool `json:"stopKubelet"`
	// CRI socket path passed to kubeadm.
	// @deck.example unix:///run/containerd/containerd.sock
	CriSocket string `json:"criSocket"`
	// Additional flags passed directly to kubeadm reset.
	// @deck.example [--skip-phases=preflight]
	ExtraArgs []string `json:"extraArgs"`
	// Directories to delete during cleanup.
	// @deck.example [/etc/cni/net.d,/var/lib/etcd]
	RemovePaths []string `json:"removePaths"`
	// Files to delete during cleanup.
	// @deck.example [/etc/kubernetes/admin.conf]
	RemoveFiles []string `json:"removeFiles"`
	// Containers to stop and remove during cleanup.
	// @deck.example [kube-apiserver,etcd]
	CleanupContainers []string `json:"cleanupContainers"`
	// Runtime service to restart after cleanup.
	// @deck.example containerd
	RestartRuntimeManageService string `json:"restartRuntimeService"`
	// Wait until the runtime service reports active.
	// @deck.example true
	WaitForRuntimeService bool `json:"waitForRuntimeService"`
	// Poll runtime readiness after cleanup.
	// @deck.example true
	WaitForRuntimeReady bool `json:"waitForRuntimeReady"`
	// Glob that must resolve to zero matches before the step succeeds.
	// @deck.example /etc/kubernetes/manifests/*.yaml
	WaitForMissingManifestsGlob string `json:"waitForMissingManifestsGlob"`
	// Stop kubelet again after runtime verification completes.
	// @deck.example true
	StopKubeletAfterReset bool `json:"stopKubeletAfterReset"`
	// Containers that must no longer exist after cleanup.
	// @deck.example [kube-apiserver,etcd]
	VerifyContainersAbsent []string `json:"verifyContainersAbsent"`
	// Optional reset report file written after cleanup.
	// @deck.example /tmp/deck/reports/reset-state.txt
	ReportFile string `json:"reportFile"`
	// Value written into the reset report as `resetReason`.
	// @deck.example node-reset-acceptance
	ReportResetReason string `json:"reportResetReason"`
	// Maximum total duration for the reset step.
	// @deck.example 15m
	Timeout string `json:"timeout"`
}

type KubeadmUpgrade struct {
	// Kubernetes version string passed to kubeadm upgrade.
	// @deck.example v1.31.0
	KubernetesVersion string `json:"kubernetesVersion"`
	// Preflight checks to suppress during upgrade.
	// @deck.example [Swap]
	IgnorePreflightErrors []string `json:"ignorePreflightErrors"`
	// Additional flags passed directly to kubeadm upgrade.
	// @deck.example [--allow-experimental-upgrades]
	ExtraArgs []string `json:"extraArgs"`
	// Restart kubelet after a successful upgrade.
	// @deck.example true
	RestartKubelet *bool `json:"restartKubelet"`
	// Service name restarted after a successful upgrade.
	// @deck.example kubelet
	KubeletService string `json:"kubeletService"`
	// Maximum total duration for the upgrade step.
	// @deck.example 30m
	Timeout string `json:"timeout"`
}

type LoadImage struct {
	// Image references to load from the prepared archives.
	// @deck.example [registry.k8s.io/kube-apiserver:v1.30.1]
	Images []string `json:"images"`
	// Optional target platforms matching DownloadImage archive suffixes.
	// @deck.example [linux/amd64]
	Platforms []ImagePlatform `json:"platforms"`
	// Directory containing prepared image archives.
	// @deck.example images/control-plane
	SourceDir string `json:"sourceDir"`
	// Runtime loader to use for imports.
	// @deck.example ctr
	Runtime string `json:"runtime"`
	// Optional runtime command override.
	// @deck.example [ctr,-n,k8s.io,images,import,{archive}]
	Command []string `json:"command"`
	// Optional total timeout for the load step.
	// @deck.example 10m
	Timeout string `json:"timeout"`
}

type ManageService struct {
	// Single service name to manage. Use `name` or `names`, not both.
	// @deck.example containerd
	Name string `json:"name"`
	// Multiple service names managed in one step. Use `name` or `names`, not both.
	// @deck.example [firewalld,ufw]
	Names []string `json:"names"`
	// Run `systemctl daemon-reload` before applying state changes.
	// @deck.example true
	DaemonReload bool `json:"daemonReload"`
	// Only manage the service if it exists on the host.
	// @deck.example true
	IfExists bool `json:"ifExists"`
	// Suppress errors when the service is not found.
	// @deck.example true
	IgnoreMissing bool `json:"ignoreMissing"`
	// Whether the service should be enabled on boot.
	// @deck.example true
	Enabled *bool `json:"enabled"`
	// Desired service state.
	// @deck.example started
	State string `json:"state"`
	// Maximum total duration for service operations.
	// @deck.example 5m
	Timeout string `json:"timeout"`
}

type Message struct {
	// Message text to print. Templates are rendered before the step runs and YAML block scalars support multi-line text.
	// @deck.example Node setup is starting.
	Message string `json:"message"`
	// Message severity used as a human-readable prefix for warnings and errors. Defaults to `info`.
	// @deck.example info
	Level string `json:"level"`
	// Output stream for the message. Defaults to `stdout`.
	// @deck.example stdout
	Stream string `json:"stream"`
}

type PackagePlatform string

type RefreshRepository struct {
	// Package manager to use.
	// @deck.example apt
	Manager string `json:"manager"`
	// Run a cache clean before updating metadata.
	// @deck.example true
	Clean bool `json:"clean"`
	// Fetch fresh package metadata from the configured repositories.
	// @deck.example true
	Update bool `json:"update"`
	// Limit the metadata update to these repository selectors.
	// @deck.example [/etc/apt/sources.list.d/offline.list]
	RestrictToRepos []string `json:"restrictToRepos"`
	// Repository selectors to skip during metadata update.
	// @deck.example [updates]
	ExcludeRepos []string `json:"excludeRepos"`
	// Maximum total duration for refresh operations.
	// @deck.example 5m
	Timeout string `json:"timeout"`
}

type RepositoryEntry struct {
	// RPM repository ID.
	// @deck.example offline-kubernetes
	ID string `json:"id"`
	// Human-readable repository name.
	// @deck.example Offline Kubernetes
	Name string `json:"name"`
	// Base URL for the repository.
	// @deck.example http://repo.local/debian
	BaseURL string `json:"baseurl"`
	// Explicit enabled state for the repository entry.
	// @deck.example true
	Enabled *bool `json:"enabled"`
	// Explicit gpgcheck state for RPM repositories.
	// @deck.example true
	GPGCheck *bool `json:"gpgcheck"`
	// URL or path to the repository GPG key.
	// @deck.example file:///etc/pki/rpm-gpg/RPM-GPG-KEY-offline
	GPGKey string `json:"gpgkey"`
	// Mark a deb repository as trusted.
	// @deck.example true
	Trusted *bool `json:"trusted"`
	// Deb repository suite.
	// @deck.example stable
	Suite string `json:"suite"`
	// Deb repository component.
	// @deck.example main
	Component string `json:"component"`
	// Deb repository type.
	// @deck.example deb
	Type string `json:"type"`
	// Additional rpm-style repository keys.
	// @deck.example {priority:10,module_hotfixes:true}
	Extra map[string]any `json:"extra"`
}

type StructuredEdit struct {
	// Structured edit operation.
	// @deck.example set
	Op string `json:"op"`
	// Path expression within the target document.
	// @deck.example plugins."io.containerd.grpc.v1.cri".registry.config_path
	RawPath string `json:"rawPath"`
	// Typed edit value.
	// @deck.example /etc/containerd/certs.d
	Value any `json:"value,omitempty"`
}

type Swap struct {
	// Disable all active swap devices with `swapoff -a`.
	// @deck.example true
	Disable *bool `json:"disable"`
	// Comment out swap entries in fstab so swap stays off after reboot.
	// @deck.example true
	Persist *bool `json:"persist"`
	// Path to the fstab file.
	// @deck.example /etc/fstab
	FstabPath string `json:"fstabPath"`
	// Maximum total duration for swap operations.
	// @deck.example 2m
	Timeout string `json:"timeout"`
}

type Sysctl struct {
	// Map of sysctl key-value pairs to write.
	// @deck.example {net.ipv4.ip_forward:1,net.bridge.bridge-nf-call-iptables:1}
	Values map[string]any `json:"values"`
	// Path to the sysctl file written with the given values.
	// @deck.example /etc/sysctl.d/99-k8s.conf
	WriteFile string `json:"writeFile"`
	// Run `sysctl -p <writeFile>` after writing.
	// @deck.example true
	Apply bool `json:"apply"`
	// Maximum total duration for sysctl operations.
	// @deck.example 2m
	Timeout string `json:"timeout"`
}

type VerifyImage struct {
	// Image references that must already exist in the runtime.
	// @deck.example [registry.k8s.io/kube-apiserver:v1.30.1]
	Images []string `json:"images"`
	// Optional image-listing command override.
	// @deck.example [ctr,-n,k8s.io,images,list,-q]
	Command []string `json:"command"`
	// Optional total timeout for the verification step.
	// @deck.example 5m
	Timeout string `json:"timeout"`
}

type Wait struct {
	// Duration between poll attempts.
	// @deck.example 2s
	Interval string `json:"interval"`
	// Deprecated alias for `interval`. Prefer `interval`.
	// @deck.example 2s
	PollInterval string `json:"pollInterval"`
	// Duration to wait before the first poll attempt.
	// @deck.example 1s
	InitialDelay string `json:"initialDelay"`
	// Filesystem path to check.
	// @deck.example /etc/kubernetes/admin.conf
	Path string `json:"path"`
	// List of paths that must all be absent before the step succeeds.
	// @deck.example [/etc/kubernetes/manifests/a.yaml,/etc/kubernetes/manifests/b.yaml]
	Paths []string `json:"paths"`
	// Glob pattern that must resolve to zero matches before the step succeeds.
	// @deck.example /etc/kubernetes/manifests/*.yaml
	Glob string `json:"glob"`
	// Filesystem entry type restriction for path checks.
	// @deck.example file
	Type string `json:"type"`
	// Require the matched file to have non-zero size.
	// @deck.example true
	NonEmpty bool `json:"nonEmpty"`
	// Service name to check.
	// @deck.example containerd
	Name string `json:"name"`
	// Command vector to run on each poll attempt.
	// @deck.example [test,-f,/etc/kubernetes/admin.conf]
	Command []string `json:"command"`
	// Host or IP address for TCP port checks.
	// @deck.example 127.0.0.1
	Address string `json:"address"`
	// TCP port number to check.
	// @deck.example 6443
	Port string `json:"port"`
	// Maximum total duration to wait before the step fails.
	// @deck.example 5m
	Timeout string `json:"timeout"`
}

type WriteContainerdConfig struct {
	// Destination path for the generated `config.toml`.
	// @deck.example /etc/containerd/config.toml
	Path string `json:"path"`
	// Generate a base config with `containerd config default` when the file does not exist.
	// @deck.example true
	CreateDefault *bool `json:"createDefault"`
	// How the step chooses or enforces the containerd config version.
	// @deck.example require-v3
	VersionPolicy string `json:"versionPolicy"`
	// Ordered containerd config edits.
	// @deck.example [{op:set,rawPath:plugins."io.containerd.grpc.v1.cri".registry.config_path,value:/etc/containerd/certs.d}]
	RawSettings []ContainerdConfigSetting `json:"rawSettings"`
	// Maximum total duration for config rendering and writes.
	// @deck.example 5m
	Timeout string `json:"timeout"`
}

type WriteContainerdRegistryHosts struct {
	// Directory where per-registry `hosts.toml` files are written.
	// @deck.example /etc/containerd/certs.d
	Path string `json:"path"`
	// Per-registry host entries written as `hosts.toml` files under `path`.
	// @deck.example [{registry:registry.k8s.io,host:http://mirror.local:5000}]
	RegistryHosts []ContainerdRegistryHost `json:"registryHosts"`
}

type WriteFile struct {
	// Destination path on the node.
	// @deck.example /etc/motd
	Path string `json:"path"`
	// Inline content written verbatim to `path`.
	// @deck.example hello
	Content string `json:"content"`
	// Inline multi-line content rendered with the current vars before writing.
	// @deck.example Hello {{ .vars.name }}
	Template string `json:"template"`
	// File permissions in octal notation applied after the write completes.
	// @deck.example 0644
	Mode string `json:"mode"`
}

type WriteSystemdUnit struct {
	// Destination path for the unit file on the node.
	// @deck.example /etc/systemd/system/kubelet.service
	Path string `json:"path"`
	// Inline unit file content written verbatim to `path`.
	// @deck.example
	// [Unit]
	// Description=kubelet
	Content string `json:"content"`
	// Inline multi-line unit content rendered with the current vars before writing.
	// @deck.example
	// [Service]
	// Environment=NODE_IP={{ .vars.nodeIP }}
	Template string `json:"template"`
	// File permissions applied to the unit file in octal notation.
	// @deck.example 0644
	Mode string `json:"mode"`
	// Run `systemctl daemon-reload` after writing the unit file.
	// @deck.example true
	DaemonReload bool `json:"daemonReload"`
	// Maximum total duration for the write and reload operations.
	// @deck.example 2m
	Timeout string `json:"timeout"`
}