mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: codify host proxy bootstrap governance

Browse Source
This commit is contained in:
Codex
2026-06-29 11:11:08 +00:00
parent 7d981a9785
commit 73d40d310c
4 changed files with 69 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/yaml-first-ops.md
+29
View File
@@ -73,6 +73,25 @@ The domain CLI resolves the target from YAML, calls shared helpers and prints st
Runtime mutation goes through UniDesk CLI and `trans` route execution. Direct `kubectl`, raw SSH, hand-written Caddy edits, direct GitHub API calls or ad hoc shell scripts may be diagnostic or emergency recovery tools only. Repeated operational writes must be promoted into a controlled CLI command that reads YAML and reports redacted structured output.
## Host Bootstrap And Zero-Dependency Proxy
Fresh VPS bootstrap has one allowed host-level exception before the node can become a clean k3s runtime: a zero-dependency host proxy client distributed and configured by YAML-first ops through `trans`. The client must not require Docker, k3s, containerd, Node, Python, Bun, Go, Rust, or package-manager network access to install. Its purpose is to provide outbound connectivity for those dependencies, including k3s installer downloads, container image pulls, `apk`, `apt`, `npm`, Go modules, Git and git-mirror sync/flush.
The proxy source, upstream server identity, local listen address, local port, systemd unit, environment injection targets, health probe and secret source references must be declared in YAML. The target node should receive only rendered artifacts and redacted summaries over `trans`; it must not fetch the proxy client from the public internet before the proxy exists. Values such as proxy server host, credentials, bind port and benchmark profile belong in YAML or Secret source files, not in prose or code defaults.
The default bootstrap order for a new node is:
1. establish provider-gateway only long enough to make `trans` reachable;
2. distribute the zero-dependency proxy client through `trans`;
3. start and validate the host proxy client from YAML-rendered systemd or equivalent host control;
4. configure host egress for k3s/containerd/package managers and Git through that proxy;
5. install k3s and deploy workloads through YAML-first control paths;
6. keep later workload proxy settings as YAML-declared consumers of the host route unless a domain explicitly owns a different proxy boundary.
For fresh VPS bring-up, do not use provider-gateway WebSocket egress as the bulk path for large installers, images or dependency downloads. Provider-gateway and `trans` are the bootstrap control channel; the host proxy client is the data egress path once installed.
Host proxy use has a privacy boundary. A plain `http_proxy=http://...` proxy can observe destination hosts, request metadata and any proxy credential embedded in the URL or process environment; TLS protects encrypted request bodies from the proxy but does not hide the destination metadata from the proxy operator. Do not place private API keys in proxy URLs, logs or CLI output. `NO_PROXY`/`no_proxy` must preserve local, cluster, metadata and explicitly declared direct domains, including `hyueapi.com` and `.hyueapi.com` for Codex direct API access.
## Cross-Repository Operational Truth
When UniDesk prepares or supervises runtime data for another repository, the owning YAML still belongs in UniDesk if the data is part of node/lane operations rather than that repository's application source. Examples include HWLAB test/admin account inventories, operator-only API key source references, runtime DB sync inputs, public exposure targets and cross-node workbench preparation. The service repository may contain application code and app-native migrations, but it must not become a second desired-state truth for UniDesk-operated accounts, credentials, nodes, lanes, namespaces or sourceRef bindings.
@@ -109,6 +128,16 @@ External database consumers must reference the YAML-owned platform database sour
Probes are validation data, not hidden policy. YAML should declare what endpoint or runtime object proves the operation for that service. CLI code may execute the probe, bound output and classify failure, but should not hard-code current URLs, credentials, namespaces or service paths.
## Reuse, Composition And Variable Rendering
YAML-first does not mean one ever-growing file per node. Reusable configuration should be expressed as small owning YAML documents that can be inherited, composed or referenced by `configRefs`. A node-specific file should normally select a baseline, provide only the concrete overrides for that node, and reference shared blocks for proxy, public exposure, Secret distribution, source truth, runtime dependencies, probes and rollout policy.
Config composition must keep one durable source of truth for each fact. Rendered plans may merge defaults, baselines and overrides for execution, but the merged object must not be written back as a second editable truth. CLI `plan/status --full` should show the reference chain, effective owner, variable inputs, redacted source fingerprints and missing fields instead of dumping all expanded YAML by default.
Variable rendering is allowed for node/lane/service-specific artifact generation. Node and lane identifiers must be data variables, not part of YAML filenames, parser function names, renderer names, TypeScript helper names or long-term schema names. For example, use a neutral template plus `NODE`/`LANE` variables instead of adding files or functions named after a concrete node. Concrete node names may appear only as YAML values, CLI parameters, rendered runtime object names where the external system needs them, or legacy adapters that are explicitly classified.
When a configuration area starts to repeat whole blocks across nodes, treat that as a design smell. Promote the common block into a baseline or shared reference before adding more node copies, and keep node overrides short enough to review. If the owning YAML still grows without a clear owner boundary, split by responsibility: bootstrap host dependencies, proxy, k3s install, platform services, app lane, public exposure, Secret sourceRefs, probes and sentinel schedules should not be forced into one file merely because they target the same node.
## Refactoring Rule
When adding YAML-first ops to an existing domain, follow this order: