snapshotter

type AgentConfig struct {
	// Kubeconfig path (optional override)
	Kubeconfig string

	// Namespace for agent deployment
	Namespace string

	// Image for agent container
	Image string

	// ImagePullSecrets for pulling the agent image from private registries
	ImagePullSecrets []string

	// JobName for the agent Job
	JobName string

	// ServiceAccountName selects the ServiceAccount the agent pod runs
	// as. It is EXACT-IF-EXISTS, so it carries two meanings resolved once
	// per deployment:
	//
	//   - A ServiceAccount of exactly this name already exists in
	//     Namespace: it is used verbatim, and the run creates NO
	//     ServiceAccount, Role, RoleBinding, ClusterRole or
	//     ClusterRoleBinding — and deletes none at cleanup. aicr adds and
	//     removes no permissions on an identity it did not create. This
	//     is how a ServiceAccount carrying IRSA
	//     (eks.amazonaws.com/role-arn) or GKE Workload Identity
	//     (iam.gke.io/gcp-service-account) annotations stays usable: both
	//     providers pin trust to the ServiceAccount NAME, which a
	//     run-scoped name can never satisfy. Generate its RBAC manifests
	//     with WriteAgentRoleManifests, then apply them out of band.
	//   - Otherwise: a name prefix. The run creates "<prefix>-<RunID>"
	//     and the full run-scoped RBAC set, and deletes them at cleanup.
	//
	// Empty falls back to NameBase and is never probed for existence, so
	// a stray ServiceAccount sitting at the default base cannot silently
	// capture the run.
	//
	// Using an existing ServiceAccount waives per-run permission
	// isolation: concurrent runs sharing it share its grants, and grants
	// provisioned for DiscoverNetwork persist beyond any one run.
	ServiceAccountName string

	// NodeSelector for targeting specific nodes
	NodeSelector map[string]string

	// Tolerations for scheduling on tainted nodes. Nil uses
	// DefaultTolerations; a non-nil empty slice explicitly disables that default.
	Tolerations []corev1.Toleration

	// Timeout for waiting for Job completion
	Timeout time.Duration

	// Cleanup determines whether to remove Job and RBAC on completion
	Cleanup bool

	// Output destination for snapshot
	Output string

	// Debug enables debug logging
	Debug bool

	// Privileged enables privileged mode (hostPID, hostNetwork, privileged container).
	// Required for GPU and SystemD collectors. When false, only K8s and OS collectors work.
	Privileged bool

	// RequireGPU requests nvidia.com/gpu resource for the agent pod.
	// Required in CDI environments (e.g., kind with nvkind) where GPU devices
	// are only injected when explicitly requested.
	RequireGPU bool

	// RuntimeClassName sets runtimeClassName on the agent pod and injects
	// NVIDIA_VISIBLE_DEVICES=all. Use instead of RequireGPU when all GPUs
	// are allocated — gives the agent nvidia-smi access without consuming
	// a GPU from the Device Plugin.
	RuntimeClassName string

	// TemplatePath is the path to a Go template file for custom output formatting.
	// When set, the snapshot output will be processed through this template.
	TemplatePath string

	// MaxNodesPerEntry limits node names per topology entry (0 = unlimited).
	MaxNodesPerEntry int

	// OS is the recipe OS criteria value (e.g., "ubuntu", "talos"). Drives
	// per-OS pod construction and in-pod collector backend selection. When
	// empty, defaults preserve the systemd-based behavior.
	OS string

	// ClusterConfigPath, when set, asks the in-pod network collector to
	// ingest a pre-existing l8k cluster-config.yaml at this path. In
	// Job-mode the path must resolve inside the agent pod (ConfigMap
	// mount, etc.) — this iteration plumbs the field through but does
	// not yet auto-mount the file; the typical use today is local mode
	// (AICR_AGENT_MODE=true) where the file lives on the caller's host.
	ClusterConfigPath string

	// AKSGPUPoolsPath, when set, points at an operator-supplied
	// `az aks nodepool list -o json` dump on the CALLER's filesystem.
	// The projection is pure file processing, so unlike ClusterConfigPath
	// it never enters the pod: the controller-side CLI projects it before
	// deploying (fail-loud on a bad file, before any cluster work) and
	// merges the aks-gpu-pools subtype into the snapshot the Job returns.
	AKSGPUPoolsPath string

	// OKEAddonsPath, when set, points at an operator-supplied
	// `oci ce cluster list-addons --cluster-id <cluster-ocid> --all --output json` dump on the
	// CALLER's filesystem. Same contract as AKSGPUPoolsPath: projected
	// controller-side before deploying, merged into the returned
	// snapshot as the oke-addons subtype.
	OKEAddonsPath string

	// DiscoverNetwork enables the in-pod network collector's live l8k
	// discovery path. Discovery is NOT read-only — it writes node labels
	// (nvidia.kubernetes-launch-kit.*) and patches NicClusterPolicy via
	// server-side-apply. RBAC must allow those writes.
	DiscoverNetwork bool

	// Requests overrides the agent container's per-resource requests.
	// When nil, the privileged/restricted defaults baked into
	// pkg/k8s/agent are used. Useful for right-sizing the agent on
	// resource-constrained dev clusters (e.g. talosctl Docker
	// provisioner workers).
	Requests corev1.ResourceList

	// Limits overrides the agent container's per-resource limits. When
	// nil, the privileged/restricted defaults are used. RequireGPU
	// defaults nvidia.com/gpu=1 only when the caller has not supplied
	// that key in Limits — e.g. --require-gpu --limits nvidia.com/gpu=4
	// keeps 4, not 1.
	Limits corev1.ResourceList

	// RunID scopes every resource this deployment creates (Job, RBAC, and
	// the internal staging ConfigMap when Output does not name one) to a
	// single run, so concurrent snapshot-agent runs never collide on a
	// shared resource name. DeployAndCollect generates one with
	// runid.Generate() when this is empty — callers normally leave it
	// unset; setting it explicitly is for correlating this run with an
	// external identifier (e.g. sharing one ID with a downstream
	// validator run).
	//
	// DeployAndCollect never writes the generated value back here: the
	// AgentConfig belongs to the caller, and a caller reusing one config
	// pointer across two runs would otherwise silently become a caller
	// pinning a duplicate RunID — the one state ADR-020 declares
	// unsupported, which fails the second run with ErrCodeInternal on the
	// first still-existing run-scoped object.
	RunID string

	// NameBase prefixes generated resource names (Job, ServiceAccount,
	// Role/RoleBinding). It applies per name: JobName falls back to it
	// when JobName is empty, and ServiceAccountName (which also names the
	// Role and RoleBinding) falls back to it when ServiceAccountName is
	// empty — so setting only one of the two leaves NameBase governing the
	// other. Forwarded verbatim to pkg/k8s/agent.Config.NameBase, which
	// defaults to "aicr" when also empty.
	NameBase string
}

