meta

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: May 13, 2026 License: MIT Imports: 7 Imported by: 1

Documentation

Overview

Package meta defines shared metadata keys and naming rules used across Cocoon components.

Index

Constants

View Source
const (
	// APIVersion is the apiVersion string for CocoonSet resources.
	APIVersion = "cocoonset.cocoonstack.io/v1"
	// KindCocoonSet is the kind string for CocoonSet resources.
	KindCocoonSet = "CocoonSet"

	// TolerationKey is the virtual-kubelet provider key used to gate cocoon pods onto vk-cocoon nodes.
	TolerationKey = "virtual-kubelet.io/provider"

	// LabelCocoonSet stamps a pod with its owning CocoonSet name.
	LabelCocoonSet = "cocoonset.cocoonstack.io/name"
	// LabelRole stamps a pod with its role (main / sub-agent / toolbox).
	LabelRole = "cocoonset.cocoonstack.io/role"
	// LabelSlot stamps a pod with its zero-based agent slot index.
	LabelSlot = "cocoonset.cocoonstack.io/slot"

	// LabelNodePool selects which cocoon node pool a pod should land on.
	LabelNodePool = "cocoonstack.io/pool"
	// DefaultNodePool is the pool name used when LabelNodePool is unset.
	DefaultNodePool = "default"

	// AnnotationMode declares the VM provisioning mode (clone / run / static).
	AnnotationMode = "cocoonset.cocoonstack.io/mode"
	// AnnotationImage carries the VM image reference.
	AnnotationImage = "cocoonset.cocoonstack.io/image"
	// AnnotationStorage carries the VM root volume size (resource.Quantity).
	AnnotationStorage = "cocoonset.cocoonstack.io/storage"
	// AnnotationManaged marks a VM as cocoon-managed ("true") versus user-managed/static.
	AnnotationManaged = "cocoonset.cocoonstack.io/managed"
	// AnnotationOS carries the guest OS family (linux / windows / android).
	AnnotationOS = "cocoonset.cocoonstack.io/os"
	// AnnotationSnapshotPolicy carries the per-pod snapshot policy.
	AnnotationSnapshotPolicy = "cocoonset.cocoonstack.io/snapshot-policy"
	// AnnotationNetwork carries the cluster network to attach the VM to.
	AnnotationNetwork = "cocoonset.cocoonstack.io/network"
	// AnnotationForcePull bypasses the image cache when set to "true".
	AnnotationForcePull = "cocoonset.cocoonstack.io/force-pull"
	// AnnotationCocoonSetGeneration carries the CocoonSet generation stamped at scheduling time.
	AnnotationCocoonSetGeneration = "cocoonset.cocoonstack.io/generation"

	// AnnotationVMID carries the runtime VM identifier vk-cocoon assigns after creation.
	AnnotationVMID = "vm.cocoonstack.io/id"
	// AnnotationVMName carries the deterministic VM name the operator builds from namespace/deployment/slot.
	AnnotationVMName = "vm.cocoonstack.io/name"
	// AnnotationIP carries the VM's primary IPv4 address.
	AnnotationIP = "vm.cocoonstack.io/ip"
	// AnnotationVNCPort carries the VM's VNC port when one is exposed.
	AnnotationVNCPort = "vm.cocoonstack.io/vnc-port"
	// AnnotationHibernate signals "hibernate this VM" when set to "true".
	AnnotationHibernate = "vm.cocoonstack.io/hibernate"
	// AnnotationForkFrom names a VM to fork the new VM from.
	AnnotationForkFrom = "vm.cocoonstack.io/fork-from"
	// AnnotationCloneFromDir names a host directory to clone the VM image from (vk-cocoon-specific).
	AnnotationCloneFromDir = "vm.cocoonstack.io/clone-from-dir"
	// AnnotationConnType overrides the connection protocol inferred from OS/runtime.
	AnnotationConnType = "vm.cocoonstack.io/conn-type"
	// AnnotationBackend selects the hypervisor backend (cloud-hypervisor / firecracker).
	AnnotationBackend = "vm.cocoonstack.io/backend"
	// AnnotationNoDirectIO disables O_DIRECT on writable disks when set to "true" (cloud-hypervisor only).
	AnnotationNoDirectIO = "vm.cocoonstack.io/no-direct-io"
	// AnnotationProbePort overrides the default ICMP readiness probe with a TCP port check.
	AnnotationProbePort = "vm.cocoonstack.io/probe-port"
	// AnnotationLifecycleState carries the vk-cocoon-reported lifecycle state.
	AnnotationLifecycleState = "vm.cocoonstack.io/lifecycle-state"
	// AnnotationLifecycleObservedGeneration carries the CocoonSet generation observed by vk-cocoon.
	AnnotationLifecycleObservedGeneration = "vm.cocoonstack.io/lifecycle-observed-generation"
	// AnnotationLifecycleStateMessage carries an optional message accompanying the lifecycle state.
	AnnotationLifecycleStateMessage = "vm.cocoonstack.io/lifecycle-state-message"

	// RoleMain identifies the main agent VM (slot 0).
	RoleMain = "main"
	// RoleSubAgent identifies a sub-agent VM (slot > 0).
	RoleSubAgent = "sub-agent"
	// RoleToolbox identifies a toolbox VM.
	RoleToolbox = "toolbox"

	// HibernateSnapshotTag names the snapshot tag used for hibernation.
	HibernateSnapshotTag = "hibernate"
	// DefaultSnapshotTag names the default snapshot tag.
	DefaultSnapshotTag = "latest"
)

