Skip to content

Commit 26dd1c7

Browse files
vmg-devvmg-dev
committed
first commit
0 parents  commit 26dd1c7

6 files changed

Lines changed: 292 additions & 0 deletions

‎01-oci2gondolin-spec.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# 01 — `oci2gondolin` Spec
2+
3+
## Objective
4+
Convert an OCI image into a Gondolin-compatible boot artifact set that can be loaded via:
5+
6+
- `VM.create({ sandbox: { rootDiskPath, ... } })` (rootfs-only output), or
7+
- `GONDOLIN_GUEST_DIR=<asset-dir>` / `sandbox.imagePath=<asset-dir>` (full bundle output)
8+
9+
## Constraints
10+
- No changes to Gondolin runtime APIs required for MVP
11+
- Keep host-side extraction secure (no path traversal, no symlink escapes)
12+
- Ensure output keeps Gondolin guest contract required by `vm.exec`
13+
14+
## Inputs
15+
Support at least these sources:
16+
17+
1. `--image <ref>` (registry image reference)
18+
2. `--oci-layout <path>` (OCI layout directory)
19+
3. `--oci-tar <path>` (OCI archive)
20+
21+
## Outputs
22+
### Mode A: `rootfs`
23+
Output files:
24+
- `rootfs.ext4`
25+
- `meta.json` (source digest, platform, entrypoint/cmd/env/workdir/user)
26+
27+
### Mode B: `assets`
28+
Output directory:
29+
- `vmlinuz-virt`
30+
- `initramfs.cpio.lz4`
31+
- `rootfs.ext4`
32+
- `manifest.json`
33+
34+
`assets` mode copies kernel/initramfs from a selected Gondolin base bundle, then injects converted rootfs.
35+
36+
## CLI (proposed)
37+
```bash
38+
oci2gondolin --image ghcr.io/org/app:latest \
39+
--platform linux/arm64 \
40+
--out ./out/app-assets \
41+
--mode assets
42+
43+
oci2gondolin --oci-tar ./app.oci.tar \
44+
--out ./out/app-rootfs \
45+
--mode rootfs
46+
```
47+
48+
## Functional pipeline
49+
1. Parse source + platform
50+
2. Resolve OCI manifest (single or index)
51+
3. Download/read blobs + verify digest
52+
4. Apply layers in order with whiteout handling
53+
5. Materialize merged rootfs tree
54+
6. Inject Gondolin runtime requirements
55+
7. Build `rootfs.ext4`
56+
8. Emit metadata + optional full assets bundle
57+
58+
## Runtime compatibility contract
59+
For Gondolin SDK features to work, output rootfs must include:
60+
- `sandboxd` available and started by init
61+
- `sandboxfs` available if VFS mount behavior is expected
62+
- init flow compatible with Gondolin initramfs handoff (`switch_root /init`) unless full custom initramfs is supplied
63+
64+
## MVP scope
65+
- Linux images only
66+
- `amd64` + `arm64`
67+
- gzip-compressed layers required
68+
- whiteouts supported
69+
- private registry auth via standard bearer token flow
70+
71+
## Out of scope (initially)
72+
- Windows containers
73+
- non-Linux platforms
74+
- advanced runtime translation (`HEALTHCHECK`, `STOPSIGNAL`, cgroups tuning)
75+
- full parity with Docker runtime semantics