type AgentRoleObject struct {
	// Kind is the Kubernetes kind ("Role", "RoleBinding", "ClusterRole",
	// "ClusterRoleBinding").
	Kind string

	// Name is the object's metadata.name.
	Name string

	// Path is the manifest's path, including the output directory.
	Path string
}

type AgentRolesConfig struct {
	// Namespace is the namespace of the ServiceAccount, and the namespace
	// the rendered Role and RoleBinding declare. Required.
	Namespace string

	// ServiceAccountName is the name of the ServiceAccount the rendered
	// bindings name as their subject. Required, and not verified to
	// exist — see WriteAgentRoleManifests.
	ServiceAccountName string

	// DiscoverNetwork also renders the cluster-scoped MUTATING rules that
	// `aicr snapshot --discover-network` needs, with a header enumerating
	// each one and the discovery step it exists for.
	DiscoverNetwork bool

	// RunID names the output directory (`snapshot-rbac-<RunID>`). Empty
	// generates one, which is the normal path; it is injectable so tests
	// and automation can pin a directory name.
	RunID string
}

type AgentRolesResult struct {
	// Dir is the output directory, relative to the working directory the
	// call was made from.
	Dir string

	// RunID is the run ID the directory name was built from.
	RunID string

	Namespace          string
	ServiceAccountName string

	// Objects lists what was written, in the order the files apply.
	Objects []AgentRoleObject

	// DiscoverNetwork echoes AgentRolesConfig.DiscoverNetwork: it is the
	// difference between a read-only grant and one carrying cluster-scoped
	// mutating rules, so anything reporting this result can say which was
	// written.
	DiscoverNetwork bool
}