Variables

This section is empty.

Functions

func AgentVMNamePrefix added in v0.2.1

func AgentVMNamePrefix(namespace, cocoonSet string) string

AgentVMNamePrefix returns "vk-NAMESPACE-COCOONSET-", the prefix every agent VM name shares.

func ConnectionType

func ConnectionType(osType string, hasVNCPort bool, override string) string

ConnectionType returns the connection protocol. A non-empty override wins over OS-based inference (e.g. Linux + xrdp → rdp).

func ExtractAgentSlot added in v0.2.1

func ExtractAgentSlot(namespace, cocoonSet, vmName string) int

ExtractAgentSlot parses the trailing slot index from vmName when it matches the agent naming convention for (namespace, cocoonSet), or -1 for any toolbox VM name (e.g. "vk-NS-CS-db-2").

func ExtractSlotFromVMName deprecated

func ExtractSlotFromVMName(vmName string) int

ExtractSlotFromVMName parses the trailing slot index from a VM name, or -1 if absent.

Deprecated: misclassifies toolbox names with numeric suffixes (e.g. "vk-NS-CS-db-2" → slot 2). Prefer ExtractAgentSlot.

func HasCocoonTolerationKey added in v0.2.1

func HasCocoonTolerationKey(tolerations []corev1.Toleration) bool

HasCocoonTolerationKey reports whether tolerations include an entry whose Key matches TolerationKey. Operator/Value/Effect are ignored — the cocoon-webhook gate is intentionally permissive.

func InferRoleFromAgentSlot added in v0.2.1

func InferRoleFromAgentSlot(slot int) string

InferRoleFromAgentSlot returns RoleMain for slot 0, RoleSubAgent for positive slots, RoleToolbox for slot < 0.

func InferRoleFromVMName deprecated

func InferRoleFromVMName(vmName string) string

InferRoleFromVMName returns RoleMain for slot 0, RoleSubAgent otherwise.

Deprecated: shares the toolbox-collision bug of ExtractSlotFromVMName. Prefer InferRoleFromAgentSlot(ExtractAgentSlot(ns, cs, vmName)).

func IsContainerRunning added in v0.1.4

func IsContainerRunning(pod *corev1.Pod) bool

IsContainerRunning reports whether any container in pod is in a Running state.

func IsOwnedByCocoonSet added in v0.1.3

func IsOwnedByCocoonSet(ownerRefs []metav1.OwnerReference) bool

IsOwnedByCocoonSet reports whether any owner reference is a CocoonSet.

func IsPodReady added in v0.1.4

func IsPodReady(pod *corev1.Pod) bool

IsPodReady reports whether pod has a PodReady=True condition.

func IsPodTerminal added in v0.1.4

func IsPodTerminal(pod *corev1.Pod) bool

IsPodTerminal reports whether pod is in PodFailed phase.

func IsWindowsPod added in v0.1.4

func IsWindowsPod(pod *corev1.Pod) bool

IsWindowsPod reports whether the pod's OS annotation is "windows".

func MainAgentVMNameFor added in v0.2.1

func MainAgentVMNameFor(namespace, cocoonSet string) string

MainAgentVMNameFor returns the VM name of the main (slot 0) agent for (namespace, cocoonSet).

func OwnerDeploymentName added in v0.1.2

func OwnerDeploymentName(ownerRefs []metav1.OwnerReference) (string, bool)

OwnerDeploymentName extracts the deployment name from a ReplicaSet owner reference. Returns ok=false when absent or unparseable.

func PodKey added in v0.1.4

func PodKey(namespace, name string) string

PodKey returns a namespace/name string for use as a map key.

func PodNodePool added in v0.1.4

func PodNodePool(pod *corev1.Pod) string

PodNodePool returns the cocoon pool from nodeSelector, labels, annotations, or DefaultNodePool.

func QuantityString added in v0.1.7

func QuantityString(q *resource.Quantity) string

QuantityString returns q.String() or "" when q is nil.

func ReadCocoonSetGeneration added in v0.2.1

func ReadCocoonSetGeneration(pod *corev1.Pod) int64

ReadCocoonSetGeneration reads the CocoonSet generation stamped on the pod by cocoon-operator.

func ReadLifecycleObservedGeneration added in v0.2.1

func ReadLifecycleObservedGeneration(pod *corev1.Pod) int64

ReadLifecycleObservedGeneration reads the observed-generation annotation; missing or unparseable returns 0.

func ShouldSnapshotVM added in v0.1.4

func ShouldSnapshotVM(spec VMSpec) bool

ShouldSnapshotVM reports whether the VM should be snapshotted based on its SnapshotPolicy.

