cocoon-common

The contract repository for the cocoonstack MicroVM platform: the CRD Go types, the pod annotation contract, and the OCI snapshot wire format that cocoon-operator, cocoon-webhook, vk-cocoon, and cocoon-net all import instead of re-declaring. Cross-repo shared code lives here and nowhere else, so producer and consumer cannot drift.

Documentation: cocoonstack.github.io/cocoon-common (source in docs/).

• API types — the cocoonset.cocoonstack.io/v1 group, enum defaults, the CEL rules that ship inside the CRDs, and the regeneration workflow
• Metadata contract — the three identifier namespaces, the typed annotation wrappers, VM naming and role inference, and the snapshot / hibernation / lifecycle contracts
• Kubernetes helpers — client config and rate limits, patch builders, conditions, TLS bring-up, and admission-webhook scaffolding
• Registry and snapshots — the artifact model, the v1 and v2 snapshot wire formats, push and pull tuning knobs, and the media-type vocabulary
• Runtime helpers — HTTP server lifecycle and logger setup

go get github.com/cocoonstack/cocoon-common@latest

import (
    v1 "github.com/cocoonstack/cocoon-common/apis/v1"
    "github.com/cocoonstack/cocoon-common/meta"
)

// The operator stamps the VM spec a pod's provider will read back.
meta.FromAgentSpec(cs.Spec.Agent, vmName, cs.Spec.SnapshotPolicy, "").Apply(pod)

// vk-cocoon reports lifecycle state on the same pod.
meta.LifecycleStatus{
    State:              meta.LifecycleStateReady,
    ObservedGeneration: meta.ReadCocoonSetGeneration(pod),
}.Apply(pod)

make build          # build all packages
make test           # vet + race-detected tests with coverage
make lint           # golangci-lint on linux + darwin
make fmt            # gofumpt + goimports
make generate       # regenerate deepcopy methods for api types
make manifests      # regenerate CRD YAML manifests for api types
make all            # deps + generate + manifests + fmt + lint + test + build
make help           # show all targets

After any change to apis/v1/*_types.go, run make generate manifests and commit the regenerated zz_generated.deepcopy.go and apis/v1/crds/*.yaml. CI re-runs both and fails on a dirty tree.

The Makefile detects Go workspace mode (go env GOWORK) and skips go mod tidy when active, so sibling checkouts resolve through go.work without forcing a release of this module.

MIT