type NodeSnapshotter struct {
	// Version is the snapshotter version.
	Version string

	// Factory is the collector factory to use. If nil, the default factory is used.
	Factory collector.Factory

	// Serializer is the serializer to use for output. If nil, a default stdout JSON serializer is used.
	Serializer serializer.Serializer

	// AgentConfig contains configuration for agent deployment mode. If nil or Enabled=false, runs locally.
	AgentConfig *AgentConfig

	// RequireGPU when true causes the snapshot to fail if no GPU is detected.
	RequireGPU bool

	// AKSGPUPoolsPath, when set, points at an operator-supplied
	// `az aks nodepool list -o json` dump. Local mode projects it into
	// the K8s measurement's aks-gpu-pools subtype up front (fail-loud —
	// explicit operator input never rides the collectSafe degrade-to-
	// warning policy). Agent Job mode carries the equivalent field on
	// AgentConfig and merges controller-side after retrieval.
	AKSGPUPoolsPath string

	// OKEAddonsPath, when set, points at an operator-supplied
	// `oci ce cluster list-addons --cluster-id <cluster-ocid> --all --output json` dump. Same
	// contract as AKSGPUPoolsPath: projected fail-loud into the K8s
	// measurement's oke-addons subtype before any collector runs.
	OKEAddonsPath string
}

type Snapshot struct {
	header.Header `json:",inline" yaml:",inline"`

	// Fingerprint is a structured cluster identity derived from the
	// raw measurements: detected service, accelerator, OS,
	// Kubernetes server version, region, and node count. Populated
	// after all collectors finish so it reflects the final
	// measurement set.
	//
	// The embedded Fingerprint is advisory: it is a convenience for
	// humans reading the snapshot file, not an authoritative claim.
	// Consumers of the snapshot that bear trust — notably the
	// ADR-007 bundler when building the predicate body and the
	// evidence verifier when re-checking it — MUST recompute the
	// Fingerprint from Measurements via fingerprint.FromMeasurements
	// rather than read this field. The snapshot YAML is not signed
	// at this layer; an attacker controlling the file could swap
	// the embedded Fingerprint without touching the measurements
	// that back it.
	Fingerprint *fingerprint.Fingerprint `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty"`

	// Measurements contains the collected measurements from various collectors.
	Measurements []*measurement.Measurement `json:"measurements" yaml:"measurements"`
}

type SnapshotDelivery struct {
	// Output is the destination: empty, "-", or the stdout URI for stdout;
	// a cm://namespace/name URI for a ConfigMap; any other value is a file
	// path.
	Output string

	// TemplatePath, when set, renders the snapshot through a Go template
	// instead of copying bytes. Takes precedence over the Output scheme —
	// Output then names the rendered report's destination.
	TemplatePath string

	// Kubeconfig is the path used to reach the cluster for a cm:// Output.
	// Empty means in-cluster or the standard discovery chain. Ignored for
	// every other destination.
	Kubeconfig string

	// Format is the rendering the caller asked for. The zero value and
	// serializer.FormatYAML both deliver the agent's bytes verbatim to
	// stdout and file destinations; JSON and table re-render the document
	// (see renderSnapshotFormat). A cm:// destination always re-serializes,
	// whatever the format — see the ConfigMap section on DeliverSnapshot.
	// Ignored when TemplatePath is set, since a template supplies its own
	// rendering.
	Format serializer.Format
}