mirror of
https://github.com/sredevopsorg/deepseek-kubernetes-sandbox.git
synced 2026-11-03 09:23:25 +00:00
3e9ba38fc1
Add opt-in hardening to the agents-as-a-service example: - commented runtimeClassName/nodeSelector fields for sandboxes and Deployments - optional sandbox NetworkPolicy plus exposure-variant policies - optional dsh-provider-keys-extra Secret for extra provider keys - docs/optional-hardening.md with verification, caveats and rollback The base walkthrough stays portable; no gateway code, routes or auth changed. Co-authored-by: SREDevOpsAgents <agents@sredevops.org>
133 lines
6.6 KiB
Markdown
133 lines
6.6 KiB
Markdown
# Extending the repository
|
|
|
|
Read `AGENTS.md`, `docs/examples.md`, and the example README before editing.
|
|
This repository is image-first: the Dockerfile is the primary artifact, every
|
|
implementation is a self-contained example under `examples/<name>/`, and
|
|
`versions.env` is the only source of pins. Documentation is part of the change.
|
|
|
|
## Invariants
|
|
|
|
- Never hard-code a version, image tag, or registry path; edit `versions.env`.
|
|
For the DSH release identity use `make set-version`, never ad-hoc `sed`.
|
|
- Never commit a secret. Secret-shaped manifests are `*.yaml.example` with
|
|
placeholders; keys are documented only in `.env.sample`.
|
|
- Manifests are numbered `NN-*.yaml` and apply in order with plain `kubectl`.
|
|
Exposure variants live under `manifests/exposure/<variant>/`, are documented
|
|
by one README, and are mutually exclusive.
|
|
- Keep the gateway HTTP/WebSocket contract stable unless the change is explicitly
|
|
about it.
|
|
- Do not edit `CHANGELOG.md` (generated by git-cliff) or rewrite git history.
|
|
- Keep diffs scoped; do not mix a version bump with an unrelated feature.
|
|
|
|
## Change matrix
|
|
|
|
| Change | Edit | Minimum verification |
|
|
| --- | --- | --- |
|
|
| Documentation only | `*.md`, `docs/` | `make check`; relative links resolve |
|
|
| Example manifest | `examples/<name>/manifests/NN-*.yaml`, README step | `make check`; server-side dry-run in CI |
|
|
| Optional hardening | `manifests/optional/`, exposure NPs, example `docs/optional-hardening.md` | `make check`; manual verification on a capable cluster |
|
|
| Gateway behavior/route | `gateway/gateway.py`, `gateway/test_gateway.py`, gateway README, architecture | `make test`, `make lint`; update tests and API docs |
|
|
| Exposure variant | `manifests/exposure/<variant>/`, exposure README, example README | `make check`; apply exactly one variant |
|
|
| New example | full `examples/<name>/` layout, `examples/README.md` | `make check`; CI dry-run; optional e2e |
|
|
| Version bump | `versions.env`, affected docs/manifests | `make check`; CI installs the pin; e2e on a cluster |
|
|
| MCP integration | deployment/RBAC, DSH row, docs | read-only `/readyz`; no secret in repo |
|
|
| Workflow | `.github/workflows/` | actionlint; SHA-pinned actions; no hard-coded versions |
|
|
|
|
## Recipes
|
|
|
|
### Add or change a resource step
|
|
|
|
1. Keep numbering stable; add `NN-*.yaml` at the end unless order matters.
|
|
2. Update the matching numbered step in the example README.
|
|
3. Keep cluster-specific state (node affinity, tuned replica counts) out of the
|
|
shipped manifest; document it as a local patch.
|
|
4. Run `make check`. CI additionally parses every manifest and runs a
|
|
server-side dry-run against the agent-sandbox CRDs.
|
|
|
|
### Change the gateway
|
|
|
|
The gateway is a single-file Starlette app. A change usually touches:
|
|
|
|
- `gateway/gateway.py` (route, auth, proxy, sweeper);
|
|
- `gateway/test_gateway.py` (unit tests; no cluster required);
|
|
- `gateway/README.md` (API table, configuration, auth semantics);
|
|
- `examples/dsh-agents-as-a-service/docs/architecture.md` when flows change;
|
|
- `examples/dsh-agents-as-a-service/README.md` when the walkthrough changes.
|
|
|
|
Run `make test` and `make lint`. Preserve session-cookie auth, same-origin rules
|
|
for cookie mutations and WebSocket upgrades, and the "waking"/`502`/`503`
|
|
semantics unless the change is explicitly about them. Do not expose a trusted
|
|
identity header unless the Service is reachable only through the proxy.
|
|
|
|
### Add an exposure variant
|
|
|
|
Create `manifests/exposure/<variant>/NN-*.yaml`, update
|
|
`manifests/exposure/README.md` and the example README, and state the trust
|
|
boundary. Variants are alternatives: never apply two paths to the same gateway.
|
|
Set `DSH_TRUSTED_HOSTS` in the template for the public host and
|
|
`COOKIE_SECURE=true` for HTTPS.
|
|
|
|
### Add an example
|
|
|
|
Follow `docs/examples.md`: `README.md`, `manifests/NN-*.yaml`, optional
|
|
`manifests/exposure/` with a README, optional components with Dockerfile +
|
|
README + tests, and executable, idempotent, self-cleaning scripts. Add the
|
|
literal `examples/<name>/` entry to `examples/README.md`; `make check` enforces
|
|
the layout. Publish component images under
|
|
`<registry>/<owner>/<repo>/<example>/<component>`.
|
|
|
|
### Bump a version
|
|
|
|
- **DSH release identity:** `make set-version DSH_VERSION=<ref>
|
|
[RELEASE_REVISION=rN]`, then `make check`, then build and smoke-test the image.
|
|
Tags are immutable; fix a bad release with `-r(N+1)`.
|
|
- **agent-sandbox:** edit `AGENT_SANDBOX_VERSION` in `versions.env`, update the
|
|
prerequisites in the example README, and note behavior changes (connection
|
|
types, MCP output limits, CRD fields). Install the new release YAML on a kind
|
|
cluster, then run `make check` and `make e2e`. Do not bump it inside an
|
|
unrelated PR.
|
|
|
|
### Integrate the agent-sandbox MCP server
|
|
|
|
Build from the cluster's pinned tag, give it a dedicated namespace and
|
|
least-privilege ServiceAccount, keep it ClusterIP behind an authenticating
|
|
proxy, and document how to reach `/readyz`. Add a DSH profile row only with user
|
|
approval; a row affects every session. Never commit its credentials or a
|
|
`cluster-admin` binding.
|
|
|
|
### Documentation
|
|
|
|
Update the doc whose behavior changed in the same commit: root README for the
|
|
front door, `docs/` for repository-wide contracts, the example README for that
|
|
walkthrough, the gateway README for API/config/auth. Skill docs live in
|
|
`.dsh/skills/`; keep `SKILL.md` under ~8 KB and put depth in `references/`.
|
|
`scripts/check-versions.sh` scans every `*.md` for stale `dsh-v…` tokens, so
|
|
refer to "the release identity in `versions.env`" rather than copying a tag.
|
|
|
|
## Verification and review
|
|
|
|
Run at least `make check`; add `make test` and `make lint` for gateway/script
|
|
changes. For manifests, use `kubectl apply --dry-run=server` against a cluster
|
|
with the CRDs. For behavior changes, run the example or `make e2e`.
|
|
|
|
Before reporting, review:
|
|
|
|
- [ ] Diff is scoped; no generated files or unrelated changes.
|
|
- [ ] Docs and examples match the new behavior.
|
|
- [ ] Pins come only from `versions.env`; no stale version tokens.
|
|
- [ ] No secrets or usable credentials; secret-shaped files are `.example`.
|
|
- [ ] Manifests parse; exposure variants remain mutually exclusive.
|
|
- [ ] Gateway tests and public contract unchanged or intentionally updated.
|
|
- [ ] Skills: frontmatter valid, body within budget, scripts shellcheck-clean.
|
|
- [ ] `CHANGELOG.md` untouched; branch/commit follow `docs/gitflow.md`.
|
|
|
|
## Safe follow-ups enabled by this skill
|
|
|
|
- A read-only preflight job or scheduled report using
|
|
`scripts/platform-preflight.sh`.
|
|
- An MCP readiness check in the example e2e (health endpoints only).
|
|
- A separate runtime warm pool for untrusted execution, leaving the DSH template
|
|
unchanged.
|
|
- A combined DSH + sandboxd image only with an explicit maintenance/exec design
|
|
and a documented trust boundary.
|