docs(specs): record xce-node-manager interactions with service and provisioning specs

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>

2026-10-10 07:46:24 +00:00

2.6 KiB

Raw Blame History

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.

2.6 KiB Raw Blame History