sbx: restructure governance docs and add API reference#25162
Draft
dvdksn wants to merge 11 commits into
Draft
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR restructures sandbox governance docs into a clean multi-page hierarchy and adds an OpenAPI-rendered API reference page. The redirect aliases on local.md and org.md correctly cover the old security/policy and security/governance URLs. Two issues found in the newly added content.
Contributor
Author
|
Endpoints will get a new shape, waiting on the new OAS reflecting this to land. |
dvdksn
force-pushed
the
sbx/governance-docs
branch
from
5d453f3 to
32c124d
Compare
github-actions
Bot
added
area/engine
The "Data source Discovery" heading in `content/guides/grafana-mcp-server-gemini.md` has two spaces after the `###`, which trips markdownlint (MD019). Since the lint job runs over the whole `content/**/*.md` tree, this currently fails CI on every open PR. This removes the extra space.
Splits the existing security/governance and security/policy pages into a new governance section with concepts, local, organization, monitoring, and API reference sub-pages, and adds a custom api-reference Hugo layout that renders the colocated OpenAPI 3 spec directly from the spec file. The layout reads the spec via transform.Unmarshal, resolves $ref nodes through a small returning partial, and overrides baseof's main block to take the full content width. The built-in right-rail TOC is replaced with a sticky endpoint navigator that groups operations by tag with method-colored pills. Each operation card shows method/path, summary, description, parameters, request body, and responses. Responses use native <details> elements so the list of status codes stays scannable; 2xx defaults to open. JSON examples are wrapped in the site's syntax-light/dark utility so Chroma classes pick up the theme. Each operation also exposes a copy-as-cURL button that assembles a ready-to-paste command from the spec's path and query parameter examples, the bearer-auth scheme (with $TOKEN as a literal placeholder), and the request body's default JSON example. A companion api-reference.markdown.md template renders the same spec as a clean markdown document so the page's "Copy Markdown" / "View Markdown" actions and the .md alternate link return real content instead of just the page title. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Relocates the OpenAPI reference page bundle out of the product manual tree and into the canonical /reference/api/ section. The old URL keeps working via a Hugo alias on the new page. Under /ai/sandboxes/governance the sidebar still shows an "API reference" entry: a non-rendered stub page (build.render: never) with sidebar.goto pointing at the new location, so the link in the governance sidebar cross-references the reference section directly without bouncing through a placeholder page. The duplicate static/manuals/ai/sandboxes/governance/api.yaml is dropped now that the page resource is the single source of the spec. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The sidebar stub at content/manuals/ai/sandboxes/governance/api.md has build.render: never, so relative (api.md) links from sibling files resolved to an empty href once the bundle moved to the reference section. Updates org.md, local.md, concepts.md, and _index.md to link directly at the new URL. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Picks up upstream style fixes (drops "currently", removes meta "Note:" prefix) and overrides the doc-URL line that upstream regressed to the pre-restructure /security/governance/ path. Will be fixed upstream so the next re-vendor stays clean. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Re-vendors the OpenAPI spec from upstream, which now exposes UpdateRule with application/merge-patch+json (RFC 7396) instead of application/json. The layout, the curl-command builder, and the markdown template all previously hardcoded index .content "application/json", which would have silently dropped the new content. They now iterate the content map and pick the first declared media type, surface it as a small "Content type:" label, and use the same value in the generated curl Content-Type header. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Updates api.yaml to the latest spec from docker/governor-services: - server URL changed to hub.docker.com/v2 - all paths now include /governance/ prefix - routing note added to info description - permission_denied descriptions updated to mention org entitlement Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
dvdksn
force-pushed
the
sbx/governance-docs
branch
from
32c124d to
addcf27
Compare
- defaults.md: rewrite the network-defaults outro to consolidate the two-sentence local/org split into one paragraph pointing at the governance section, and fix the stale governance.md link (was security/governance.md, now governance/org.md) - get-started.md next-steps: change [Policies]→[Governance] pointing at the section landing instead of local.md - faq.md: point the "network policies" overview link at the section landing rather than local.md Inline links that are specifically about sbx policy CLI usage (get-started.md:117, :236; isolation.md; architecture.md) stay at local.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
architecture.md and isolation.md describe the proxy mechanism that enforces network policy — this applies equally to local and org-level rules, so local.md was too narrow. Switch both to governance/. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
briandai-docker
left a comment
briandai-docker
left a comment
There was a problem hiding this comment.
This is amazing! Thanks for documenting 🙏 🙏 , left a small comments mainly pointing out delegation as something that is still TBD
| **Organization policy** is configured centrally in the Docker Admin Console or | ||
| via the [Governance API](/reference/api/ai-governance/). Rules defined at the org level apply | ||
| uniformly across every sandbox in the organization and take precedence over | ||
| local rules. Admins can optionally delegate specific rule types back to local |
There was a problem hiding this comment.
We are not supporting delegation for now until there's some more product-shaping. cc @smnovick
Comment on lines
+100
to
+103
| - Admins can [delegate](org.md#delegate-rules-to-local-policy) specific rule | ||
| types back to local control. Delegated local rules can expand access for | ||
| targets the organization hasn't explicitly denied, but can't override | ||
| organization-level deny rules. |
There was a problem hiding this comment.
Again, not supporting delegation for the time being
|
|
||
| **Enforcement and delegation.** Organization policies take precedence over | ||
| local sandbox policies and cannot be overridden by individual users. When | ||
| an administrator enables delegation for a rule type, users may supplement |
| **Routing.** This is the public-facing API. Requests are received by the | ||
| Docker Hub gateway and forwarded to the governance service; the paths | ||
| documented here (`/v2/orgs/{org_name}/governance/...`) are the public | ||
| routes, which differ from the internal service routes. |
There was a problem hiding this comment.
Stupid question, who are these docs for? 😅 Are they public facing?
| default: | ||
| value: | ||
| name: "Security Research — hardened" | ||
| scope: |
There was a problem hiding this comment.
Wondering if we should add some examples in here of teams as well. Also profiles is only enabled for Nvidia and the future shape of it is tbd.
|
|
||
| | Type | Format | Notes | | ||
| |------|--------|-------| | ||
| | Password | Plain text | Your Docker Hub account password. | |
There was a problem hiding this comment.
Building familiarity with our APIs still - need to personally check if this form of authn also works.
| value: | ||
| error: | ||
| code: invalid_argument | ||
| message: "name is required" |
There was a problem hiding this comment.
Just curious does this need quotes?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the Docker AI Governance documentation under `/ai/sandboxes/governance/` and adds the supporting API reference.
Preview links:
Information architecture
The existing `security/governance` and `security/policy` pages are merged into a new top-level `governance` section so local-policy and org-policy sit side by side instead of being split across unrelated parents:
API reference
`/reference/api/ai-governance/` renders the Governance OpenAPI spec vendored at `content/reference/api/ai-governance/api.yaml` from `docker/governor-services`. Operations, schemas, examples, and status codes are fully driven by the spec — future updates land via re-vendor, not in-repo edits. Anything wrong in the rendered reference should be fixed upstream and re-vendored here.
The spec has been re-vendored to the latest upstream version, which updated the server URL to `hub.docker.com/v2` and added the `/governance/` prefix to all API paths.
Review focus
Generated by Claude Code