Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/actions/python-distributions/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,12 @@ runs:

import adx_environment
import akernel_sdk
from akernel_sdk import ComposeProject, DockerRuntime, ServiceHandle, ServiceProcessHandle
from importlib.resources import files

assert all(callable(value) for value in (ComposeProject, DockerRuntime, ServiceHandle, ServiceProcessHandle))
for helper in ("_image_bridge_guest.py", "_docker_network_guest.py", "_service_process_guest.py"):
assert files("akernel_sdk").joinpath(helper).read_text()

assert version("akernel-sdk") == os.environ["EXPECTED_VERSION"]
assert any(
Expand Down
22 changes: 22 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,28 @@ concurrency:
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
image-bridge:
name: Managed Docker image bridge
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Set up Go
uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
with:
go-version: '1.25.5'
cache-dependency-path: builder/image-bridge/go.sum
- name: Test and build the host/guest helper
working-directory: builder/image-bridge
env:
CGO_ENABLED: '0'
run: |
test -z "$(gofmt -l .)"
go vet ./...
go test ./...
GOOS=linux GOARCH=amd64 go build -trimpath -o "$RUNNER_TEMP/akernel-image-bridge" .

sdk-unit-tests:
name: Python SDK unit tests (${{ matrix.python-version }})
runs-on: ubuntu-latest
Expand Down
13 changes: 13 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -869,3 +869,16 @@ ADX profile, applying patches only to present roles. Resolve profile/role
selectors with ADX's single-pass environment/default/escape rules while
preserving source expressions for the authoritative loader. Severity queries consume
Collector-normalized log metadata and plain bodies.


## Managed Docker runtime

The source-preview SDK owns Compose image discovery/OCI metadata validation, ROFS mount plans and guest bridge/containerd/dockerd startup. Sources live in `builder/image-bridge`, `builder/dind`, and `sdk/python/akernel_sdk/_docker_runtime.py`. Callers supply original project files and keep service orchestration in their adapter. Snapshot restore must rebind mounts, runtime extra_config and local tunnels without rerunning startup. Reuse the existing sandboxd image provider; do not add a parallel layer cache or modify deployment/runtime pins for client refactoring. See the SDK and builder guides for managed-upper prerequisites and supported scope.

Compose project lifecycle and Docker service/process operations are SDK extensions in `_compose.py` and `_service_process.py`; the dependency-free `_service_process_guest.py` runs in the selected service PID namespace. Keep project descriptors JSON-compatible and restore attachment free of fresh-boot operations. Preserve explicit build/network-policy/up boundaries, unknown-outcome identities, source fencing, and container/process start-time checks before signals. Callers retain task/harness semantics. Run the real-process helper unit tests with owned-process cleanup and the complete SDK quality gate when changing these contracts. This feature does not add Docker semantics to Agent DX or change runtime pins.

Automatic Compose image preparation covers image-only services as well as Dockerfile bases. Verify pinned Docker references and committed ROFS snapshots instead of running native pulls, including during up. Keep digest-reference regression coverage and fail closed on missing registrations; never relax bridge extraction protection or populate the private upper with replacement lower layers.

Managed discovery requires helper schema 2 and probes capabilities before sending project input. Confine client Dockerfile/build-context and `.env` reads to the frozen project; never inherit unspecified host environment variables. External include/extends files remain unsupported. Validate manifest/config/chain relationships and allow legitimate same-chain roots with different target digests. Keep the empty automatic-plan marker for scratch-only builds. Unknown command exits and failed cancellation retain their identities and cleanup errors without replay.

Managed Compose defaults preserve native IPv4 bridge definitions. Keep forwarding/NAT and per-service tunnel exposure in the SDK/runtime, with daemon-only legacy iptables selection for Docker DNS. Restore attachment stays pure; explicit reconnect_network refreshes only owned chains for the new outer TAP before the harness resumes. Do not claim external TCP address migration. Keep the opt-in Compose network integration regression, including existing inner and published-port sockets, synchronized with these APIs. Docker 28 operator flags are prerequisites; client work must not change production or runtime bundle pins.
12 changes: 12 additions & 0 deletions builder/dind/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Build from the repository root: docker build -f builder/dind/Dockerfile .
ARG GO_BUILD_IMAGE=golang:1.25.5-bookworm
FROM ${GO_BUILD_IMAGE} AS bridge
WORKDIR /src
COPY builder/image-bridge/go.mod builder/image-bridge/go.sum ./
RUN go mod download
COPY builder/image-bridge/ ./
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o /out/akernel-image-bridge .

FROM docker:28.3.3-dind
RUN apk add --no-cache bash python3 coreutils util-linux shadow tar xz
COPY --from=bridge /out/akernel-image-bridge /opt/akernel-image-bridge
27 changes: 27 additions & 0 deletions builder/image-bridge/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Managed Docker image bridge

This helper exposes sandboxd-provided immutable ROFS image mounts as committed containerd snapshots, with private upper/work directories owned by the sandbox. It does not introduce another registry layer cache. Metadata-only image registration and source Dockerfile/Compose discovery use containerd, compose-go and BuildKit parsers.

The snapshotter originated in tianyuzhou95's agent-worker POC, commit `9b3434d36086d920b6bb7f3322da642381a254b8`. The managed-upper runtime contract was ported to sandboxd separately. Preserve this provenance when moving or publishing the helper.

Build the host/guest helper on a Linux/amd64 client:

```sh
cd builder/image-bridge
CGO_ENABLED=0 go test ./...
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -o /path/to/akernel-image-bridge .
```

The Python SDK's `prepare_compose_images()` invokes `--mode discover`, resolves tags and verifies OCI manifest/config bytes. Credentials stay on the client; the runtime image manager must independently be authorized to fetch the pinned images. Only metadata is uploaded. Layer bytes are mounted by the existing sandboxd OCI/ROFS provider, which owns node-wide caching and distribution.

`DockerRuntime.sandbox_options()` supplies the ROFS mounts and `fileBackedTmpfsMounts` to fresh creation and snapshot restore. `DockerRuntime.start()` uploads the helper when configured, starts its private containerd and bridge, registers original image aliases, then starts dockerd. Call start only once on a fresh sandbox; never on a restored sandbox. Failed startup is cleaned up by the owner deleting the newly created sandbox, not by touching shared node state.

Automatic Compose uses these mounted roots for image-only services as well as build bases. After registration, the SDK verifies aliases against their pinned target digests and checks the committed ROFS snapshots. It does not use native Compose pull for those inputs: Docker Compose can pull digest references even with `--policy missing`, which would incorrectly enter the ordinary layer extraction path. Automatic `up` also disables repeat pulls. An absent registration fails instead of bypassing the mount plan or silently copying image layers into private storage. Different image manifests/configurations can legitimately share one chain ID; the validated configuration and chain bind their ROFS roots before verification allows that sharing.

The current SDK requires **discovery schema 2**. Check with `akernel-image-bridge --mode capabilities`; older helpers (including the earlier `72e706e2` attachment) must be replaced before using this SDK. The probe sends no project data. Discovery rejects Dockerfile/build-context paths or `.env` links escaping the frozen project and does not inherit unspecified client environment variables. External `include` / `extends.file`, remote contexts and platform emulation are outside the source-preview profile; pass explicit supported Compose files instead. The runtime bundle and Sandboxd contract do not change with this client-helper update.

Use `DockerRuntime.default_image`, the public Docker Hub `docker.io/library/docker:28.3.3-dind` image. Fresh startup installs missing Alpine support packages, so no custom runtime image build or push is required. An explicitly supplied outer image must provide Docker 28.3.3, containerd/ctr, Python 3, findmnt/mount, Bash, iproute tools, iptables-legacy and iptables-legacy-restore. `builder/dind/Dockerfile` optionally packages these and the guest helper; use repository root as build context. The SDK can upload the matching helper from the client. No helper binary is downloaded automatically.

The default Linux/amd64 runsc profile preserves default/custom IPv4 Compose bridge networks, DNS and TCP/UDP userland port mappings. The operator must enable `extra_args = ["--net-raw=true", "--allow-packet-socket-write=true"]` under `[plugin.runtime.runsc]` for Docker 28. The SDK owns in-sandbox legacy forwarding/SNAT and per-service tunnel entries; Docker owns bridges/IPAM/DNS. After restore call `ComposeProject.reconnect_network()` to rebind the new outer TAP without restarting Docker. Task Dockerfiles and Compose files remain unchanged. Host networking is an explicit compatibility option. Remote contexts, runtime-created unknown image references and platform emulation remain outside this profile. Ordinary native Docker builds still run inside the sandbox. This is not a complete shared Docker content store: exporting/saving/pushing an image may still fetch layers.

The file-backed upper requires sandboxd managed tmpfs support and runsc checkpoint support for those mounts. It consumes the sandbox storage limit. Reflink must be configured by the deployment, on a compatible filesystem and same mount; the SDK does not change deployment durability policy or replace runtime bundles. Memory mode is an explicit alternative and counts file contents toward memory snapshots.
272 changes: 272 additions & 0 deletions builder/image-bridge/discover.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,272 @@
package main

// Discovery uses the Compose and Dockerfile implementations, not regular
// expressions over user files. The original project is still built by Docker.
import (
"context"
"encoding/json"
"fmt"
"io"
"os"
"path/filepath"
"sort"
"strconv"
"strings"

"github.com/compose-spec/compose-go/v2/cli"
"github.com/compose-spec/compose-go/v2/types"
"github.com/distribution/reference"
"github.com/moby/buildkit/frontend/dockerfile/instructions"
"github.com/moby/buildkit/frontend/dockerfile/parser"
"github.com/moby/buildkit/frontend/dockerfile/shell"
"gopkg.in/yaml.v3"
)

func projectPath(root, path string) (string, error) {
if !filepath.IsAbs(path) {
path = filepath.Join(root, path)
}
resolved, err := filepath.EvalSymlinks(path)
if err != nil {
return "", fmt.Errorf("cannot resolve managed project input: %w", err)
}
relative, err := filepath.Rel(root, resolved)
if err != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) {
return "", fmt.Errorf("managed Compose inputs must stay within the project directory")
}
return resolved, nil
}

