README
¶
weaveplatform-oci
This repository is home to the image layer of the weave platform. Its purpose
is to give every weave project one way to package, publish, move and verify
virtual machine images for macOS, Windows and Linux guests, using standard OCI
registries as the transport. It defines the weave guest artifact contract,
implements it as a pure Go module, and ships the tools and pipelines built on
it: the weaveoci CLI, the weave-zot reference registry and publication workflows.
Imageweave owns image construction through Packer. OCI imports its completed artifacts through the Imageweave handoff. Hostweave owns pinned image selection and placement; compatible runtimes execute the resulting images. Construction, media selection and runtime qualification live in Imageweave; OCI retains artifact verification and authenticated admission. See the handoff guide for migration commands and qualification limits.
The motivation for this project stems from the following factors:
- One image format for the whole platform. hostweave, guestweave for macOS and guestweave for Windows each grew their own way of storing VM images, none of which the others could read. A single contract means an image built once runs on any weave host that supports its guest.
- VM disks are not container images. A guest disk is tens of gigabytes of mostly empty block device with firmware state beside it. The contract stores it as fixed-size, independently compressed, digest-addressed chunks of the raw disk: pulls resume, empty space costs nothing on the wire or on disk, and unchanged chunks are never uploaded twice.
- Identity never travels. Machine identifiers, MAC addresses, TPM state and SMBIOS serials are regenerated for every VM made from an image, so two VMs from the same image never collide on a network or in an MDM.
- Trust that works offline. Images are signed at build time (GitHub attestations or a cosign key) and promoted through a signed channel manifest whose root key stays offline. A consumer checks both before it unpacks a byte, whether it is connected to GHCR, a site mirror or an air-gapped layout on a USB drive.
- Any registry, no lock-in. GHCR, a private registry such as the bundled
weave-zot, Harbor or any OCI 1.1 registry, with mirrors and air-gap transfer. The format depends on no third-party VM image format or tool.
What is in the repository
| Component | What it is |
|---|---|
| Contract | The weave guest artifact contract v1 (weave-guest-v1): media types, config schema, chunk rules, state blobs, annotations, conformance checklist |
pkg/ |
The Go module consumers import: spec, chunk, pack, conformance, client, cache, fetch, sign, verify, channel, publish, profile, source, disk/vhd |
weaveoci |
The CLI: pack, inspect, push, pull, publish, sign, verify, channel management, air-gap export and import, verified source fetch |
deploy/zot/ |
weave-zot: zot preconfigured for multi-gigabyte VM artifacts, with private and mirror roles and a Compose deployment |
images/ |
Image definitions, in tiers: a base is the vendor OS unmodified, and derived tiers (agent, then workload layers) are built on it by digest. linux/ubuntu-24.04-base is built from Canonical's signed cloud images and published as ghcr.io/weaveplatform/weave-images/ubuntu-24.04-base |
.github/workflows/ |
The quality gate, the reusable Linux image build, and releases of the weaveoci and weave-zot container images and binaries |
The consumers are hostweave, which runs ephemeral VM workloads from these images, and guestweave-cli-macos and guestweave-cli-windows, which pull, clone and push them and still build VMs from installation media without any registry. Promotion runs through weaveplatform-release-channels.
Documentation
The design set lives in docs/research:
- OCI primer and prior art — the standards and how others ship VM images
- Registries and GitHub, supply chain, large artifacts — the constraints the design answers
- Build pipelines and target architecture — how images are made and where they flow
- Image production — Imageweave ownership, candidate handoff and acceptance reports
- Artifact contract v1 — the format
- Shared Go module — the packages, the CLI and the bundle format
- Deployment profiles — github, private and hybrid deployments,
weave-zot, cosign keys - guestweave adoption — standalone or registry-backed guestweave
- Migration plan, open questions, decision records and the glossary
Installing
Each release
publishes weaveoci archives for macOS, Linux and Windows (amd64 and arm64)
with SHA256SUMS, and two signed container images:
docker run --rm ghcr.io/weaveplatform/weaveoci:latest version
docker run -d -p 5000:5000 ghcr.io/weaveplatform/weave-zot:latest
From source (Go 1.27, no cgo):
make build # bin/weaveoci-<os>-<arch> for every release platform
Using weaveoci
# pull a published image, verified per the profile, and unpack it as sparse raw disks
weaveoci pull weave-images/ubuntu-24.04-base:24.04-20260926-r1 --platform linux/arm64 --to ./ubuntu
# check an image against the contract
weaveoci export-layout weave-images/ubuntu-24.04-base:24.04-20260926-r1 ./layout
weaveoci inspect ./layout --strict --deep
# build an image from a raw disk, verified against the distribution's signed checksums
weaveoci source fetch <url> --checksums <url> --signature <url> --keyring keys.asc --fingerprint <fpr> --out disk.raw --record src.json
weaveoci bundle init ./bundle --disk disk.raw --source src.json --os linux --arch arm64 ...
weaveoci publish ./bundle --repository ubuntu-24.04-base --tag 24.04-20260926-r1 --promotion-out entry.json
# run a channel of your own and move images across an air gap
weaveoci channel promote stable.json entry.json && weaveoci channel sign signing.key stable.json
weaveoci export-layout <ref> ./usb && weaveoci import-layout ./usb
Which registry, signing provider and verification mode apply comes from a
deployment profile; see deployment profiles.
Run weaveoci --help for every verb.
Quality gate
Every pull request must pass vet, blocking golangci-lint, unit tests on Linux,
macOS and Windows, the godog acceptance suite against weave-zot and
registry:3 in Docker, govulncheck, a cross-compile, and merged coverage of at
least 95% total, 95% for handoff and evidence verification, and 90% for other packages. make gate runs the same locally (with
GOWORK=off). Dependencies track their latest releases through Dependabot and
deps-refresh.yml, and merge automatically once the gate passes.
License
MIT, see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
weaveoci
command
Command weaveoci packs, inspects and unpacks weave guest artifacts.
|
Command weaveoci packs, inspects and unpacks weave guest artifacts. |
|
internal
|
|
|
buildinfo
Package buildinfo carries version metadata injected with -ldflags -X.
|
Package buildinfo carries version metadata injected with -ldflags -X. |
|
cli
Package cli implements the weaveoci command line.
|
Package cli implements the weaveoci command line. |
|
testbundle
Package testbundle writes small, sparse, contract-shaped bundle directories for unit and acceptance tests.
|
Package testbundle writes small, sparse, contract-shaped bundle directories for unit and acceptance tests. |
|
testregistry
Package testregistry runs an in-process OCI registry for tests: the go-containerregistry in-memory registry behind a chi router that can require basic auth, hide the referrers API, fail requests transiently, count requests and refuse tag updates.
|
Package testregistry runs an in-process OCI registry for tests: the go-containerregistry in-memory registry behind a chi router that can require basic auth, hide the referrers API, fail requests transiently, count requests and refuse tag updates. |
|
pkg
|
|
|
agentcheck
Package agentcheck exercises a running image's agent through the shared SDK.
|
Package agentcheck exercises a running image's agent through the shared SDK. |
|
cache
Package cache is the device-side content-addressed store for weave guest artifacts (decision 0008): one OCI image layout shared by every image on a device, so a chunk present in two images is stored once; in-use pins that garbage collection never removes; least-recently-used eviction down to a quota; a disk-space check before the first byte of a pull; and OCI-layout export and import for air-gapped sites, with referrers carried along.
|
Package cache is the device-side content-addressed store for weave guest artifacts (decision 0008): one OCI image layout shared by every image on a device, so a chunk present in two images is stored once; in-use pins that garbage collection never removes; least-recently-used eviction down to a quota; a disk-space check before the first byte of a pull; and OCI-layout export and import for air-gapped sites, with referrers carried along. |
|
channel
Package channel reads, writes, signs and verifies weave channel manifests (decision 0006): the promotion record whose signature chain is an offline root key, an endorsed signing key, and the manifest.
|
Package channel reads, writes, signs and verifies weave channel manifests (decision 0006): the promotion record whose signature chain is an offline root key, an endorsed signing key, and the manifest. |
|
chunk
Package chunk splits a raw guest disk into contract chunk layers and reassembles chunk layers into a sparse raw disk (contract §5).
|
Package chunk splits a raw guest disk into contract chunk layers and reassembles chunk layers into a sparse raw disk (contract §5). |
|
client
Package client is the registry transport for weave guest artifacts, built on oras-go v2.
|
Package client is the registry transport for weave guest artifacts, built on oras-go v2. |
|
conformance
Package conformance runs the contract §12 checklist over an index or a manifest held in any OCI content source.
|
Package conformance runs the contract §12 checklist over an index or a manifest held in any OCI content source. |
|
disk/vhd
Package vhd reads and writes the 512-byte footer that turns a raw disk into a fixed VHD (Microsoft Virtual Hard Disk Image Format Specification, version 1.0).
|
Package vhd reads and writes the 512-byte footer that turns a raw disk into a fixed VHD (Microsoft Virtual Hard Disk Image Format Specification, version 1.0). |
|
disk/virtualdisk
Package virtualdisk uses Windows' virtual-disk APIs for local VHDX storage.
|
Package virtualdisk uses Windows' virtual-disk APIs for local VHDX storage. |
|
fetch
Package fetch is the consumer side of the contract in one call: resolve a reference, pull it into the device cache, verify it against the profile's policy, select a platform and optionally unpack it as a bundle.
|
Package fetch is the consumer side of the contract in one call: resolve a reference, pull it into the device cache, verify it against the profile's policy, select a platform and optionally unpack it as a bundle. |
|
handoff
Package handoff imports completed Imageweave/Packer candidates without running builders.
|
Package handoff imports completed Imageweave/Packer candidates without running builders. |
|
imagecheck
Package imagecheck checks image acceptance evidence against the exact OCI subject.
|
Package imagecheck checks image acceptance evidence against the exact OCI subject. |
|
macsetup
Package macsetup defines deterministic macOS onboarding independent of its UI transport.
|
Package macsetup defines deterministic macOS onboarding independent of its UI transport. |
|
pack
Package pack converts between a bundle directory (raw disks, state files and a bundle.json describing them) and a contract v1 manifest and index in an OCI content store, usually an OCI image layout on disk.
|
Package pack converts between a bundle directory (raw disks, state files and a bundle.json describing them) and a contract v1 manifest and index in an OCI content store, usually an OCI image layout on disk. |
|
profile
Package profile loads the deployment profile file shared by weaveoci, hostweave and the guestweave CLIs (decision 0011): which registry is canonical, which mirrors to read from, how images are signed when published, what consumers verify, and which channel trust anchors they accept.
|
Package profile loads the deployment profile file shared by weaveoci, hostweave and the guestweave CLIs (decision 0011): which registry is canonical, which mirrors to read from, how images are signed when published, what consumers verify, and which channel trust anchors they accept. |
|
publish
Package publish is the publication pipeline as a library (decision 0007): pack bundles into a contract index, check conformance, push every blob then the manifests under a build tag that must not already exist, sign with the profile's provider, pull the index back into an empty store and verify it and its signature, and emit the channel promotion entry.
|
Package publish is the publication pipeline as a library (decision 0007): pack bundles into a contract index, check conformance, push every blob then the manifests under a build tag that must not already exist, sign with the profile's provider, pull the index back into an empty store and verify it and its signature, and emit the channel promotion entry. |
|
sign
Package sign produces cosign-compatible key signatures for weave guest artifacts (decision 0006, private profile).
|
Package sign produces cosign-compatible key signatures for weave guest artifacts (decision 0006, private profile). |
|
source
Package source downloads the upstream media an image is built from (a distribution cloud image, an ISO) and refuses it unless the distribution's own checksum file vouches for it.
|
Package source downloads the upstream media an image is built from (a distribution cloud image, an ISO) and refuses it unless the distribution's own checksum file vouches for it. |
|
spec
Package spec implements the weave guest artifact contract v1 (docs/research/09-artifact-contract-v1.md): media types, annotation keys, the config document and its JSON Schema, the canonical zero chunk, and the conformance rules that validate an index or a manifest without fetching disk chunks.
|
Package spec implements the weave guest artifact contract v1 (docs/research/09-artifact-contract-v1.md): media types, annotation keys, the config document and its JSON Schema, the canonical zero chunk, and the conformance rules that validate an index or a manifest without fetching disk chunks. |
|
verify
Package verify decides whether an artifact may be used (decision 0006): cosign-key signatures and GitHub artifact attestations attached as OCI referrers, and membership in a verified channel manifest, combined by a verification mode (channel, signature, both or none).
|
Package verify decides whether an artifact may be used (decision 0006): cosign-key signatures and GitHub artifact attestations attached as OCI referrers, and membership in a verified channel manifest, combined by a verification mode (channel, signature, both or none). |
Click to show internal directories.
Click to hide internal directories.