From 2c6d4f259b3efcd09b6db0f6d6b1e2357c1d9f2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20de=20la=20Pe=C3=B1a?= Date: Wed, 18 Nov 2026 16:20:39 +0000 Subject: [PATCH] docs: generate kit capability support reference Co-Authored-By: GPT-6 Sol --- .github/workflows/kit-capabilities.yml | 39 + .github/workflows/sync-kit-capabilities.yml | 89 ++ .../customize/author/capabilities.md | 26 +- data/kit_capabilities.json | 335 +++++ hack/kit-capabilities/.gitignore | 1 + hack/kit-capabilities/README.md | 42 + hack/kit-capabilities/kit.schema.json | 1088 +++++++++++++++++ hack/kit-capabilities/source.json | 34 + hack/kit-capabilities/support.json | 275 +++++ hack/kit-capabilities/sync.py | 197 +++ hack/kit-capabilities/test_sync.py | 95 ++ layouts/_partials/kit-capabilities-table.html | 30 + layouts/_shortcodes/kit-capabilities.html | 1 + .../_shortcodes/kit-capabilities.markdown.md | 1 + 14 files changed, 2230 insertions(+), 23 deletions(-) create mode 100644 .github/workflows/kit-capabilities.yml create mode 100644 .github/workflows/sync-kit-capabilities.yml create mode 100644 data/kit_capabilities.json create mode 100644 hack/kit-capabilities/.gitignore create mode 100644 hack/kit-capabilities/README.md create mode 100644 hack/kit-capabilities/kit.schema.json create mode 100644 hack/kit-capabilities/source.json create mode 100644 hack/kit-capabilities/support.json create mode 100644 hack/kit-capabilities/sync.py create mode 100644 hack/kit-capabilities/test_sync.py create mode 100644 layouts/_partials/kit-capabilities-table.html create mode 100644 layouts/_shortcodes/kit-capabilities.html create mode 100644 layouts/_shortcodes/kit-capabilities.markdown.md diff --git a/.github/workflows/kit-capabilities.yml b/.github/workflows/kit-capabilities.yml new file mode 100644 index 00000000000..797b661c19c --- /dev/null +++ b/.github/workflows/kit-capabilities.yml @@ -0,0 +1,39 @@ +name: Kit capabilities + +on: + pull_request: + paths: + - ".github/workflows/kit-capabilities.yml" + - ".github/workflows/sync-kit-capabilities.yml" + - "hack/kit-capabilities/**" + - "data/kit_capabilities.json" + - "layouts/_shortcodes/kit-capabilities*" + - "layouts/_partials/kit-capabilities*" + - "content/manuals/ai/sandboxes/customize/author/capabilities.md" + push: + branches: + - main + paths: + - ".github/workflows/kit-capabilities.yml" + - ".github/workflows/sync-kit-capabilities.yml" + - "hack/kit-capabilities/**" + - "data/kit_capabilities.json" + - "layouts/_shortcodes/kit-capabilities*" + - "layouts/_partials/kit-capabilities*" + - "content/manuals/ai/sandboxes/customize/author/capabilities.md" + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-24.04 + steps: + - name: Checkout docs + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 + + - name: Run kit capability tests and drift check + run: | + python3 --version + python3 -m unittest discover -s hack/kit-capabilities -p 'test_*.py' + python3 hack/kit-capabilities/sync.py check diff --git a/.github/workflows/sync-kit-capabilities.yml b/.github/workflows/sync-kit-capabilities.yml new file mode 100644 index 00000000000..7f18987672a --- /dev/null +++ b/.github/workflows/sync-kit-capabilities.yml @@ -0,0 +1,89 @@ +name: Sync kit capabilities + +on: + schedule: + # Check upstream weekly; the sync job opens a PR only when the pinned catalog changes. + - cron: "0 9 * * 1" + workflow_dispatch: + inputs: + ref: + description: "Git ref in docker/sandbox-kit-spec to sync (defaults to main)." + type: string + required: false + default: main + +concurrency: + group: sync-kit-capabilities + cancel-in-progress: false + +permissions: + contents: read + +env: + BRANCH_NAME: chore/sync-kit-capabilities + +jobs: + sync: + runs-on: ubuntu-24.04 + permissions: + contents: read + steps: + - id: setup + uses: docker/actions/setup@707e5d98a430d92e8e6c2d34faa5bfb2a9149e9b + with: + app_id: ${{ secrets.HUB_PLATFORM_APP_ID }} + app_private_key: ${{ secrets.HUB_PLATFORM_APP_PRIVATE_KEY }} + + - name: Checkout docs + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 + with: + token: ${{ steps.setup.outputs.token }} + show-progress: false + + - name: Resolve upstream ref to commit SHA + id: resolve + env: + GH_TOKEN: ${{ steps.setup.outputs.token }} + REF: ${{ inputs.ref }} + run: | + set -euo pipefail + ref="${REF:-main}" + sha=$(gh api "repos/docker/sandbox-kit-spec/commits/${ref}" --jq .sha) + if [[ ! "$sha" =~ ^[0-9a-f]{40}$ ]]; then + echo "error: upstream ref did not resolve to a 40-character commit SHA" >&2 + exit 1 + fi + echo "sha=$sha" >> "$GITHUB_OUTPUT" + echo "Syncing docker/sandbox-kit-spec at $sha" + + - name: Sync pinned capability catalog + env: + GH_TOKEN: ${{ steps.setup.outputs.token }} + REF: ${{ steps.resolve.outputs.sha }} + run: | + set -euo pipefail + python3 hack/kit-capabilities/sync.py sync --ref "$REF" + + - name: Test and check generated catalog + run: | + set -euo pipefail + python3 -m unittest discover -s hack/kit-capabilities -p 'test_*.py' + python3 hack/kit-capabilities/sync.py check + + - name: Create or update pull request + uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 + with: + token: ${{ steps.setup.outputs.token }} + title: "docs: sync kit capability catalog" + body: | + Refreshes the pinned capability catalog from `docker/sandbox-kit-spec`. + + The runtime support classifications remain manually maintained and are not changed by this sync. + commit-message: "Sync kit capability catalog" + sign-commits: true + add-paths: | + hack/kit-capabilities/source.json + hack/kit-capabilities/kit.schema.json + data/kit_capabilities.json + branch: ${{ env.BRANCH_NAME }} + delete-branch: true diff --git a/content/manuals/ai/sandboxes/customize/author/capabilities.md b/content/manuals/ai/sandboxes/customize/author/capabilities.md index bf364a21bbd..f2722190b16 100644 --- a/content/manuals/ai/sandboxes/customize/author/capabilities.md +++ b/content/manuals/ai/sandboxes/customize/author/capabilities.md @@ -20,30 +20,10 @@ that Docker Sandboxes applies only part of the capability. Declaration only means that Docker Sandboxes accepts the entry without using its commands. All capability names in the table have the `com.docker.sandbox/` prefix. +Not verified means Docker Sandboxes support has not been confirmed for that +capability. -| Capability | Local sandboxes | Cloud sandboxes | Restrictions | -| --- | --- | --- | --- | -| [`agent-context@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-context@1.md) | v0.45.0 | v0.45.0 | Agent instructions are applied when creating the sandbox. | -| [`agent-context@2`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-context@2.md) | v0.51.0 | Limited: v0.51.0 | Cloud sandboxes write one workload profile in `/home/agent`. Mixins use the workload's profile and cannot specify a `directory`. Unsupported required profiles prevent creation; optional ones are skipped. | -| [`agent-interactive-sessions@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-interactive-sessions@1.md) | Unsupported | Unsupported | Docker Sandboxes does not use these session commands. | -| [`agent-sessions@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-sessions@1.md) | Declaration only | Declaration only | Accepted since v0.45.0, but Docker Sandboxes does not execute the declared session commands. | -| [`agent-skill@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-skill@1.md) | v0.48.0 | Unsupported | Requires a selected `agent-skills@1` destination. Bundled skills remain available with `--skills=off`. | -| [`agent-skills@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-skills@1.md) | v0.45.0 | Unsupported | Local sandboxes mount the shared skills store. From v0.48.0, discovery paths also receive bundled skills. | -| [`credential@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/credential@1.md) | v0.45.0 | Limited: v0.45.0 | In cloud sandboxes, credentials scoped to installation remain available after setup. | -| [`git-identity@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/git-identity@1.md) | v0.48.0 | Unsupported | Requires `user.name` and `user.email` in the host Git config. | -| [`host-mount@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/host-mount@1.md) | v0.50.0 | Unsupported | Users can [select host directories](../use-kits.md#choose-directories-for-kit-host-mounts) at creation time. Cloud sandboxes reject required entries and skip optional ones. | -| [`kit-registry@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/kit-registry@1.md) | v0.45.0 | Unsupported | Restricted to approved OCI builder kits. Local and Git kit sources do not receive registry access. | -| [`lifecycle@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/lifecycle@1.md) | v0.45.0 | v0.45.0 | Local startup hooks run alongside the agent, rather than blocking its launch. | -| [`long-running@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/long-running@1.md) | v0.47.0 | Unsupported | Keeps a local sandbox running after its last session disconnects. | -| [`network-policy@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes keep installation-phase network access after setup. | -| [`network-policy@2`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@2.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes enforce host rules, but not HTTP method or path restrictions. Installation-phase access remains after setup. | -| [`port@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/port@1.md) | v0.45.0 | Limited: v0.45.0 | Cloud sandboxes expose IPv4 TCP ports only. See [Port address families](#port-address-families). | -| [`privileged@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/privileged@1.md) | v0.48.0 | Unsupported | Accepted by the local runtime, which runs Docker-in-Docker containers in privileged mode inside the sandbox VM. | -| [`resources@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/resources@1.md) | Limited: v0.45.0 | Limited: v0.45.0 | Workload CPU and memory defaults are applied. The `gpu` field does not select GPUs; cloud creation rejects a required GPU request. | -| [`sbx@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/sbx@1.md) | v0.45.0 | v0.45.0 | Docker Sandboxes launches the agent using the workload command. | -| [`ssh-agent@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/ssh-agent@1.md) | v0.48.0 | Unsupported | Requires SSH-agent forwarding to be enabled and a host SSH agent to be available. | -| [`usb-device@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/usb-device@1.md) | Unsupported | Unsupported | Kit requests for USB device access are not supported. | -| [`volume@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/volume@1.md) | v0.45.0 | Limited: v0.45.0 | Local sandboxes provide block storage or tmpfs and [retain block volumes across removal and recreation](../use-kits.md#keep-kit-data-when-recreating-a-sandbox). Cloud sandboxes use ordinary sandbox disk at the declared paths, including for tmpfs requests. | +{{< kit-capabilities >}} ## Port address families diff --git a/data/kit_capabilities.json b/data/kit_capabilities.json new file mode 100644 index 00000000000..ae3fed02e50 --- /dev/null +++ b/data/kit_capabilities.json @@ -0,0 +1,335 @@ +{ + "source": { + "repository": "docker/sandbox-kit-spec", + "commit": "16e1610ee26184faa44a6d60c15d3b9e141e824b" + }, + "capabilities": [ + { + "id": "com.docker.sandbox/acp@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/acp@1.md", + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + { + "id": "com.docker.sandbox/agent-context@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/agent-context@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "supported", + "since": "v0.45.0" + }, + "restrictions": "Agent instructions are applied when creating the sandbox." + }, + { + "id": "com.docker.sandbox/agent-context@2", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/agent-context@2.md", + "local": { + "status": "supported", + "since": "v0.51.0" + }, + "cloud": { + "status": "limited", + "since": "v0.51.0" + }, + "restrictions": "Cloud sandboxes write one workload profile in `/home/agent`. Mixins use the workload's profile and cannot specify a `directory`. Unsupported required profiles prevent creation; optional ones are skipped." + }, + { + "id": "com.docker.sandbox/agent-interactive-sessions@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/agent-interactive-sessions@1.md", + "local": { + "status": "unsupported" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Docker Sandboxes does not use these session commands." + }, + { + "id": "com.docker.sandbox/agent-sessions@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/agent-sessions@1.md", + "local": { + "status": "declaration-only", + "since": "v0.45.0" + }, + "cloud": { + "status": "declaration-only", + "since": "v0.45.0" + }, + "restrictions": "Accepted since v0.45.0, but Docker Sandboxes does not execute the declared session commands." + }, + { + "id": "com.docker.sandbox/agent-skill@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/agent-skill@1.md", + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Requires a selected `agent-skills@1` destination. Bundled skills remain available with `--skills=off`." + }, + { + "id": "com.docker.sandbox/agent-skills@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/agent-skills@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Local sandboxes mount the shared skills store. From v0.48.0, discovery paths also receive bundled skills." + }, + { + "id": "com.docker.sandbox/auto-restart@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/auto-restart@1.md", + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + { + "id": "com.docker.sandbox/credential@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/credential@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "In cloud sandboxes, credentials scoped to installation remain available after setup." + }, + { + "id": "com.docker.sandbox/docker-auth@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/docker-auth@1.md", + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + { + "id": "com.docker.sandbox/dockerd@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/dockerd@1.md", + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + { + "id": "com.docker.sandbox/git-identity@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/git-identity@1.md", + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Requires `user.name` and `user.email` in the host Git config." + }, + { + "id": "com.docker.sandbox/host-mount@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/host-mount@1.md", + "local": { + "status": "supported", + "since": "v0.50.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Users can [select host directories](../use-kits.md#choose-directories-for-kit-host-mounts) at creation time. Cloud sandboxes reject required entries and skip optional ones." + }, + { + "id": "com.docker.sandbox/host-port@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/host-port@1.md", + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + { + "id": "com.docker.sandbox/kit-registry@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/kit-registry@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Restricted to approved OCI builder kits. Local and Git kit sources do not receive registry access." + }, + { + "id": "com.docker.sandbox/lifecycle@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/lifecycle@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "supported", + "since": "v0.45.0" + }, + "restrictions": "Local startup hooks run alongside the agent, rather than blocking its launch." + }, + { + "id": "com.docker.sandbox/long-running@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/long-running@1.md", + "local": { + "status": "supported", + "since": "v0.47.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Keeps a local sandbox running after its last session disconnects." + }, + { + "id": "com.docker.sandbox/network-policy@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Cloud sandboxes keep installation-phase network access after setup." + }, + { + "id": "com.docker.sandbox/network-policy@2", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/network-policy@2.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Cloud sandboxes enforce host rules, but not HTTP method or path restrictions. Installation-phase access remains after setup." + }, + { + "id": "com.docker.sandbox/open-url@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/open-url@1.md", + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + { + "id": "com.docker.sandbox/port@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/port@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Cloud sandboxes expose IPv4 TCP ports only. See [Port address families](#port-address-families)." + }, + { + "id": "com.docker.sandbox/privileged@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/privileged@1.md", + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Accepted by the local runtime, which runs Docker-in-Docker containers in privileged mode inside the sandbox VM." + }, + { + "id": "com.docker.sandbox/resources@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/resources@1.md", + "local": { + "status": "limited", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Workload CPU and memory defaults are applied. The `gpu` field does not select GPUs; cloud creation rejects a required GPU request." + }, + { + "id": "com.docker.sandbox/sbx@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/sbx@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "supported", + "since": "v0.45.0" + }, + "restrictions": "Docker Sandboxes launches the agent using the workload command." + }, + { + "id": "com.docker.sandbox/ssh-agent@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/ssh-agent@1.md", + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Requires SSH-agent forwarding to be enabled and a host SSH agent to be available." + }, + { + "id": "com.docker.sandbox/usb-device@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/usb-device@1.md", + "local": { + "status": "unsupported" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Kit requests for USB device access are not supported." + }, + { + "id": "com.docker.sandbox/volume@1", + "url": "https://github.com/docker/sandbox-kit-spec/blob/16e1610ee26184faa44a6d60c15d3b9e141e824b/docs/spec/capabilities/com.docker.sandbox/volume@1.md", + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Local sandboxes provide block storage or tmpfs and [retain block volumes across removal and recreation](../use-kits.md#keep-kit-data-when-recreating-a-sandbox). Cloud sandboxes use ordinary sandbox disk at the declared paths, including for tmpfs requests." + } + ] +} diff --git a/hack/kit-capabilities/.gitignore b/hack/kit-capabilities/.gitignore new file mode 100644 index 00000000000..c18dd8d83ce --- /dev/null +++ b/hack/kit-capabilities/.gitignore @@ -0,0 +1 @@ +__pycache__/ diff --git a/hack/kit-capabilities/README.md b/hack/kit-capabilities/README.md new file mode 100644 index 00000000000..06bc89293b6 --- /dev/null +++ b/hack/kit-capabilities/README.md @@ -0,0 +1,42 @@ +# Kit capability support data + +The [kit capability page](../../content/manuals/ai/sandboxes/customize/author/capabilities.md) +uses two sources: + +- `source.json` pins a public `docker/sandbox-kit-spec` commit and the checksum + of `kit.schema.json`. Its documentation paths identify each capability page + at that commit. The schema defines the capability inventory and config + shapes; it does not state Docker Sandboxes support. +- `support.json` records Docker Sandboxes support for local and cloud sandboxes, + the first `sbx` version where applicable, and the restrictions shown to + readers. These entries need product owner review. `unverified` means the + support status has not been confirmed; it does not mean unsupported. + +`data/kit_capabilities.json` is generated from these files. Hugo renders the +table from that data for both HTML and Markdown output. Builds do not fetch +GitHub content. + +## Update the catalog + +Resolve the public spec branch to a full commit SHA, then run: + +```console +$ python3 hack/kit-capabilities/sync.py sync --ref +``` + +The sync command requires the `gh` CLI to fetch the schema and documentation +tree through the GitHub API. The weekly sync workflow stops if the spec adds a +capability without an explicit `support.json` classification. Add the entry after +confirming its Docker Sandboxes behavior, or classify it as `unverified` until +that review is complete. Sync checks every entry before changing the pinned +files. Review the generated diff and the hand-written sections of the page, +especially settings that require sandbox creation. + +After editing `support.json`, regenerate the data. The check and tests run +offline with Python's standard library: + +```console +$ python3 hack/kit-capabilities/sync.py generate +$ python3 hack/kit-capabilities/sync.py check +$ python3 -m unittest discover -s hack/kit-capabilities -p 'test_*.py' +``` diff --git a/hack/kit-capabilities/kit.schema.json b/hack/kit-capabilities/kit.schema.json new file mode 100644 index 00000000000..34247cedc39 --- /dev/null +++ b/hack/kit-capabilities/kit.schema.json @@ -0,0 +1,1088 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Docker Sandbox Kit descriptor (schemaVersion 3)", + "description": "The declaration half of a kit: capabilities offered and needed, args, hooks, guidance. Published as compact JSON in the vnd.docker.sandbox.kit.descriptor manifest annotation. Mirrors spec/types.go; spec/schema_test.go pins the constants so the two cannot drift silently.", + "type": "object", + "additionalProperties": false, + "required": [ + "schemaVersion", + "kind" + ], + "properties": { + "schemaVersion": { + "const": "3", + "description": "The descriptor grammar version this schema describes." + }, + "displayName": { + "type": "string", + "description": "What humans read; identity lives in the consumption reference." + }, + "author": { + "type": "string", + "description": "Who published the kit, in the org.opencontainers.image.authors convention ('Name ', commas for multiples). Display metadata only: a self-asserted claim, never identity and never a trust input - publisher identity lives in the reference's registry namespace and the signature." + }, + "description": { + "type": "string", + "description": "Short human-readable summary." + }, + "sourceUrl": { + "type": "string", + "description": "The kit's source repository or documentation." + }, + "iconUrl": { + "type": "string", + "format": "uri", + "pattern": "^https://", + "description": "Absolute https URL to an image representing the kit in catalogs and pickers. Display metadata, self-asserted like displayName. https only: a consumer fetches and renders this, so javascript:, data:, and file: are refused." + }, + "version": { + "type": "string", + "description": "Fallback version for unversioned provides entries when the consumption reference carries no version (local directory, git branch). A version-shaped tag always overrides it. May reference a build-phase arg." + }, + "licenses": { + "type": "array", + "items": { + "type": "string" + }, + "description": "SPDX license identifiers." + }, + "kind": { + "enum": [ + "workload", + "mixin", + "set" + ], + "description": "A workload's layers are a root filesystem that may stand at the bottom of the stack; a mixin's are an overlay that must land on one. A set's content is the kits it lists, and the frontend publishes the merged result under the kind they imply - workload when one of them is a workload, mixin when they all are - so 'set' never appears in a published descriptor." + }, + "provides": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Capabilities this kit offers, optionally versioned as name@version. Nothing an author offers is provided implicitly. Bare names normalize into the default namespace (gh IS com.docker.kit/gh, like debian is docker.io/library/debian); third parties qualify under their own namespace, which never matches the bare form. The deb/ and apk/ namespaces are reserved: publishing fills them from the package databases in a workload's content, one entry per installed package, so do not author them." + }, + "requires": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Capabilities the resolved set must satisfy, as \"name\" or \"name version\" with optional comma-AND'd constraints (ops: >=, >, <=, <, =). Unsatisfiable sets are rejected at parse. Bare names normalize into the default namespace; matching is on normalized names against the closed set only, never a registry search." + }, + "integrates": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Capabilities the kit works with when present but functions without, in the requires grammar. An absent provider is fine; a present one that violates the stated constraints still fails resolution. A met entry orders like requires: the provider composes first." + }, + "conflicts": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Capability names that must be absent from the resolved set. Bare names normalize into the default namespace." + }, + "capabilities": { + "type": "array", + "items": { + "$ref": "#/definitions/capabilityItem" + }, + "description": "Typed, versioned capability requests, each answered \u2014 granted, refused, or prompted \u2014 by the host. A host refuses a required type it does not provide by name; an optional one is skipped and recorded. Engine-executed behaviors (lifecycle hooks, agent context with an optional discovery profile directory) live here beside resource grants." + }, + "args": { + "type": "object", + "propertyNames": { + "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" + }, + "additionalProperties": { + "$ref": "#/definitions/arg" + }, + "description": "Installer inputs keyed by arg name. env exports at create, buildArg passes an ordinary build argument, and buildSecret declares a BuildKit session secret whose bytes never enter argument expansion." + }, + "build": { + "type": "string", + "description": "The content recipe inline: literal Dockerfile text, the single-file alternative to the companion .dockerfile (declaring both is an error). Handed to the Dockerfile frontend verbatim." + }, + "dockerfile": { + "type": "string", + "description": "Names the companion recipe explicitly, relative to the descriptor's directory. Optional sugar over the filename-stem convention; a named recipe that does not exist is an error, unlike the conventional companion whose absence means a declaration-only kit. Mutually exclusive with build." + }, + "kits": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/definitions/kit" + }, + "description": "This kit's content as a list of published kits rather than Dockerfile text: the fourth authoring form. Mutually exclusive with build and dockerfile. The frontend resolves every one of them, judges them as a set, merges their layers and declarations, and publishes one ordinary kit; the published descriptor retains this list with every entry pinned by digest." + } + }, + "allOf": [ + { + "if": { + "properties": { + "kind": { + "const": "set" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "required": [ + "kits" + ] + } + }, + { + "if": { + "required": [ + "kits" + ] + }, + "then": { + "not": { + "anyOf": [ + { + "required": [ + "build" + ] + }, + { + "required": [ + "dockerfile" + ] + } + ] + }, + "properties": { + "args": { + "additionalProperties": { + "not": { + "required": [ + "buildSecret" + ] + } + } + } + } + } + }, + { + "if": { + "properties": { + "kind": { + "const": "mixin" + } + }, + "required": [ + "kind" + ] + }, + "then": { + "properties": { + "capabilities": { + "items": { + "properties": { + "type": { + "not": { + "const": "com.docker.sandbox/sbx@1" + } + }, + "group": { + "properties": { + "capabilities": { + "items": { + "properties": { + "type": { + "not": { + "const": "com.docker.sandbox/sbx@1" + } + } + } + } + } + } + } + } + } + } + } + }, + "description": "com.docker.sandbox/sbx@1 is workload-only: a mixin's image config never becomes the composed image's, so the identity it would promise is not the one a host reads." + }, + { + "$ref": "#/definitions/noNul" + } + ], + "definitions": { + "noNul": { + "description": "No string anywhere in the descriptor, key or value, holds NUL (U+0000). Applied once at the root and recursively, so it covers every field, including the config of capability types this schema does not know.", + "not": { + "type": "string", + "pattern": "\u0000" + }, + "propertyNames": { + "not": { + "pattern": "\u0000" + } + }, + "additionalProperties": { + "$ref": "#/definitions/noNul" + }, + "items": { + "$ref": "#/definitions/noNul" + } + }, + "kit": { + "type": "object", + "additionalProperties": false, + "required": [ + "ref" + ], + "properties": { + "ref": { + "type": "string", + "pattern": "^(\\$\\{\\{\\s*kit\\.args\\.[A-Za-z_][A-Za-z0-9_]*\\s*\\}\\}|[^\\s./])(\\$\\{\\{\\s*kit\\.args\\.[A-Za-z_][A-Za-z0-9_]*\\s*\\}\\}|[^\\s])*$", + "not": { + "anyOf": [ + { + "pattern": "^git\\+" + }, + { + "pattern": "://" + } + ] + }, + "description": "The registry reference this kit is consumed by, and the identity it is named by in every merge diagnostic. A local path or a git URL names a kit that may not be published, and a set's kits have to be resolvable from the manifest alone." + }, + "digest": { + "type": "string", + "pattern": "^sha256:[0-9a-f]{64}$", + "description": "Pins this kit's manifest. Optional when authored - a tag is how an author names a version - and required in the published form, which the frontend fills in from the reference it resolved." + }, + "args": { + "type": "object", + "propertyNames": { + "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" + }, + "additionalProperties": { + "type": "string" + }, + "description": "This kit's create-phase args, keyed by its own arg names. A literal value is expanded into the merged descriptor at publish, which is what pins the set. A value that is itself a ${{ kit.args.* }} reference re-exports the input under the set's name, where the set's own declaration bounds it." + } + } + }, + "capability": { + "type": "object", + "additionalProperties": false, + "required": [ + "type" + ], + "properties": { + "type": { + "type": "string", + "pattern": "^[a-z0-9]([a-z0-9.-]*[a-z0-9])?/[a-z0-9]([a-z0-9-]*[a-z0-9])?@[1-9][0-9]*$", + "description": "/@. The namespace admits host-specific capability types. The version covers the config schema and observable behavior, including composition and persistent-state transitions. RELEASES.md defines when versions move and the maintainer-approved draft-stage exception." + }, + "name": { + "type": "string", + "description": "Optional human-readable display label. Spaces and duplicate names are allowed; the label does not change identity, merging, or permissions." + }, + "optional": { + "type": "boolean", + "description": "An unknown or unprovided optional need is skipped and recorded; a required one fails resolution closed. For credentials this subsumes the older per-credential required flag." + }, + "config": { + "type": "object", + "description": "Type-specific request payload. Well-known types decode strictly; unknown types carry it opaquely. Part of the permission surface: config changes gate like any widening. String values may reference ${{ kit.env.NAME }} from the final container environment, expanded before selection and validation. Keys are not environment-expanded." + }, + "description": { + "type": "string", + "description": "Shown wherever the request is listed or prompted." + }, + "source": { + "$ref": "#/definitions/capabilitySource" + }, + "declarationBlocks": { + "$ref": "#/definitions/declarationBlocks" + } + }, + "allOf": [ + { + "if": { + "properties": {"type": {"const": "com.docker.sandbox/docker-auth@1"}}, + "required": ["type"] + }, + "then": { + "required": ["config"], + "properties": {"config": {"$ref": "capabilities/com.docker.sandbox/docker-auth@1.schema.json"}} + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/network-policy@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/network-policy@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/network-policy@2" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/network-policy@2.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/credential@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/credential@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/ssh-agent@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/ssh-agent@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/agent-skills@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/agent-skills@1.schema.json" + } + }, + "required": [ + "config" + ] + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/volume@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/volume@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/host-mount@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/host-mount@1.schema.json" + } + }, + "required": [ + "config" + ] + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/host-port@1" + } + }, + "required": ["type"] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/host-port@1.schema.json" + } + }, + "required": ["config"] + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/port@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/port@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/usb-device@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/usb-device@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/resources@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/resources@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/privileged@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/privileged@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/dockerd@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/dockerd@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/sbx@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/sbx@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/kit-registry@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/kit-registry@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/acp@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "required": [ + "config" + ], + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/acp@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/agent-sessions@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/agent-sessions@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/agent-interactive-sessions@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "required": [ + "config" + ], + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/agent-interactive-sessions@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/lifecycle@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/lifecycle@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/agent-context@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/agent-context@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/agent-context@2" + } + }, + "required": [ + "type" + ] + }, + "then": { + "required": [ + "config" + ], + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/agent-context@2.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/open-url@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/open-url@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/long-running@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/long-running@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/auto-restart@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/auto-restart@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/git-identity@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/git-identity@1.schema.json" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "com.docker.sandbox/agent-skill@1" + } + }, + "required": [ + "type" + ] + }, + "then": { + "required": [ + "config" + ], + "properties": { + "config": { + "$ref": "capabilities/com.docker.sandbox/agent-skill@1.schema.json" + } + } + } + } + ] + }, + "arg": { + "type": "object", + "additionalProperties": false, + "properties": { + "default": { + "type": "string", + "description": "Substituted when the caller supplies nothing." + }, + "required": { + "type": "boolean", + "description": "The caller must supply a value. Mutually exclusive with default." + }, + "description": { + "type": "string" + }, + "enum": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Exact allowed values. Exclusive with pattern." + }, + "pattern": { + "type": "string", + "description": "RE2 regexp matched against the whole value. Exclusive with enum." + }, + "env": { + "type": "string", + "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", + "description": "Opts the resolved value into the container environment under this name." + }, + "buildArg": { + "type": "string", + "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", + "description": "Resolves the arg at build instead: validated by the frontend, handed to the dockerfile under this build-arg name, expanded into the published descriptor." + }, + "buildSecret": { + "type": "string", + "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", + "description": "BuildKit session secret ID. Never expanded or passed as a build argument or runtime input. The recipe uses RUN --mount=type=secret,id=,required=true to require it." + } + }, + "allOf": [ + { + "not": { + "required": [ + "env", + "buildArg" + ] + } + }, + { + "not": { + "required": [ + "enum", + "pattern" + ] + } + }, + { + "not": { + "allOf": [ + { + "required": [ + "default" + ] + }, + { + "properties": { + "required": { + "const": true + } + }, + "required": [ + "required" + ] + } + ] + } + }, + { + "if": { + "required": [ + "buildSecret" + ] + }, + "then": { + "not": { + "anyOf": [ + { + "required": [ + "env" + ] + }, + { + "required": [ + "buildArg" + ] + }, + { + "required": [ + "default" + ] + }, + { + "required": [ + "enum" + ] + }, + { + "required": [ + "pattern" + ] + }, + { + "required": [ + "required" + ], + "properties": { + "required": { + "const": true + } + } + } + ] + } + } + } + ] + }, + "capabilitySource": { + "type": "object", + "additionalProperties": false, + "required": [ + "path" + ], + "properties": { + "kit": { + "type": "string" + }, + "path": { + "type": "string", + "minLength": 1 + } + } + }, + "capabilityMember": { + "allOf": [ + { + "$ref": "#/definitions/capability" + }, + { + "not": { + "required": [ + "optional" + ] + } + }, + { + "not": { + "required": [ + "declarationBlocks" + ] + } + } + ] + }, + "capabilityGroup": { + "type": "object", + "additionalProperties": false, + "required": [ + "capabilities" + ], + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "optional": { + "type": "boolean", + "default": false + }, + "capabilities": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/definitions/capabilityMember" + } + } + } + }, + "capabilityItem": { + "oneOf": [ + { + "$ref": "#/definitions/capability" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "group" + ], + "properties": { + "group": { + "$ref": "#/definitions/capabilityGroup" + }, + "source": { + "$ref": "#/definitions/capabilitySource" + }, + "declarationBlocks": { + "$ref": "#/definitions/declarationBlocks" + } + }, + "allOf": [ + { + "if": { + "required": [ + "declarationBlocks" + ], + "properties": { + "declarationBlocks": { + "minItems": 1 + } + } + }, + "then": { + "properties": { + "group": { + "properties": { + "capabilities": { + "maxItems": 1 + } + } + } + } + } + } + ] + } + ] + }, + "declarationBlocks": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "minLength": 1 + }, + "description": "Descriptor-local declaration block IDs for duplicate validation before selection. Shared IDs retain the original ordinary block across independently selected one-member groups. Reconciled concrete requests retain every contributing ID. These IDs are structural constraints, not source attribution or trust inputs." + } + } +} diff --git a/hack/kit-capabilities/source.json b/hack/kit-capabilities/source.json new file mode 100644 index 00000000000..9dd46df1f59 --- /dev/null +++ b/hack/kit-capabilities/source.json @@ -0,0 +1,34 @@ +{ + "repository": "docker/sandbox-kit-spec", + "commit": "16e1610ee26184faa44a6d60c15d3b9e141e824b", + "schema_sha256": "a099ae501c6703b2bb7b5d8df7605748f0de164a2d466b4ddb44dd6fd17af3c9", + "documentation": [ + "docs/spec/capabilities/com.docker.sandbox/acp@1.md", + "docs/spec/capabilities/com.docker.sandbox/agent-context@1.md", + "docs/spec/capabilities/com.docker.sandbox/agent-context@2.md", + "docs/spec/capabilities/com.docker.sandbox/agent-interactive-sessions@1.md", + "docs/spec/capabilities/com.docker.sandbox/agent-sessions@1.md", + "docs/spec/capabilities/com.docker.sandbox/agent-skill@1.md", + "docs/spec/capabilities/com.docker.sandbox/agent-skills@1.md", + "docs/spec/capabilities/com.docker.sandbox/auto-restart@1.md", + "docs/spec/capabilities/com.docker.sandbox/credential@1.md", + "docs/spec/capabilities/com.docker.sandbox/docker-auth@1.md", + "docs/spec/capabilities/com.docker.sandbox/dockerd@1.md", + "docs/spec/capabilities/com.docker.sandbox/git-identity@1.md", + "docs/spec/capabilities/com.docker.sandbox/host-mount@1.md", + "docs/spec/capabilities/com.docker.sandbox/host-port@1.md", + "docs/spec/capabilities/com.docker.sandbox/kit-registry@1.md", + "docs/spec/capabilities/com.docker.sandbox/lifecycle@1.md", + "docs/spec/capabilities/com.docker.sandbox/long-running@1.md", + "docs/spec/capabilities/com.docker.sandbox/network-policy@1.md", + "docs/spec/capabilities/com.docker.sandbox/network-policy@2.md", + "docs/spec/capabilities/com.docker.sandbox/open-url@1.md", + "docs/spec/capabilities/com.docker.sandbox/port@1.md", + "docs/spec/capabilities/com.docker.sandbox/privileged@1.md", + "docs/spec/capabilities/com.docker.sandbox/resources@1.md", + "docs/spec/capabilities/com.docker.sandbox/sbx@1.md", + "docs/spec/capabilities/com.docker.sandbox/ssh-agent@1.md", + "docs/spec/capabilities/com.docker.sandbox/usb-device@1.md", + "docs/spec/capabilities/com.docker.sandbox/volume@1.md" + ] +} diff --git a/hack/kit-capabilities/support.json b/hack/kit-capabilities/support.json new file mode 100644 index 00000000000..6b6e88a0dc7 --- /dev/null +++ b/hack/kit-capabilities/support.json @@ -0,0 +1,275 @@ +{ + "com.docker.sandbox/acp@1": { + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + "com.docker.sandbox/agent-context@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "supported", + "since": "v0.45.0" + }, + "restrictions": "Agent instructions are applied when creating the sandbox." + }, + "com.docker.sandbox/agent-context@2": { + "local": { + "status": "supported", + "since": "v0.51.0" + }, + "cloud": { + "status": "limited", + "since": "v0.51.0" + }, + "restrictions": "Cloud sandboxes write one workload profile in `/home/agent`. Mixins use the workload's profile and cannot specify a `directory`. Unsupported required profiles prevent creation; optional ones are skipped." + }, + "com.docker.sandbox/agent-interactive-sessions@1": { + "local": { + "status": "unsupported" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Docker Sandboxes does not use these session commands." + }, + "com.docker.sandbox/agent-sessions@1": { + "local": { + "status": "declaration-only", + "since": "v0.45.0" + }, + "cloud": { + "status": "declaration-only", + "since": "v0.45.0" + }, + "restrictions": "Accepted since v0.45.0, but Docker Sandboxes does not execute the declared session commands." + }, + "com.docker.sandbox/agent-skill@1": { + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Requires a selected `agent-skills@1` destination. Bundled skills remain available with `--skills=off`." + }, + "com.docker.sandbox/agent-skills@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Local sandboxes mount the shared skills store. From v0.48.0, discovery paths also receive bundled skills." + }, + "com.docker.sandbox/auto-restart@1": { + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + "com.docker.sandbox/credential@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "In cloud sandboxes, credentials scoped to installation remain available after setup." + }, + "com.docker.sandbox/docker-auth@1": { + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + "com.docker.sandbox/dockerd@1": { + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + "com.docker.sandbox/git-identity@1": { + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Requires `user.name` and `user.email` in the host Git config." + }, + "com.docker.sandbox/host-mount@1": { + "local": { + "status": "supported", + "since": "v0.50.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Users can [select host directories](../use-kits.md#choose-directories-for-kit-host-mounts) at creation time. Cloud sandboxes reject required entries and skip optional ones." + }, + "com.docker.sandbox/host-port@1": { + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + "com.docker.sandbox/kit-registry@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Restricted to approved OCI builder kits. Local and Git kit sources do not receive registry access." + }, + "com.docker.sandbox/lifecycle@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "supported", + "since": "v0.45.0" + }, + "restrictions": "Local startup hooks run alongside the agent, rather than blocking its launch." + }, + "com.docker.sandbox/long-running@1": { + "local": { + "status": "supported", + "since": "v0.47.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Keeps a local sandbox running after its last session disconnects." + }, + "com.docker.sandbox/network-policy@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Cloud sandboxes keep installation-phase network access after setup." + }, + "com.docker.sandbox/network-policy@2": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Cloud sandboxes enforce host rules, but not HTTP method or path restrictions. Installation-phase access remains after setup." + }, + "com.docker.sandbox/open-url@1": { + "local": { + "status": "unverified" + }, + "cloud": { + "status": "unverified" + }, + "restrictions": "Docker Sandboxes support has not been verified." + }, + "com.docker.sandbox/port@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Cloud sandboxes expose IPv4 TCP ports only. See [Port address families](#port-address-families)." + }, + "com.docker.sandbox/privileged@1": { + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Accepted by the local runtime, which runs Docker-in-Docker containers in privileged mode inside the sandbox VM." + }, + "com.docker.sandbox/resources@1": { + "local": { + "status": "limited", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Workload CPU and memory defaults are applied. The `gpu` field does not select GPUs; cloud creation rejects a required GPU request." + }, + "com.docker.sandbox/sbx@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "supported", + "since": "v0.45.0" + }, + "restrictions": "Docker Sandboxes launches the agent using the workload command." + }, + "com.docker.sandbox/ssh-agent@1": { + "local": { + "status": "supported", + "since": "v0.48.0" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Requires SSH-agent forwarding to be enabled and a host SSH agent to be available." + }, + "com.docker.sandbox/usb-device@1": { + "local": { + "status": "unsupported" + }, + "cloud": { + "status": "unsupported" + }, + "restrictions": "Kit requests for USB device access are not supported." + }, + "com.docker.sandbox/volume@1": { + "local": { + "status": "supported", + "since": "v0.45.0" + }, + "cloud": { + "status": "limited", + "since": "v0.45.0" + }, + "restrictions": "Local sandboxes provide block storage or tmpfs and [retain block volumes across removal and recreation](../use-kits.md#keep-kit-data-when-recreating-a-sandbox). Cloud sandboxes use ordinary sandbox disk at the declared paths, including for tmpfs requests." + } +} diff --git a/hack/kit-capabilities/sync.py b/hack/kit-capabilities/sync.py new file mode 100644 index 00000000000..64f65f56b29 --- /dev/null +++ b/hack/kit-capabilities/sync.py @@ -0,0 +1,197 @@ +#!/usr/bin/env python3 +"""Build the Docker Sandboxes capability table from a pinned public catalog.""" + +import argparse +import base64 +import hashlib +import json +import re +import subprocess +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +DIR = Path(__file__).resolve().parent +SOURCE = DIR / "source.json" +SCHEMA = DIR / "kit.schema.json" +SUPPORT = DIR / "support.json" +OUTPUT = ROOT / "data/kit_capabilities.json" +REPOSITORY = "docker/sandbox-kit-spec" +TYPE = re.compile(r"^com\.docker\.sandbox/[a-z0-9][a-z0-9-]*@[1-9][0-9]*$") +COMMIT = re.compile(r"^[0-9a-f]{40}$") +VERSION = re.compile(r"^v[0-9]+\.[0-9]+\.[0-9]+$") +STATUSES = {"supported", "limited", "declaration-only", "unsupported", "unverified"} +DOC_PREFIX = "docs/spec/capabilities/" + + +class CatalogError(ValueError): + pass + + +def read_json(path): + try: + return json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as error: + raise CatalogError(f"{path}: {error}") from error + + +def json_bytes(value): + return (json.dumps(value, indent=2, ensure_ascii=False) + "\n").encode() + + +def inventory(schema_bytes, documentation): + try: + schema = json.loads(schema_bytes) + branches = schema["definitions"]["capability"]["allOf"] + except (ValueError, KeyError, TypeError) as error: + raise CatalogError(f"invalid capability schema: {error}") from error + + found = {} + for branch in branches: + try: + identifier = branch["if"]["properties"]["type"]["const"] + reference = branch["then"]["properties"]["config"]["$ref"] + except (KeyError, TypeError) as error: + raise CatalogError(f"invalid capability branch: {error}") from error + if not isinstance(identifier, str) or not TYPE.fullmatch(identifier): + raise CatalogError(f"invalid capability ID: {identifier!r}") + if identifier in found: + raise CatalogError(f"duplicate capability ID: {identifier}") + expected = f"capabilities/{identifier}.schema.json" + if reference != expected: + raise CatalogError(f"{identifier}: expected schema reference {expected}, got {reference}") + found[identifier] = f"{DOC_PREFIX}{identifier}.md" + + if not found: + raise CatalogError("schema has no capability types") + if not isinstance(documentation, list) or documentation != sorted(set(documentation)): + raise CatalogError("documentation paths must be a sorted list without duplicates") + expected_docs = set(found.values()) + actual_docs = set(documentation) + if expected_docs != actual_docs: + raise CatalogError( + "spec documentation mismatch: missing " + str(sorted(expected_docs - actual_docs)) + + "; extra " + str(sorted(actual_docs - expected_docs)) + ) + return found + + +def validate_support(support, identifiers): + if not isinstance(support, dict): + raise CatalogError("support.json must be an object") + missing = sorted(identifiers - support.keys()) + extra = sorted(support.keys() - identifiers) + if missing or extra: + raise CatalogError(f"support.json classifications: missing {missing}; extra {extra}") + for identifier, entry in support.items(): + if not isinstance(entry, dict) or set(entry) != {"local", "cloud", "restrictions"}: + raise CatalogError(f"{identifier}: expected local, cloud, and restrictions") + restrictions = entry["restrictions"] + if not isinstance(restrictions, str) or not restrictions.strip(): + raise CatalogError(f"{identifier}: restrictions must be nonempty text") + if any(character in restrictions for character in "|\r\n"): + raise CatalogError(f"{identifier}: restrictions must fit in one Markdown table cell") + for environment in ("local", "cloud"): + value = entry[environment] + if not isinstance(value, dict) or value.get("status") not in STATUSES: + raise CatalogError(f"{identifier} {environment}: invalid status") + status = value["status"] + expected_keys = {"status", "since"} if status in {"supported", "limited", "declaration-only"} else {"status"} + if set(value) != expected_keys: + raise CatalogError(f"{identifier} {environment}: expected {sorted(expected_keys)}") + if "since" in value and (not isinstance(value["since"], str) or not VERSION.fullmatch(value["since"])): + raise CatalogError(f"{identifier} {environment}: invalid sbx version") + + +def make_data(schema_bytes, source, support): + if not isinstance(source, dict) or set(source) != {"repository", "commit", "schema_sha256", "documentation"}: + raise CatalogError("source.json has unexpected fields") + if source["repository"] != REPOSITORY or not isinstance(source["commit"], str) or not COMMIT.fullmatch(source["commit"]): + raise CatalogError("source.json must pin docker/sandbox-kit-spec at a 40-character commit SHA") + checksum = hashlib.sha256(schema_bytes).hexdigest() + if source["schema_sha256"] != checksum: + raise CatalogError(f"schema checksum mismatch: expected {source['schema_sha256']}, got {checksum}") + docs = inventory(schema_bytes, source["documentation"]) + validate_support(support, set(docs)) + return { + "source": {"repository": REPOSITORY, "commit": source["commit"]}, + "capabilities": [ + { + "id": identifier, + "url": f"https://github.com/{REPOSITORY}/blob/{source['commit']}/{docs[identifier]}", + **support[identifier], + } + for identifier in sorted(docs) + ], + } + + +def github_api(path): + try: + return json.loads(subprocess.check_output(["gh", "api", f"repos/{REPOSITORY}/{path}"], text=True)) + except (OSError, subprocess.CalledProcessError, json.JSONDecodeError) as error: + raise CatalogError(f"GitHub API request failed for {path}: {error}") from error + + +def sync(commit, support): + if not COMMIT.fullmatch(commit): + raise CatalogError("--ref must be an immutable 40-character lowercase commit SHA") + content = github_api(f"contents/schema/kit.schema.json?ref={commit}") + if content.get("encoding") != "base64": + raise CatalogError("GitHub API did not return base64 schema content") + try: + schema_bytes = base64.b64decode(content["content"].replace("\n", ""), validate=True) + except (KeyError, ValueError) as error: + raise CatalogError(f"invalid GitHub schema content: {error}") from error + tree = github_api(f"git/trees/{commit}?recursive=1") + if tree.get("truncated"): + raise CatalogError("GitHub tree response was truncated") + documentation = sorted( + node["path"] for node in tree["tree"] + if node["type"] == "blob" + and node["path"].startswith(DOC_PREFIX + "com.docker.sandbox/") + and node["path"].endswith(".md") + ) + source = { + "repository": REPOSITORY, + "commit": commit, + "schema_sha256": hashlib.sha256(schema_bytes).hexdigest(), + "documentation": documentation, + } + data = make_data(schema_bytes, source, support) + # Validate every file and every classification before changing the checkout. + SCHEMA.write_bytes(schema_bytes) + SOURCE.write_bytes(json_bytes(source)) + OUTPUT.write_bytes(json_bytes(data)) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + commands = parser.add_subparsers(dest="command", required=True) + commands.add_parser("check") + commands.add_parser("generate") + sync_parser = commands.add_parser("sync") + sync_parser.add_argument("--ref", required=True, help="full public spec commit SHA") + args = parser.parse_args() + try: + support = read_json(SUPPORT) + if args.command == "sync": + sync(args.ref, support) + else: + source = read_json(SOURCE) + try: + schema_bytes = SCHEMA.read_bytes() + except OSError as error: + raise CatalogError(f"{SCHEMA}: {error}") from error + expected = json_bytes(make_data(schema_bytes, source, support)) + if args.command == "generate": + OUTPUT.write_bytes(expected) + elif not OUTPUT.exists() or OUTPUT.read_bytes() != expected: + raise CatalogError(f"{OUTPUT}: missing or stale; run python3 hack/kit-capabilities/sync.py generate") + except CatalogError as error: + parser.exit(1, f"{error}\n") + + +if __name__ == "__main__": + main() diff --git a/hack/kit-capabilities/test_sync.py b/hack/kit-capabilities/test_sync.py new file mode 100644 index 00000000000..fb33e4a8de8 --- /dev/null +++ b/hack/kit-capabilities/test_sync.py @@ -0,0 +1,95 @@ +"""Failure cases for the pinned capability catalog and support metadata.""" + +import copy +import importlib.util +import json +import tempfile +import unittest +from pathlib import Path +from unittest.mock import patch + + +MODULE_PATH = Path(__file__).with_name("sync.py") +SPEC = importlib.util.spec_from_file_location("kit_capability_sync", MODULE_PATH) +sync = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(sync) + + +class CatalogTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.schema_bytes = sync.SCHEMA.read_bytes() + cls.source = sync.read_json(sync.SOURCE) + cls.support = sync.read_json(sync.SUPPORT) + + def test_generated_data_preserves_classified_support(self): + data = sync.make_data(self.schema_bytes, self.source, self.support) + self.assertEqual(json.loads(sync.OUTPUT.read_bytes()), data) + by_id = {entry["id"]: entry for entry in data["capabilities"]} + self.assertEqual(set(by_id), set(self.support)) + self.assertEqual(by_id["com.docker.sandbox/agent-context@2"]["cloud"], + {"status": "limited", "since": "v0.51.0"}) + self.assertEqual(by_id["com.docker.sandbox/agent-sessions@1"]["local"], + {"status": "declaration-only", "since": "v0.45.0"}) + self.assertEqual(by_id["com.docker.sandbox/host-port@1"]["local"], + {"status": "unverified"}) + + def test_new_spec_type_requires_explicit_classification(self): + schema = json.loads(self.schema_bytes) + branch = copy.deepcopy(schema["definitions"]["capability"]["allOf"][0]) + identifier = "com.docker.sandbox/future@1" + branch["if"]["properties"]["type"]["const"] = identifier + branch["then"]["properties"]["config"]["$ref"] = f"capabilities/{identifier}.schema.json" + schema["definitions"]["capability"]["allOf"].append(branch) + source = copy.deepcopy(self.source) + source["documentation"].append(f"docs/spec/capabilities/{identifier}.md") + source["documentation"].sort() + source["schema_sha256"] = sync.hashlib.sha256(sync.json_bytes(schema)).hexdigest() + with self.assertRaisesRegex(sync.CatalogError, "future@1"): + sync.make_data(sync.json_bytes(schema), source, self.support) + support = copy.deepcopy(self.support) + support[identifier] = { + "local": {"status": "unverified"}, + "cloud": {"status": "unverified"}, + "restrictions": "Docker Sandboxes support has not been verified.", + } + data = sync.make_data(sync.json_bytes(schema), source, support) + self.assertIn(identifier, {entry["id"] for entry in data["capabilities"]}) + + def test_rejects_missing_docs_and_duplicate_type(self): + docs = self.source["documentation"][1:] + with self.assertRaisesRegex(sync.CatalogError, "spec documentation mismatch"): + sync.inventory(self.schema_bytes, docs) + schema = json.loads(self.schema_bytes) + schema["definitions"]["capability"]["allOf"].append( + copy.deepcopy(schema["definitions"]["capability"]["allOf"][0])) + with self.assertRaisesRegex(sync.CatalogError, "duplicate capability ID"): + sync.inventory(sync.json_bytes(schema), self.source["documentation"]) + + def test_rejects_integrity_and_invalid_status_metadata(self): + with self.assertRaisesRegex(sync.CatalogError, "checksum mismatch"): + sync.make_data(self.schema_bytes + b" ", self.source, self.support) + support = copy.deepcopy(self.support) + support["com.docker.sandbox/port@1"]["cloud"]["status"] = "maybe" + with self.assertRaisesRegex(sync.CatalogError, "invalid status"): + sync.make_data(self.schema_bytes, self.source, support) + support = copy.deepcopy(self.support) + support["com.docker.sandbox/port@1"]["cloud"]["since"] = "v3.0" + with self.assertRaisesRegex(sync.CatalogError, "invalid sbx version"): + sync.make_data(self.schema_bytes, self.source, support) + support = copy.deepcopy(self.support) + support["com.docker.sandbox/port@1"]["restrictions"] = "first | second" + with self.assertRaisesRegex(sync.CatalogError, "one Markdown table cell"): + sync.make_data(self.schema_bytes, self.source, support) + + def test_check_rejects_stale_output(self): + with tempfile.TemporaryDirectory() as directory: + output = Path(directory) / "kit_capabilities.json" + output.write_text("{}\n") + with patch.object(sync, "OUTPUT", output), patch.object(sync.sys, "argv", ["sync.py", "check"]): + with self.assertRaisesRegex(SystemExit, "1"): + sync.main() + + +if __name__ == "__main__": + unittest.main() diff --git a/layouts/_partials/kit-capabilities-table.html b/layouts/_partials/kit-capabilities-table.html new file mode 100644 index 00000000000..39547f4d74d --- /dev/null +++ b/layouts/_partials/kit-capabilities-table.html @@ -0,0 +1,30 @@ +{{- $data := hugo.Data.kit_capabilities -}} +{{- if not $data.capabilities -}} + {{- errorf "kit capability data is missing or empty; run python3 hack/kit-capabilities/sync.py generate" -}} +{{- end -}} +{{- $rows := slice "| Capability | Local sandboxes | Cloud sandboxes | Restrictions |" "| --- | --- | --- | --- |" -}} +{{- range $data.capabilities -}} + {{- $local := "Not verified" -}} + {{- if eq .local.status "supported" -}} + {{- $local = .local.since -}} + {{- else if eq .local.status "limited" -}} + {{- $local = printf "Limited: %s" .local.since -}} + {{- else if eq .local.status "declaration-only" -}} + {{- $local = "Declaration only" -}} + {{- else if eq .local.status "unsupported" -}} + {{- $local = "Unsupported" -}} + {{- end -}} + {{- $cloud := "Not verified" -}} + {{- if eq .cloud.status "supported" -}} + {{- $cloud = .cloud.since -}} + {{- else if eq .cloud.status "limited" -}} + {{- $cloud = printf "Limited: %s" .cloud.since -}} + {{- else if eq .cloud.status "declaration-only" -}} + {{- $cloud = "Declaration only" -}} + {{- else if eq .cloud.status "unsupported" -}} + {{- $cloud = "Unsupported" -}} + {{- end -}} + {{- $name := strings.TrimPrefix "com.docker.sandbox/" .id -}} + {{- $rows = $rows | append (printf "| [`%s`](%s) | %s | %s | %s |" $name .url $local $cloud .restrictions) -}} +{{- end -}} +{{- return (delimit $rows "\n") -}} diff --git a/layouts/_shortcodes/kit-capabilities.html b/layouts/_shortcodes/kit-capabilities.html new file mode 100644 index 00000000000..761d9550ff0 --- /dev/null +++ b/layouts/_shortcodes/kit-capabilities.html @@ -0,0 +1 @@ +{{- partial "kit-capabilities-table.html" . | .Page.RenderString (dict "display" "block") -}} diff --git a/layouts/_shortcodes/kit-capabilities.markdown.md b/layouts/_shortcodes/kit-capabilities.markdown.md new file mode 100644 index 00000000000..7aa03484999 --- /dev/null +++ b/layouts/_shortcodes/kit-capabilities.markdown.md @@ -0,0 +1 @@ +{{ partial "kit-capabilities-table.html" . }}