func validateComposeSources(root string, files []string) error {
// Only explicitly supplied top-level files may live outside the frozen
// context (SDK overlays do). Never let user YAML load other client files.
for _, file := range files {
data, err := os.ReadFile(file)
if err != nil {
return err
}
var document map[string]any
if err = yaml.Unmarshal(data, &document); err != nil {
return err
}
if document["include"] != nil {
return fmt.Errorf("managed Compose discovery does not support include; supply explicit project files")
}
services, _ := document["services"].(map[string]any)
for _, value := range services {
service, _ := value.(map[string]any)
extends, _ := service["extends"].(map[string]any)
if extends["file"] != nil {
return fmt.Errorf("managed Compose discovery does not support extends.file; supply explicit project files")
}
}
}
if _, err := os.Lstat(filepath.Join(root, ".env")); err == nil {
_, err = projectPath(root, ".env")
return err
} else if !os.IsNotExist(err) {
return err
}
return nil
}

func dockerfileImages(source string, build *types.BuildConfig) ([]string, error) {
parsed, err := parser.Parse(strings.NewReader(source))
if err != nil {
return nil, err
}
stages, args, err := instructions.Parse(parsed.AST, nil)
if err != nil {
return nil, err
}
values := map[string]string{
"BUILDPLATFORM": "linux/amd64", "BUILDOS": "linux", "BUILDARCH": "amd64", "BUILDVARIANT": "",
"TARGETPLATFORM": "linux/amd64", "TARGETOS": "linux", "TARGETARCH": "amd64", "TARGETVARIANT": "",
}
lex := shell.NewLex(parsed.EscapeToken)
expand := func(word string) (string, error) {
env := make([]string, 0, len(values))
for k, v := range values {
env = append(env, k+"="+v)
}
value, _, err := lex.ProcessWord(word, shell.EnvsFromSlice(env))
return value, err
}
for _, command := range args {
for _, arg := range command.Args {
if override, ok := build.Args[arg.Key]; ok && override != nil {
values[arg.Key] = *override
continue
} else if ok {
if value, present := os.LookupEnv(arg.Key); present {
values[arg.Key] = value
continue
}
}
if arg.Value != nil {
value, err := expand(*arg.Value)
if err != nil {
return nil, err
}
values[arg.Key] = value
}
}
}
var images []string
knownStages := map[string]bool{}
for _, stage := range stages {
knownStages[strings.ToLower(stage.Name)] = true
}
add := func(name string, allowStage bool) error {
if strings.EqualFold(name, "scratch") || (allowStage && knownStages[strings.ToLower(name)]) {
return nil
}
if allowStage {
if _, err := strconv.Atoi(name); err == nil {
return nil
}
}
if context, ok := build.AdditionalContexts[name]; ok {
if !strings.HasPrefix(context, "docker-image://") {
return fmt.Errorf("automatic image preparation needs a docker-image context for %s", name)
}
name = strings.TrimPrefix(context, "docker-image://")
}
ref, err := reference.ParseNormalizedNamed(name)
if err != nil {
return fmt.Errorf("invalid external image %q: %w", name, err)
}
images = append(images, reference.TagNameOnly(ref).String())
return nil
}
previousStages := map[string]bool{}
for _, stage := range stages {
if stage.Platform != "" {
platform, err := expand(stage.Platform)
if err != nil || platform != "linux/amd64" {
return nil, fmt.Errorf("automatic image preparation supports linux/amd64, got %q", platform)
}
}
name, err := expand(stage.BaseName)
if err != nil {
return nil, err
}
if !previousStages[strings.ToLower(name)] {
if err = add(name, false); err != nil {
return nil, err
}
}
previousStages[strings.ToLower(stage.Name)] = true
for _, command := range stage.Commands {
if copy, ok := command.(*instructions.CopyCommand); ok && copy.From != "" {
if err = add(copy.From, true); err != nil {
return nil, err
}
}
if run, ok := command.(*instructions.RunCommand); ok {
for _, mount := range instructions.GetMounts(run) {
if mount.From != "" {
if err = add(mount.From, true); err != nil {
return nil, err
}
}
}
}
}
}
return images, nil
}

