cleanup memo

Author: CMGS

apis/v1/cocoonhibernation_types.go

@@ -5,23 +5,17 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// HibernationDesire is the requested target state for a pod's VM.
-//
 // +kubebuilder:validation:Enum=Hibernate;Wake
+
 type HibernationDesire string
 
 const (
-	// HibernationDesireHibernate asks vk-cocoon to snapshot the VM,
-	// destroy it, and keep the backing pod alive.
 	HibernationDesireHibernate HibernationDesire = "Hibernate"
-	// HibernationDesireWake asks vk-cocoon to restore the VM from a
-	// previously hibernated snapshot.
-	HibernationDesireWake HibernationDesire = "Wake"
+	HibernationDesireWake     HibernationDesire = "Wake"
 )
 
-// CocoonHibernationPhase is the high-level state reported in status.
-//
 // +kubebuilder:validation:Enum=Pending;Hibernating;Hibernated;Waking;Active;Failed
+
 type CocoonHibernationPhase string
 
 const (
@@ -33,32 +27,24 @@ const (
 	CocoonHibernationPhaseFailed      CocoonHibernationPhase = "Failed"
 )
 
-// CocoonHibernationSpec is the desired state of a CocoonHibernation.
 type CocoonHibernationSpec struct {
-	// PodRef points at the pod whose VM should be hibernated or woken.
 	// +kubebuilder:validation:Required
 	PodRef corev1.LocalObjectReference `json:"podRef"`
 
-	// Desire is the target state.
 	// +kubebuilder:validation:Required
 	Desire HibernationDesire `json:"desire"`
 }
 
-// CocoonHibernationStatus is the observed state of a CocoonHibernation.
 type CocoonHibernationStatus struct {
-	// ObservedGeneration is the .metadata.generation the controller last reconciled.
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
-	// Phase reflects the lifecycle state.
 	// +optional
 	Phase CocoonHibernationPhase `json:"phase,omitempty"`
 
-	// VMName is the deterministic VM name resolved from the pod annotations.
 	// +optional
 	VMName string `json:"vmName,omitempty"`
 
-	// Conditions follow the standard Kubernetes condition pattern.
 	// +optional
 	// +patchMergeKey=type
 	// +patchStrategy=merge
@@ -75,7 +61,6 @@ type CocoonHibernationStatus struct {
 // +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 
-// CocoonHibernation is the Schema for the cocoonhibernations API.
 type CocoonHibernation struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -86,7 +71,6 @@ type CocoonHibernation struct {
 
 // +kubebuilder:object:root=true
 
-// CocoonHibernationList is a list of CocoonHibernation.
 type CocoonHibernationList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

apis/v1/cocoonset_types.go

@@ -6,149 +6,114 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// CocoonSetSpec is the desired state of a CocoonSet.
 type CocoonSetSpec struct {
-	// Suspend, when true, hibernates every managed pod.
 	// +optional
 	Suspend bool `json:"suspend,omitempty"`
 
-	// SnapshotPolicy controls when vk-cocoon snapshots VMs before destroying them.
 	// +optional
 	// +kubebuilder:default=always
 	SnapshotPolicy SnapshotPolicy `json:"snapshotPolicy,omitempty"`
 
-	// NodePool selects the cocoon node pool that should host this CocoonSet.
-	// vk-cocoon nodes are labeled with cocoonstack.io/pool=<name>.
 	// +optional
 	// +kubebuilder:default=default
 	NodePool string `json:"nodePool,omitempty"`
 
-	// Agent describes the main agent VM and any sub-agent replicas.
 	// +kubebuilder:validation:Required
 	Agent AgentSpec `json:"agent"`
 
-	// Toolboxes are companion VMs scheduled alongside the agents.
 	// +optional
 	Toolboxes []ToolboxSpec `json:"toolboxes,omitempty"`
 }
 
-// AgentSpec describes a CocoonSet's main agent and sub-agent replicas.
 type AgentSpec struct {
-	// Replicas is the number of sub-agents to fork from the main agent.
-	// The main agent is always created in addition to Replicas.
+	// Replicas is the number of sub-agents; the main agent is always created in addition.
 	// +optional
 	// +kubebuilder:default=0
 	// +kubebuilder:validation:Minimum=0
 	Replicas int32 `json:"replicas,omitempty"`
 
-	// Image is the epoch reference or boot image URL.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
 	Image string `json:"image"`
 
-	// Mode controls how the VM is brought up.
 	// +optional
 	// +kubebuilder:default=clone
 	Mode AgentMode `json:"mode,omitempty"`
 
-	// OS is the guest operating system.
 	// +optional
 	// +kubebuilder:default=linux
 	OS OSType `json:"os,omitempty"`
 
-	// Network is the CNI conflist name to use; empty means cocoon default.
 	// +optional
 	Network string `json:"network,omitempty"`
 
-	// Storage is the COW disk size to allocate for each VM.
 	// +optional
 	Storage *resource.Quantity `json:"storage,omitempty"`
 
-	// Resources passes through CPU/memory hints to the underlying pod.
 	// +optional
 	Resources corev1.ResourceRequirements `json:"resources,omitempty"`
 
-	// EnvFrom is forwarded to the agent container's envFrom field.
 	// +optional
 	EnvFrom []corev1.EnvFromSource `json:"envFrom,omitempty"`
 
-	// ServiceAccountName overrides the agent pod's serviceAccountName.
 	// +optional
 	ServiceAccountName string `json:"serviceAccountName,omitempty"`
 }
 
-// ToolboxSpec describes a companion toolbox VM scheduled alongside agents.
 type ToolboxSpec struct {
-	// Name is unique within the CocoonSet and must follow RFC 1123 label rules.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
 	Name string `json:"name"`
 
-	// OS is the guest operating system.
 	// +optional
 	// +kubebuilder:default=linux
 	OS OSType `json:"os,omitempty"`
 
-	// Image is the epoch reference or boot image URL. Required for non-static modes.
 	// +optional
 	Image string `json:"image,omitempty"`
 
-	// Mode controls how the toolbox VM is brought up.
 	// +optional
 	// +kubebuilder:default=run
 	Mode ToolboxMode `json:"mode,omitempty"`
 
-	// Storage is the COW disk size to allocate.
 	// +optional
 	Storage *resource.Quantity `json:"storage,omitempty"`
 
-	// StaticIP is the pre-assigned IP for static-mode toolboxes.
 	// +optional
 	StaticIP string `json:"staticIP,omitempty"`
 
-	// StaticVMID is the pre-assigned VM identifier for static-mode toolboxes.
 	// +optional
 	StaticVMID string `json:"staticVMID,omitempty"`
 
-	// VNCPort is the VNC port for graphical access (Windows, Android).
 	// +optional
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=65535
 	VNCPort int32 `json:"vncPort,omitempty"`
 
-	// Resources passes through CPU/memory hints to the underlying pod.
 	// +optional
 	Resources corev1.ResourceRequirements `json:"resources,omitempty"`
 }
 
-// CocoonSetStatus is the observed state of a CocoonSet.
 type CocoonSetStatus struct {
-	// ObservedGeneration is the .metadata.generation the controller last reconciled.
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
-	// Phase is the high-level lifecycle phase.
 	// +optional
 	Phase CocoonSetPhase `json:"phase,omitempty"`
 
-	// ReadyAgents is the count of agent pods in the Running phase.
 	// +optional
 	ReadyAgents int32 `json:"readyAgents"`
 
-	// DesiredAgents is the total number of agents requested by spec (1 + Replicas).
 	// +optional
 	DesiredAgents int32 `json:"desiredAgents"`
 
-	// Agents reports per-agent runtime state.
 	// +optional
 	Agents []AgentStatus `json:"agents,omitempty"`
 
-	// Toolboxes reports per-toolbox runtime state.
 	// +optional
 	Toolboxes []ToolboxStatus `json:"toolboxes,omitempty"`
 
-	// Conditions follow the standard Kubernetes condition pattern.
 	// +optional
 	// +patchMergeKey=type
 	// +patchStrategy=merge
@@ -157,9 +122,6 @@ type CocoonSetStatus struct {
 	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`
 }
 
-// AgentStatus is the per-agent runtime state. Slot 0 is always the
-// main agent; ForkedFrom is set only for sub-agents and points at
-// the main VM they cloned from.
 type AgentStatus struct {
 	Slot       int32  `json:"slot"`
 	Role       string `json:"role"`
@@ -171,9 +133,6 @@ type AgentStatus struct {
 	ForkedFrom string `json:"forkedFrom,omitempty"`
 }
 
-// ToolboxStatus is the per-toolbox runtime state. ConnType is the
-// preferred kubectl-style connection protocol picked by
-// meta.ConnectionType (ssh / rdp / adb / vnc).
 type ToolboxStatus struct {
 	Name     string `json:"name"`
 	PodName  string `json:"podName,omitempty"`
@@ -193,7 +152,6 @@ type ToolboxStatus struct {
 // +kubebuilder:printcolumn:name="Desired",type=integer,JSONPath=`.status.desiredAgents`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 
-// CocoonSet is the Schema for the cocoonsets API.
 type CocoonSet struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -204,7 +162,6 @@ type CocoonSet struct {
 
 // +kubebuilder:object:root=true
 
-// CocoonSetList is a list of CocoonSet.
 type CocoonSetList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata,omitempty"`

apis/v1/enums.go

@@ -1,62 +1,46 @@
 package v1
 
-// AgentMode controls how an agent VM is brought up.
-//
 // +kubebuilder:validation:Enum=clone;run
+
 type AgentMode string
 
 const (
-	// AgentModeClone forks the VM from a snapshot in epoch.
 	AgentModeClone AgentMode = "clone"
-	// AgentModeRun boots the VM cold from a cloud image.
-	AgentModeRun AgentMode = "run"
+	AgentModeRun   AgentMode = "run"
 )
 
-// IsValid reports whether m is one of the recognized AgentMode values.
 func (m AgentMode) IsValid() bool {
 	return m == AgentModeClone || m == AgentModeRun
 }
 
-// Default returns m when set, otherwise the canonical default
-// (AgentModeClone). Centralizing the fallback here keeps the
-// webhook, operator and vk-cocoon in lock-step.
+// Default returns m when set, otherwise AgentModeClone.
 func (m AgentMode) Default() AgentMode {
 	if m == "" {
 		return AgentModeClone
 	}
 	return m
 }
 
-// ToolboxMode controls how a toolbox VM is brought up.
-//
 // +kubebuilder:validation:Enum=run;clone;static
 type ToolboxMode string
 
 const (
-	// ToolboxModeRun boots the toolbox VM cold from a cloud image.
-	ToolboxModeRun ToolboxMode = "run"
-	// ToolboxModeClone forks the toolbox VM from a snapshot in epoch.
-	ToolboxModeClone ToolboxMode = "clone"
-	// ToolboxModeStatic attaches to an externally managed VM and never
-	// creates or destroys it; requires StaticIP and StaticVMID.
+	ToolboxModeRun    ToolboxMode = "run"
+	ToolboxModeClone  ToolboxMode = "clone"
 	ToolboxModeStatic ToolboxMode = "static"
 )
 
-// IsValid reports whether m is one of the recognized ToolboxMode values.
 func (m ToolboxMode) IsValid() bool {
 	return m == ToolboxModeRun || m == ToolboxModeClone || m == ToolboxModeStatic
 }
 
-// Default returns m when set, otherwise ToolboxModeRun.
 func (m ToolboxMode) Default() ToolboxMode {
 	if m == "" {
 		return ToolboxModeRun
 	}
 	return m
 }
 
-// OSType is the guest operating system family.
-//
 // +kubebuilder:validation:Enum=linux;windows;android
 type OSType string
 
@@ -66,48 +50,37 @@ const (
 	OSAndroid OSType = "android"
 )
 
-// IsValid reports whether o is one of the recognized OSType values.
 func (o OSType) IsValid() bool {
 	return o == OSLinux || o == OSWindows || o == OSAndroid
 }
 
-// Default returns o when set, otherwise OSLinux.
 func (o OSType) Default() OSType {
 	if o == "" {
 		return OSLinux
 	}
 	return o
 }
 
-// SnapshotPolicy controls when vk-cocoon takes snapshots.
-//
 // +kubebuilder:validation:Enum=always;main-only;never
 type SnapshotPolicy string
 
 const (
-	// SnapshotPolicyAlways snapshots every agent before destroy.
-	SnapshotPolicyAlways SnapshotPolicy = "always"
-	// SnapshotPolicyMainOnly snapshots only the main agent (slot 0).
+	SnapshotPolicyAlways   SnapshotPolicy = "always"
 	SnapshotPolicyMainOnly SnapshotPolicy = "main-only"
-	// SnapshotPolicyNever skips snapshots entirely.
-	SnapshotPolicyNever SnapshotPolicy = "never"
+	SnapshotPolicyNever    SnapshotPolicy = "never"
 )
 
-// IsValid reports whether p is one of the recognized SnapshotPolicy values.
 func (p SnapshotPolicy) IsValid() bool {
 	return p == SnapshotPolicyAlways || p == SnapshotPolicyMainOnly || p == SnapshotPolicyNever
 }
 
-// Default returns p when set, otherwise SnapshotPolicyAlways.
 func (p SnapshotPolicy) Default() SnapshotPolicy {
 	if p == "" {
 		return SnapshotPolicyAlways
 	}
 	return p
 }
 
-// CocoonSetPhase is the high-level lifecycle phase reported in status.
-//
 // +kubebuilder:validation:Enum=Pending;Running;Scaling;Suspended;Failed
 type CocoonSetPhase string
 

apis/v1/groupversion_info.go

@@ -5,12 +5,8 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/scheme"
 )
 
-// GroupVersion is the API Group Version used to register the objects.
 var GroupVersion = schema.GroupVersion{Group: "cocoonset.cocoonstack.io", Version: "v1"}
 
-// SchemeBuilder collects type registrations for this group; consumers
-// call AddToScheme to install them on a runtime.Scheme.
 var SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
 
-// AddToScheme adds the types in this group-version to the given scheme.
 var AddToScheme = SchemeBuilder.AddToScheme