README
¶
weaveplatform-oci
One OCI image approach for the weave projects: the weave guest artifact
contract for macOS, Windows and Linux VM images, a Go module that packs,
inspects, transfers and verifies those artifacts, the weaveoci CLI, the
weave-zot reference private registry, and the publication workflows used
by hostweave, guestweave-cli-macos and guestweave-cli-windows.
Start with the research and design set: the contract is 09-artifact-contract-v1.md, the module design is 10-shared-go-module.md, and the phases are in 11-migration.md.
Status
Phase 1 is implemented: the public packages pkg/spec, pkg/chunk,
pkg/pack and pkg/conformance, weaveoci pack|inspect|unpack|healthcheck,
the weave-zot image, and the quality gate.
Layout
| Path | Contents |
|---|---|
pkg/ |
Public packages imported by hostweave and the guestweave CLIs |
internal/ |
Packages used only by this project (CLI commands, build info, test bundle generator) |
cmd/weaveoci/ |
The CLI entry point |
deploy/zot/ |
The weave-zot image, config roles and Compose file |
test/acceptance/ |
godog features run against the real binary and registries |
docs/research/ |
Research, contract, architecture and decision records |
| Registry transport, caching, signing and publishing arrive in phase 2. |
Quick start
make build # bin/weaveoci-<os>-<arch>
weaveoci pack ./bundle --out ./layout --tag 26.0-25A354-r1
weaveoci inspect ./layout --strict --deep # contract conformance checklist
weaveoci unpack ./layout ./out --resume # sparse raw disks + state files
A bundle is a directory of raw disks, state files and a bundle.json
(format).
Quality gate
| Command | What it runs |
|---|---|
make test |
unit tests with -race -shuffle=on, coverage to cover/unit |
make accept |
godog features against the real weaveoci binary, weave-zot and registry:3.1.2 in Docker |
make cover |
merged coverage: ≥95% total, ≥90% per package |
make lint / make vuln |
golangci-lint and govulncheck |
make gate |
all of the above, as CI runs them (quality-gate.yml) |
The module builds with GOWORK=off (the Makefile sets it).
Private registry
cd deploy/zot && htpasswd -bBn publisher '<password>' > htpasswd && docker compose up -d
See deploy/zot and deployment profiles.
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
|
|
|
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. |
|
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). |
|
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.