func discover(input io.Reader, output io.Writer) error {
var request struct {
Directory string `json:"directory"`
Files []string `json:"files"`
}
if err := json.NewDecoder(input).Decode(&request); err != nil {
return err
}
root, err := filepath.Abs(request.Directory)
if err != nil {
return err
}
root, err = filepath.EvalSymlinks(root)
if err != nil {
return err
}
if err = validateComposeSources(root, request.Files); err != nil {
return err
}
options, err := cli.NewProjectOptions(request.Files,
cli.WithWorkingDirectory(request.Directory), cli.WithName("harbor"),
cli.WithOsEnv, cli.WithEnvFiles(), cli.WithDotEnv,
cli.WithoutEnvironmentResolution,
)
if err != nil {
return err
}
project, err := options.LoadProject(context.Background())
if err != nil {
return err
}
seen := map[string]bool{}
for _, service := range project.Services {
if service.Platform != "" && service.Platform != "linux/amd64" {
return fmt.Errorf("service %s requires unsupported platform", service.Name)
}
if service.Build == nil {
ref, err := reference.ParseNormalizedNamed(service.Image)
if err != nil {
return err
}
seen[reference.TagNameOnly(ref).String()] = true
continue
}
build := service.Build
contextPath, err := projectPath(root, build.Context)
if err != nil {
return fmt.Errorf("service %s build context: %w", service.Name, err)
}
build.Context = contextPath
build.Args = build.Args.Resolve(func(key string) (string, bool) {
value, ok := project.Environment[key]
return value, ok
})
for _, platform := range build.Platforms {
if platform != "linux/amd64" {
return fmt.Errorf("service %s requires unsupported build platform", service.Name)
}
}
source := build.DockerfileInline
if source == "" {
name := build.Dockerfile
if name == "" {
name = "Dockerfile"
}
if !filepath.IsAbs(name) {
name = filepath.Join(build.Context, name)
}
name, err = projectPath(root, name)
if err != nil {
return fmt.Errorf("service %s Dockerfile: %w", service.Name, err)
}
data, err := os.ReadFile(name)
if err != nil {
return fmt.Errorf("read Dockerfile for service %s: %w", service.Name, err)
}
source = string(data)
}
images, err := dockerfileImages(source, build)
if err != nil {
return fmt.Errorf("discover bases for service %s: %w", service.Name, err)
}
for _, image := range images {
seen[image] = true
}
}
images := make([]string, 0, len(seen))
for image := range seen {
images = append(images, image)
}
sort.Strings(images)
return json.NewEncoder(output).Encode(map[string]any{"references": images})
}
Loading
Loading