Rongsong Shen
a68aac1a2b
xce-node-manager: a "Cross-Spec Interactions" section (pending a requirements revision; approved criteria unchanged) with six points: a supervision/probe module shared with service-supervision, node-manager components vs service jobs, a lease-based provisioner role, role declaration and worker stop on decommission for provisioned hosts, a host-loss grace period longer than worker restart plus rejoin, and a future service proxy under the reverse-proxy role. design.md Open Questions points to it. The service-supervision, host-failure-job-recovery, elastic-hosts, resource-provisioner and service-endpoint briefs cross-reference the matching points; the roadmap lists the xce-node-manager revision. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
62 lines
2.6 KiB
Markdown
62 lines
2.6 KiB
Markdown
# Brief: service-endpoint
|
|
|
|
(`/kiro-discovery`, 2026-10-10, "Long-running services" phase 2.)
|
|
|
|
## Problem
|
|
Clients of a service need a stable way to reach its ready replicas. Today
|
|
users only see exec host names; there are no ports, no host addresses and no
|
|
registry, so every service invents its own discovery.
|
|
|
|
## Current State
|
|
- No port or network resource, endpoint, DNS or load-balancing concept;
|
|
`xce_worker_t` has no IP field and the host API marks `ip_addr` as
|
|
unsupported (`models/hosts.go:43`).
|
|
- Readiness will be reported by workers (`service-supervision`).
|
|
|
|
## Desired Outcome
|
|
- A service profile declares named ports (fixed or "any free"); each replica
|
|
is allocated its ports on its host like a resource, so two replicas never
|
|
collide; the job sees its ports in environment variables.
|
|
- Workers report host addresses; a service has an **endpoint**: its name
|
|
resolves to the list of `host:port` of ready replicas (readiness from
|
|
`service-supervision`), updated as replicas become ready or not.
|
|
- Users and clients read endpoints through REST and `xcecli` (and a simple
|
|
query interface usable from scripts); access follows RBAC (job view
|
|
scope).
|
|
- Out of v1 but kept possible: DNS records, a built-in proxy or load
|
|
balancer.
|
|
|
|
## Approach
|
|
Ports become a per-host consumable resource the scheduler allocates;
|
|
readiness changes already reach the controller; the controller (or the
|
|
apiserver from pushed state) maintains the endpoint table per service.
|
|
|
|
## Scope
|
|
- **In**: port declarations and allocation, host address reporting,
|
|
endpoint table from readiness, REST/xcecli endpoint queries, RBAC.
|
|
- **Out**: DNS, proxy/load balancing, TLS, ingress from outside the
|
|
cluster.
|
|
|
|
## Boundary Candidates
|
|
- Port resource and allocation (scheduler, worker).
|
|
- Host address reporting.
|
|
- Endpoint table and query surfaces.
|
|
|
|
## Out of Boundary
|
|
- Health probing itself (`service-supervision`).
|
|
|
|
## Upstream / Downstream
|
|
- **Upstream**: `service-supervision` (readiness), `application-profile`
|
|
(port declarations), resource model (`resource-accounting.md`).
|
|
- **Downstream**: `service-replica-set` (a service's endpoint covers all its
|
|
replica jobs; rollouts keep it populated).
|
|
|
|
## Existing Spec Touchpoints
|
|
- **Extends**: `application-profile` (ports in the service section).
|
|
- **Adjacent**: `resource-distribution-mapping`, `xce-node-manager`: a
|
|
later service proxy or load balancer would run under the Node Manager's
|
|
`reverse-proxy` role, its routing fed by the endpoint table
|
|
(`xce-node-manager` requirements.md, "Cross-Spec Interactions" 6).
|
|
|
|
## Constraints
|
|
- Endpoint updates are change-driven; no per-probe traffic.
|