func StampCocoonSetGeneration added in v0.2.1

func StampCocoonSetGeneration(pod *corev1.Pod, generation int64)

StampCocoonSetGeneration writes the CocoonSet generation onto the pod.

func VMNameForDeployment

func VMNameForDeployment(namespace, deployment string, slot int) string

VMNameForDeployment builds a deterministic VM name from a deployment and slot index.

func VMNameForPod

func VMNameForPod(namespace, podName string) string

VMNameForPod builds a deterministic VM name from a pod name.

Types

type HibernateState added in v0.1.3

type HibernateState bool

HibernateState is the typed contract for the hibernate annotation.

func ReadHibernateState added in v0.1.3

func ReadHibernateState(pod *corev1.Pod) HibernateState

ReadHibernateState reads the hibernate annotation from a pod.

func (HibernateState) Apply added in v0.1.3

func (s HibernateState) Apply(pod *corev1.Pod)

Apply writes HibernateState into pod annotations. False removes the annotation entirely.

type LifecycleState added in v0.2.1

type LifecycleState string

LifecycleState is the typed contract for the lifecycle-state annotation vk-cocoon publishes on a Pod.

const (
	LifecycleStateCreating    LifecycleState = "creating"
	LifecycleStateReady       LifecycleState = "ready"
	LifecycleStateHibernating LifecycleState = "hibernating"
	LifecycleStateHibernated  LifecycleState = "hibernated"
	LifecycleStateFailed      LifecycleState = "failed"
)

func ReadLifecycleState added in v0.2.1

func ReadLifecycleState(pod *corev1.Pod) LifecycleState

ReadLifecycleState reads the lifecycle-state annotation, "" when missing.

func (LifecycleState) IsTerminal added in v0.2.1

func (s LifecycleState) IsTerminal() bool

IsTerminal reports whether s is a state a client would wait for.

type LifecycleStatus added in v0.2.1

type LifecycleStatus struct {
	State              LifecycleState
	ObservedGeneration int64
	Message            string
}

LifecycleStatus is the full triple (state, observed-generation, message).

func ReadLifecycleStatus added in v0.2.1

func ReadLifecycleStatus(pod *corev1.Pod) LifecycleStatus

ReadLifecycleStatus reads the triple from pod annotations.

func (LifecycleStatus) Annotations added in v0.2.1

func (s LifecycleStatus) Annotations() map[string]any

Annotations returns the lifecycle annotation map for a merge patch. Nil values signal "delete this key".

func (LifecycleStatus) Apply added in v0.2.1

func (s LifecycleStatus) Apply(pod *corev1.Pod)

Apply writes the status onto pod annotations. Empty message clears the annotation so a stale failure reason cannot tail into the next lifecycle.

func (LifecycleStatus) Snapshot added in v0.2.1

func (s LifecycleStatus) Snapshot() string

Snapshot returns a stable comparison key. NUL separator avoids collisions with arbitrary message contents.

type VMRuntime added in v0.1.3

type VMRuntime struct {
	VMID    string
	IP      string
	VNCPort int32
}

VMRuntime is the typed annotation contract vk-cocoon writes back after VM creation.

func ParseVMRuntime added in v0.1.3

func ParseVMRuntime(pod *corev1.Pod) VMRuntime

ParseVMRuntime extracts a VMRuntime from pod annotations. Nil pods are tolerated.

func (VMRuntime) Apply added in v0.1.3

func (r VMRuntime) Apply(pod *corev1.Pod)

Apply writes VMRuntime into pod annotations. Zero VNCPort is not emitted.

type VMSpec added in v0.1.3

type VMSpec struct {
	VMName         string
	Image          string
	Mode           string
	OS             string
	Storage        string
	Network        string
	SnapshotPolicy string
	ForkFrom       string
	Managed        bool
	ForcePull      bool
	NoDirectIO     bool
	ConnType       string
	Backend        string
	ProbePort      string
}

VMSpec is the typed annotation contract the operator writes for vk-cocoon to consume.

func FromAgentSpec added in v0.1.7

func FromAgentSpec(spec cocoonv1.AgentSpec, vmName string, snapshotPolicy cocoonv1.SnapshotPolicy, forkFrom string) VMSpec

FromAgentSpec builds a VMSpec from an AgentSpec. Agent VMs are always managed.

func FromToolboxSpec added in v0.1.7

func FromToolboxSpec(spec cocoonv1.ToolboxSpec, vmName string, snapshotPolicy cocoonv1.SnapshotPolicy) VMSpec

FromToolboxSpec builds a VMSpec from a ToolboxSpec. Static-mode toolboxes are unmanaged.

func ParseVMSpec added in v0.1.3

func ParseVMSpec(pod *corev1.Pod) VMSpec

ParseVMSpec extracts a VMSpec from pod annotations. Nil pods are tolerated.

func (VMSpec) Apply added in v0.1.3

func (s VMSpec) Apply(pod *corev1.Pod)

Apply writes VMSpec into pod annotations. Empty fields are skipped (cannot clear existing values).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL