README
¶
cocoon-operator
Kubernetes operator that manages VM-backed pod lifecycles through two CRDs: Hibernation (suspend/wake a single VM pod) and CocoonSet (manage a group of related VM pods).
Overview
- Hibernation controller -- watches
HibernationCRDs and annotates pods withcocoon.cis/hibernate=trueto trigger vk-cocoon snapshot/restore - CocoonSet controller -- watches
CocoonSetCRDs, creates/deletes agent and toolbox pods, manages suspend/unsuspend, and reports aggregate status - Pod watcher -- detects pod changes owned by CocoonSets and triggers reconciliation
Kubernetes controllers assume pods are replaceable. VM-backed workloads are not. This operator keeps stateful VM workflows inside native Kubernetes APIs: scale out from a known main VM, keep stable slot identities, hibernate without letting ReplicaSets recreate the pod, and expose aggregate state through CRD status.
A 30-second informer resync and 60-second periodic reconciliation catch status transitions that informer events may miss.
Architecture
The operator runs a single binary with three informer loops:
- Hibernation controller -- annotates pods for vk-cocoon snapshot/restore
- CocoonSet controller -- manages agent and toolbox pod groups
- Pod watcher -- triggers reconciliation on pod changes
Installation
Prerequisites
- Kubernetes cluster (v1.26+)
kubectlconfigured to talk to the cluster- vk-cocoon virtual kubelet provider running on at least one node
Deploy
- Install the CRDs:
kubectl apply -f deploy/crd.yaml
kubectl apply -f deploy/cocoonset-crd.yaml
- Deploy the operator (includes RBAC and Deployment):
kubectl apply -f deploy/deploy.yaml
- Verify the operator is running:
kubectl get pods -l app=cocoon-operator
Build from source
git clone https://github.com/cocoonstack/cocoon-operator.git
cd cocoon-operator
make build # produces ./cocoon-operator
Or with Docker:
docker build -t cocoon-operator .
Usage
Hibernate a pod
apiVersion: cocoon.cis/v1alpha1
kind: Hibernation
metadata:
name: hibernate-bot-1
namespace: prod
spec:
podName: sre-agent-xxx
action: hibernate
Manage a VM group
apiVersion: cocoon.cis/v1alpha1
kind: CocoonSet
metadata:
name: demo
spec:
agent:
image: ubuntu-dev-base
replicas: 1
resources:
cpu: "2"
memory: "4Gi"
toolboxes:
- name: windows
os: windows
image: windows-server-2022
mode: static
Manifests
| File | Description |
|---|---|
deploy/crd.yaml |
Hibernation CRD |
deploy/cocoonset-crd.yaml |
CocoonSet CRD |
deploy/deploy.yaml |
Operator Deployment + RBAC |
Development
make build # build binary
make test # run tests
make lint # run golangci-lint
make fmt # format code
make help # show all targets
Related Projects
| Project | Role |
|---|---|
| vk-cocoon | Virtual kubelet provider that performs the actual VM lifecycle |
| epoch | Snapshot storage backend for hibernated VMs |
| glance | Web UI that surfaces CocoonSet and Hibernation state |
| cocoon-webhook | Admission webhook for sticky scheduling |
License
Documentation
¶
Overview ¶
cocoon-operator manages Hibernation and CocoonSet CRDs for Cocoon VM pods.
It watches Hibernation CRDs and drives pod hibernate/wake by annotating pods with cocoon.cis/hibernate=true. vk-cocoon detects the annotation and handles the actual VM snapshot/restore lifecycle.
K8s concepts reused:
- Pod stays alive during hibernation (phase=Running, Ready=False, container Waiting "Hibernated"). This prevents RS/STS controllers from recreating it.
- Pod-deletion-cost annotation is used to influence which pod gets selected when the operator needs to work with Deployment scale operations.
- ConfigMap cocoon-vm-snapshots tracks suspended VM snapshots (managed by vk-cocoon).
Usage:
# Install CRDs
kubectl apply -f deploy/crd.yaml
kubectl apply -f deploy/cocoonset-crd.yaml
# Hibernate a pod
kubectl apply -f - <<EOF
apiVersion: cocoon.cis/v1alpha1
kind: Hibernation
metadata:
name: hibernate-bot-1
namespace: prod
spec:
podName: sre-agent-xxx
action: hibernate
EOF
# Wake it up
kubectl patch hibernation hibernate-bot-1 -n prod --type merge -p '{"spec":{"action":"wake"}}'
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cocoonmeta defines shared metadata keys and naming rules used across Cocoon controllers, webhooks, dashboards, and providers.
|
Package cocoonmeta defines shared metadata keys and naming rules used across Cocoon controllers, webhooks, dashboards, and providers. |
|
Package logutil provides a shared log initialization function for cocoonstack projects.
|
Package logutil provides a shared log initialization function for cocoonstack projects. |
|
Package version holds build-time metadata set via ldflags.
|
Package version holds build-time metadata set via ldflags. |