Repository navigation
docs: remove inaccurate early-stage architecture documentation - #3517
Merged
Benjamin Elder (BenTheElder) merged 2 commits intoNov 3, 2026
Merged
Benjamin Elder (BenTheElder) merged 2 commits into
Benjamin Elder (BenTheElder) merged 2 commits into
Conversation
Remove the status: planned frontmatter banner, rewrite the outdated 'Problems We Haven't Addressed Yet' section, document atenet-egress in the networking stack, and link the Security & Isolation section to the main security documentation instead of restating it. Signed-off-by: Greg Castle <[email protected]>
Comment on lines
+77
to
+80
| frequently. Agent Substrate treats data locality as a first-class concern. | ||
| `atelet` keeps a node-local copy of an actor's latest snapshot after suspend so | ||
| subsequent resumes on that node avoid an object-store round-trip. It uploads | ||
| snapshots to durable object storage in the background or on demand. |
Collaborator
There was a problem hiding this comment.
🤖 non-blocking: this reads as only an upside now, but the data loss risk the old list called out is still there. Async suspend is the default, so if the node goes away before the background upload lands, the actor crashes and revert takes it back to the previous durable snapshot (docs/reference/api-guide.md:716). The local copy also only lasts until --snapshot-detach-delay, and there's no "on demand" upload.
Actor Lifecycle (L447-463) already describes this accurately, maybe state the tradeoff here and link there?
Collaborator
Author
There was a problem hiding this comment.
🤖 Updated to call out the durability vs. fast-reactivation tradeoff explicitly, noting that node-local snapshots are ephemeral (bound by --snapshot-detach-delay) and async suspends carry state loss risk if the node fails before remote upload, with a link to the Actor Lifecycle section.
Comment on lines
+82
to
+85
| Second, a specialized control plane must integrate cleanly with Kubernetes | ||
| while enforcing its own security boundaries. `ate-api-server` authenticates | ||
| callers via mTLS and OIDC, authorizes every RPC per atespace with an embedded | ||
| OpenFGA model, and delegates pod and node lifecycle to Kubernetes. |
Collaborator
There was a problem hiding this comment.
ate-api-server doesn't manage pods so this reads kinda weirdly.
atecontroller reconciles WorkerPools into Deployments.
Collaborator
Author
There was a problem hiding this comment.
🤖 Updated to clarify that ate-api-server handles RPC authn/authz while atecontroller reconciles WorkerPool CRDs into Deployments.
Comment on lines
+381
to
+384
| For `http` and `https` rules with `replaceHeaders`, `atenet-egress` injects | ||
| secrets from a configured credential provider or an actor JWT minted by | ||
| `ate-api-server` on the wire so the sandbox never holds ambient credentials | ||
| (see [Egress Credential Injection](../guides/egress-credential-injection.md)). |
Collaborator
There was a problem hiding this comment.
🤖 non-blocking: replaceHeaders only replaces a header the actor already sends, a request without it goes out unchanged (docs/guides/egress-credential-injection.md:176), so "injects" oversells it a bit.
More generally this copies details from docs/guides/network-egress.md, which is the egress contract and already covers this, including the DNS exception and that non-TCP traffic is blocked, which this leaves out. Can we cut it to a line or two and link that?
Collaborator
Author
There was a problem hiding this comment.
🤖 Cut down to a single sentence on tunneling, policy enforcement, and credential replacement effects, linking directly to the Network Egress Contract and Egress Credential Injection docs.
Comment on lines
+87
to
+92
| Third, with actors multiplexed onto and off of workers, operators need | ||
| actor-level and pool-level visibility. Agent Substrate emits OpenTelemetry | ||
| metrics, structured logs, and lifecycle events across its components so | ||
| operators can monitor worker capacity, track suspend/resume latency, and | ||
| correlate activity across an actor's lifetime (see the | ||
| [Observability](../guides/observability.md) guide). |
Collaborator
There was a problem hiding this comment.
🤖 nit: the observability guide says only container logs carry the actor labels today, and actor-level correlation for metrics and traces is still on the roadmap (docs/guides/observability.md:25). Maybe scope "correlate activity across an actor's lifetime" to logs?
Collaborator
Author
There was a problem hiding this comment.
🤖 Done, scoped correlation to container logs.
Address review feedback from BenTheElder: - Clarify state loss tradeoff of asynchronous suspend and detach delay. - Scope actor-level correlation to container logs. - Clarify atecontroller reconciles WorkerPools into Deployments. - Condense egress networking bullet and link to the network egress contract. Signed-off-by: Greg Castle <[email protected]>
Benjamin Elder (BenTheElder)
approved these changes
Nov 3, 2026
Eitan Yarmush (EItanya)
pushed a commit
to kagent-dev/substrate
that referenced
this pull request
Nov 3, 2026
…-substrate#3517) 1. Removes the `status: planned` banner so the page no longer claims to be aspirational. 2. Rewrites the trade-offs section into present-tense implementation context (data locality, control-plane boundaries, and OpenTelemetry observability) and removes the outdated "haven't started to tackle" list. 3. Documents `atenet-egress`, DNS relay filtering, and `EgressPolicy` credential injection under the Networking Stack. 4. Replaces the inline Security & Isolation bullet list with links to the main Security Overview and Threat Model documents. AI use: AI-assisted, I reviewed and tested it. - [x] Tests pass - [x] Docs updated --------- Signed-off-by: Greg Castle <[email protected]> (cherry picked from commit 5a5b192) Signed-off-by: Eitan Yarmush <[email protected]>
1 of 2 tasks
Dmitry Berkovich (dberkov)
pushed a commit
that referenced
this pull request
Nov 3, 2026
Bring `release-1.0` up to `main` at 5a5b192 with the 19 changes merged since the previous batch in #3536. The final tree matches that commit exactly. **Please use Rebase and merge to preserve the individual commits and author attribution.** All 19 applied cleanly in upstream order. Original authors, author dates, co-author and sign-off trailers, and `-x` source references are retained. Upgrade notes: - #3533: old gVisor MEMORY snapshots, including goldens, no longer restore. Recreate them after upgrading. MicroVM MEMORY snapshots still resume with their old mounts until recreated. `/tmp` is now always tmpfs; ROOTFS snapshots no longer preserve its contents, and image-provided files there are hidden. MicroVM `/tmp` counts against actor memory and is capped at half the guest's memory. gVisor `/dev/shm` is now a 64 MiB tmpfs. Mount a `durableDir` at either path when persistence or more space is needed. `/run` now comes from the image rootfs. - #3447: remove `--actor-jwt-jwks-file` from custom credential-exchange sidecar configs. Set `--actor-jwt-issuer-ca-file` only when the issuer uses a private CA other than the service DNS CA. - #3450: do not reuse a deleted atespace name. See the updated atespace name-reuse guidance. Includes #3505, which overlaps the open backport in #3547. GKE provisioning and teardown now live in [substrate-gke](https://github.com/ai-on-gke/substrate-gke) rather than this repository. <details> <summary>Included PRs, in cherry-pick order</summary> 1. #3500: demos/{sandbox,jupyter,multi-template}: fix tutorial prerequisites, walkthroughs, and counter volume 2. #3498: demos/counter: inline gVisor walkthrough and fix setup commands 3. #3511: e2e tests: Extend the existing tests to cover tag actor. 4. #2775: Generate API reference documentation and publish it on Substrate website 5. #3119: Document how people, pods and CI jobs should authenticate to ate-api 6. #3505: tools: remove setup-gcp and hack/teardown.sh 7. #3147: e2e: resume fidelity after SandboxConfig version edits 8. #3370: ate-setup: reconcile ate-api-server ConfigMaps and roll out on config changes 9. #1607: hack: reject breaking proto changes across each proto package 10. #3415: docs: update and add security diagrams 11. #3485: Resuming a microVM actor on the same node no longer reads its rootfs upper back from disk 12. #3447: Verify actor JWTs in the credential exchange through OIDC discovery 13. #3533: ocispec: mount tmpfs at /dev/shm, and /tmp on both runtimes 14. #3450: docs: Document that atespace names must not be reused 15. #3410: Document using more than one egress credential provider 16. #3486: atelet: register the device plugin on a new socket each time 17. #3553: ate-setup: wait for the demo namespace in delete demo 18. #3560: Fix multiple issues in claude-code-multiplex demo 19. #3517: docs: remove inaccurate early-stage architecture documentation </details> Validation: every intermediate tree matches its upstream source commit, all 19 authorship records and original attribution trailers are preserved, and `git diff --check` passes. The original 18 backport commits are unchanged. AI use: AI-assisted cherry-picking, attribution checks, and review. - [ ] Tests pass - [x] Docs updated --------- Signed-off-by: Mofi Rahman <[email protected]> Signed-off-by: Eitan Yarmush <[email protected]> Signed-off-by: Nayana Bidari <[email protected]> Signed-off-by: Julian Gutierrez Oschmann <[email protected]> Signed-off-by: Max Thompson <[email protected]> Signed-off-by: Steven Shriver <[email protected]> Signed-off-by: Grant McCloskey <[email protected]> Signed-off-by: Shrutiya <[email protected]> Signed-off-by: Haiyan Meng <[email protected]> Signed-off-by: Greg Castle <[email protected]> Signed-off-by: Benjamin Elder <[email protected]> Signed-off-by: Anish Ramasekar <[email protected]> Signed-off-by: Shruti Nair <[email protected]> Signed-off-by: Haven Xia <[email protected]> Co-authored-by: Mofi Rahman <[email protected]> Co-authored-by: nybidari <[email protected]> Co-authored-by: Julian Gutierrez Oschmann <[email protected]> Co-authored-by: Max Thompson <[email protected]> Co-authored-by: Grant McCloskey <[email protected]> Co-authored-by: Steven Shriver <[email protected]> Co-authored-by: shrutiyam-glitch <[email protected]> Co-authored-by: haiyanmeng <[email protected]> Co-authored-by: Greg Castle <[email protected]> Co-authored-by: Benjamin Elder <[email protected]> Co-authored-by: Anish Ramasekar <[email protected]> Co-authored-by: Shruti Nair <[email protected]> Co-authored-by: Haven Xia <[email protected]> Co-authored-by: Adam Wathieu <[email protected]>
1 of 2 tasks
Dmitry Berkovich (dberkov)
pushed a commit
that referenced
this pull request
Nov 3, 2026
1. Removes the `status: planned` banner so the page no longer claims to be aspirational. 2. Rewrites the trade-offs section into present-tense implementation context (data locality, control-plane boundaries, and OpenTelemetry observability) and removes the outdated "haven't started to tackle" list. 3. Documents `atenet-egress`, DNS relay filtering, and `EgressPolicy` credential injection under the Networking Stack. 4. Replaces the inline Security & Isolation bullet list with links to the main Security Overview and Threat Model documents. AI use: AI-assisted, I reviewed and tested it. - [x] Tests pass - [x] Docs updated --------- Signed-off-by: Greg Castle <[email protected]> (cherry picked from commit 5a5b192) Signed-off-by: Eitan Yarmush <[email protected]>
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
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.
status: plannedbanner so the page no longer claims to be aspirational.atenet-egress, DNS relay filtering, andEgressPolicycredential injection under the Networking Stack.AI use: AI-assisted, I reviewed and tested it.