‎02-dockerfile2gondolin-wrapper.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# 02 — `dockerfile2gondolin` Wrapper
2+
3+
## Objective
4+
Provide a convenience CLI that takes a Dockerfile context and produces Gondolin output by delegating to:
5+
6+
1. BuildKit (Dockerfile -> OCI)
7+
2. `oci2gondolin` (OCI -> Gondolin)
8+
9+
## Why wrapper only
10+
Avoid reimplementing Dockerfile semantics. BuildKit already supports modern Dockerfile behavior and caching.
11+
12+
## Supported backends (priority)
13+
1. `docker buildx build`
14+
2. standalone `buildctl`
15+
16+
## CLI (proposed)
17+
```bash
18+
dockerfile2gondolin \
19+
--file ./Dockerfile \
20+
--context . \
21+
--platform linux/arm64 \
22+
--out ./out/app-assets \
23+
--mode assets
24+
```
25+
26+
Optional:
27+
- `--builder docker-buildx|buildctl`
28+
- `--target <stage>`
29+
- `--build-arg KEY=VALUE` (repeatable)
30+
- `--secret id=...,src=...` (pass-through)
31+
32+
## Internal flow
33+
1. Validate builder availability
34+
2. Build Dockerfile into temp OCI tar/layout
35+
3. Invoke `oci2gondolin` with resulting OCI artifact
36+
4. Copy final output to requested destination
37+
5. Emit concise build summary
38+
39+
## Error mapping
40+
Map common failures to clear messages:
41+
- builder missing
42+
- build step failed
43+
- OCI output missing/invalid
44+
- conversion failed
45+
46+
## Deliverable quality bar
47+
- deterministic output for same Dockerfile + pinned base digests
48+
- clear logs separating build phase and conversion phase
49+
- no Gondolin code changes required

‎03-implementation-phases.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# 03 — Implementation Phases
2+
3+
## Timeline (single engineer estimate)
4+
- MVP: **2–4 weeks**
5+
- Hardened v1: **6–10 weeks**
6+
7+
## Phase breakdown
8+
9+
## Phase 0 — Spike (2–3 days)
10+
- Validate rootfs-only loading path with current Gondolin (`rootDiskPath`)
11+
- Confirm minimum runtime files/processes needed for `vm.exec`
12+
- Capture one known-good manual conversion recipe
13+
14+
**Exit criteria:** end-to-end manual demo from OCI image to running VM
15+
16+
## Phase 1 — `oci2gondolin` scaffolding (2–3 days)
17+
- CLI parser + config model
18+
- source abstraction (`image ref`, `oci tar`, `oci layout`)
19+
- output modes (`rootfs`, `assets`)
20+
21+
**Exit criteria:** CLI skeleton + dry-run mode
22+
23+
## Phase 2 — OCI resolver/puller (4–6 days)
24+
- auth token flow
25+
- manifest/index selection by platform
26+
- blob download/read + digest verification
27+
- local blob cache by digest
28+
29+
**Exit criteria:** pull and verify layers/config for public images
30+
31+
## Phase 3 — Layer apply engine (4–7 days)
32+
- ordered extraction
33+
- whiteout/opaque directory handling
34+
- secure extraction checks
35+
36+
**Exit criteria:** merged rootfs matches expected filesystem semantics
37+
38+
## Phase 4 — Gondolin materialization (3–5 days)
39+
- inject runtime requirements
40+
- ext4 build step
41+
- emit `meta.json` and/or full assets bundle
42+
43+
**Exit criteria:** converted image boots and supports `vm.exec`
44+
45+
## Phase 5 — `dockerfile2gondolin` wrapper (3–5 days)
46+
- BuildKit integration (`buildx`, `buildctl`)
47+
- argument passthrough for target/build args/secrets
48+
- temporary OCI artifact handling
49+
50+
**Exit criteria:** Dockerfile -> Gondolin in one command
51+
52+
## Phase 6 — Hardening + docs (4–7 days)
53+
- integration tests with multiple fixtures
54+
- performance/caching tuning
55+
- user docs + troubleshooting
56+
57+
**Exit criteria:** v1 candidate release
58+
59+
## Suggested sequencing notes
60+
- Keep converter core independent from CLI wrappers
61+
- Keep all Dockerfile logic in wrapper layer
62+
- Ensure all artifacts are reproducible and cache-addressable by digest

