[PR #91] [MERGED] docs: add static multi-node deployment guide #173

New issue

Closed

opened 2026-10-29 14:20:39 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:39 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/91
Author: @catyans
Created: 7/31/2026
Status: ✅ Merged
Merged: 7/31/2026
Merged by: @yingdi-shan

Base: main ← Head: docs/non-kubernetes-multinode

📝 Commits (1)

e7b9e7a docs: add static multi-node deployment guide

📊 Changes

3 files changed (+296 additions, -0 deletions)

View changed files

📝 docs/src/SUMMARY.md (+1 -0)
📝 docs/src/deployment/docker-compose.md (+3 -0)
➕ docs/src/deployment/static-multi-node.md (+292 -0)

📄 Description

Summary

document a real multi-machine AgentENV deployment using static Scheduler discovery
provide a complete control-plane JSON example, runtime heartbeat wiring, and systemd units
document network flows, verification, operations, and common identity/addressing failures
distinguish this deployment from the single-host Docker Compose simulation

Why

Docker Compose only simulates multiple nodes on one host, while the existing
Kubernetes guide is the only documented multi-machine path. AgentENV already
supports a non-Kubernetes deployment with statically configured runtime nodes,
but the required identity, endpoint, and heartbeat relationship was not
documented.

The guide makes the current constraint explicit: heartbeats do not
auto-register unknown nodes, so every AENV_NODE_ID must match a
scheduler.nodes[].id, and static membership changes require a Scheduler
restart.

Validation

git diff --check
make -C services test on the Lingjun test host
built both Go control-plane binaries on the Lingjun test host
extracted the JSON example from the guide and started Scheduler and Gateway
with isolated ports
verified the Gateway /health and /nodes endpoints through the temporary
control plane

Closes #59.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/91 **Author:** [@catyans](https://github.com/catyans) **Created:** 7/31/2026 **Status:** ✅ Merged **Merged:** 7/31/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `docs/non-kubernetes-multinode` --- ### 📝 Commits (1) - [`e7b9e7a`](https://github.com/kvcache-ai/AgentENV/commit/e7b9e7a5f7643205d1699c25a47b06910c517788) docs: add static multi-node deployment guide ### 📊 Changes **3 files changed** (+296 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/src/SUMMARY.md` (+1 -0) 📝 `docs/src/deployment/docker-compose.md` (+3 -0) ➕ `docs/src/deployment/static-multi-node.md` (+292 -0) </details> ### 📄 Description ## Summary - document a real multi-machine AgentENV deployment using static Scheduler discovery - provide a complete control-plane JSON example, runtime heartbeat wiring, and systemd units - document network flows, verification, operations, and common identity/addressing failures - distinguish this deployment from the single-host Docker Compose simulation ## Why Docker Compose only simulates multiple nodes on one host, while the existing Kubernetes guide is the only documented multi-machine path. AgentENV already supports a non-Kubernetes deployment with statically configured runtime nodes, but the required identity, endpoint, and heartbeat relationship was not documented. The guide makes the current constraint explicit: heartbeats do not auto-register unknown nodes, so every `AENV_NODE_ID` must match a `scheduler.nodes[].id`, and static membership changes require a Scheduler restart. ## Validation - `git diff --check` - `make -C services test` on the Lingjun test host - built both Go control-plane binaries on the Lingjun test host - extracted the JSON example from the guide and started Scheduler and Gateway with isolated ports - verified the Gateway `/health` and `/nodes` endpoints through the temporary control plane Closes #59. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:39 +00:00