‎04-testing-and-release.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# 04 — Testing and Release Plan
2+
3+
## Test matrix
4+
5+
## Unit tests
6+
- Image ref parsing
7+
- Manifest/index platform selection
8+
- Digest verification
9+
- Whiteout handling logic
10+
- Secure extraction path checks
11+
12+
## Integration tests
13+
- Public image conversion (alpine, debian-slim, distroless-like)
14+
- Converted rootfs boots in Gondolin and can execute command
15+
- Entry point/env/workdir metadata captured correctly
16+
17+
## Regression/security tests
18+
- Path traversal tar entries
19+
- Symlink overwrite attempts
20+
- Duplicate file/dir collisions across layers
21+
22+
## Performance checks
23+
- Cold pull timing vs warm cache timing
24+
- Output rootfs size sanity checks
25+
- Repeated conversion correctness with cache hits
26+
27+
## Release criteria
28+
- `oci2gondolin` stable CLI + docs
29+
- `dockerfile2gondolin` wrapper stable for at least one backend (`buildx`)
30+
- deterministic outputs for pinned digests
31+
- passing integration suite on macOS + Linux hosts
32+
33+
## Versioning/release strategy
34+
- Start at `0.x`
35+
- publish CLI artifacts and npm package (if Node-based)
36+
- include compatibility table:
37+
- supported Gondolin versions
38+
- supported host OS
39+
- supported target architectures

‎05-open-questions.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# 05 — Open Questions
2+
3+
## 1) Runtime injection strategy
4+
How should `sandboxd`/`sandboxfs`/`sandboxssh` be injected?
5+
- copy from known Gondolin base assets
6+
- or package alongside converter and inject directly
7+
8+
## 2) Init ownership
9+
Should converted images reuse Gondolin init scripts by default, or attempt to preserve container entrypoint semantics directly in init?
10+
11+
## 3) `USER` behavior
12+
For non-root container users, should converter:
13+
- preserve user exactly if present
14+
- auto-create missing user
15+
- fallback to root with warning
16+
17+
## 4) Full assets vs rootfs-only default
18+
Which mode should be default for better UX?
19+
- `assets` is easiest to run from CLI
20+
- `rootfs` is simpler if caller already controls kernel/initramfs
21+
22+
## 5) Backend policy for Dockerfile wrapper
23+
Should initial wrapper support only `docker buildx`, or also standalone `buildctl` on day one?
24+
25+
## 6) Distribution model
26+
Should this live as:
27+
- separate repo/tool (preferred for isolation)
28+
- subpackage within Gondolin monorepo
29+
30+
## 7) Security posture
31+
Do we need mandatory signature/cosign verification in v1, or treat as optional policy hook?
32+
33+
## 8) Metadata handoff
34+
How should entrypoint/cmd/env/workdir/user metadata be passed to callers?
35+
- JSON sidecar only
36+
- generated launcher script
37+
- direct VM helper API in separate SDK package

‎README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Gondolin Image Tooling Plan
2+
3+
## Goal
4+
Create external tooling that converts container artifacts into images Gondolin can boot **without modifying Gondolin core code**.
5+
6+
## Recommendation
7+
Build in this order:
8+
9+
1. **`oci2gondolin` first** (core converter)
10+
2. **`dockerfile2gondolin` second** (thin wrapper around BuildKit + `oci2gondolin`)
11+
12+
This keeps complexity low and allows multiple input paths (registry, CI-produced OCI tar, local OCI layout).
13+
14+
## Why OCI-first
15+
- Dockerfile support is effectively a full build system
16+
- OCI image/manifest/layers are a stable output contract
17+
- Reusable converter for any upstream build stack
18+
19+
## Deliverables
20+
- `oci2gondolin` CLI
21+
- `dockerfile2gondolin` CLI (wrapper)
22+
- Test fixtures + conformance tests
23+
- Basic docs and examples
24+
25+
## Directory contents
26+
- [`01-oci2gondolin-spec.md`](./01-oci2gondolin-spec.md)
27+
- [`02-dockerfile2gondolin-wrapper.md`](./02-dockerfile2gondolin-wrapper.md)
28+
- [`03-implementation-phases.md`](./03-implementation-phases.md)
29+
- [`04-testing-and-release.md`](./04-testing-and-release.md)
30+
- [`05-open-questions.md`](./05-open-questions.md)

0 commit comments

Comments
 (0)