pikasTech-unidesk/docs/reference/platform-infra.md

G14 Platform Infra

platform-infra is the G14 k3s namespace for UniDesk-operated shared platform services. It is separate from HWLAB runtime lanes, AgentRun lanes, D601 user services, and legacy devops-infra control-plane helpers. New shared infra should land here first; old devops-infra resources migrate gradually only when a concrete owner and validation path exist.

Source Of Truth

• UniDesk-owned platform configuration must be YAML-first. config/platform-infra/*.yaml is the durable source for images, versions, endpoints, FRP exposure, account profile selection, and local consumer configuration.
• Runtime Secrets and local ~/.codex/config.toml* / auth.json* files are inputs or generated local state, not committed truth. CLI output may show Secret paths, byte counts, fingerprints, and short previews only; it must not print complete API keys.
• Code that reads platform YAML must validate object shape, field types, required fields, Kubernetes names, image strings, and ports before mutating G14 k3s or local consumer files.
• Do not hide image versions, namespace names, endpoint URLs, FRP ports, or profile lists in Python/TOML/JSON helper constants when they are UniDesk-owned choices. External tools may still require their own TOML/JSON/env file formats at the edge.

Sub2API Deployment Boundary

• Sub2API is a G14 platform service operated by UniDesk in namespace platform-infra. It is not a HWLAB lane workload, AgentRun workload, D601 service, or master server daemon.
• The canonical deployment entrypoint is bun scripts/cli.ts platform-infra sub2api plan|apply|status|validate|codex-pool; raw kubectl through trans G14:k3s is only for bounded diagnosis and evidence.
• The image version is controlled by config/platform-infra/sub2api.yaml. Updating the image must be a YAML change plus platform-infra sub2api apply --confirm and follow-up runtime validation.
• Sub2API should stay ClusterIP-only by default. Do not add Ingress, NodePort, LoadBalancer, or broad FRP exposure unless a YAML-controlled public exposure decision exists.
• Sub2API currently has no resource limits by design. Do not add CPU or memory limits unless a later explicit decision changes that policy and stores the new policy in YAML.
• Master server is a consumer/control host, not the runtime location. Do not deploy Sub2API, PostgreSQL, Redis, or heavy validation loops on master server.

Codex Pool Routing

config/platform-infra/sub2api-codex-pool.yaml controls the Codex-facing OpenAI-compatible pool:

• pool.groupName names the Sub2API group that represents the pool.
• pool.apiKeySecretName and pool.apiKeySecretKey name the k3s Secret that stores the single consumer API key.
• profiles.entries selects local Codex profile files from ~/.codex/ and maps them to Sub2API account names.
• publicExposure controls the optional FRP bridge from master server to the G14 ClusterIP service.
• localCodex controls how the master server's current ~/.codex consumer files are backed up and rewritten.

The request path is:

1. A client sends an OpenAI-compatible request to the configured consumer base URL, normally master-local http://127.0.0.1:<frp-port>/v1/..., with the unified API key.
2. master frps forwards the TCP connection to platform-infra/sub2api-frpc when publicExposure.enabled is true.
3. sub2api-frpc forwards to sub2api.platform-infra.svc.cluster.local:8080.
4. Sub2API validates the unified key and resolves its group_id.
5. Accounts listed in profiles.entries are bound to the same group via group_ids, so Sub2API dispatches through that group using its own account selection semantics.

After codex-pool configure-local --confirm, the default upstream profile must not recursively import the just-created Sub2API consumer endpoint as an upstream account. Keep the default source profile pointed at config.toml.<backupSuffix> and auth.json.<backupSuffix>; fallback to the current default files is only for first bootstrap before backups exist.

Availability And Probes

Kubernetes readiness is not the same as pool availability:

• The Sub2API app, PostgreSQL, and Redis manifests include container-level health probes. These only prove the pods and local dependencies are healthy enough for Kubernetes scheduling.
• The FRP client deployment is currently a simple connector deployment and does not itself prove that master-local traffic reaches Sub2API.
• No scheduled CronJob, ServiceMonitor, or PodMonitor currently proves the full unified Codex API path.
• platform-infra sub2api validate and platform-infra sub2api codex-pool validate are on-demand checks. They are acceptable for deployment closeout, but they are not continuous monitoring.

When an automatic availability probe is added, it should be YAML-controlled and cover these layers without printing secrets:

1. G14 in-cluster GET /v1/models through sub2api.platform-infra.svc.cluster.local:8080 with the unified key.
2. master-local GET /v1/models through the configured FRP endpoint when public exposure is enabled.
3. A tiny POST /v1/responses call through the same consumer URL for true OpenAI-compatible request validation.
4. Optional per-upstream account probes if Sub2API exposes a safe account selection or admin-health mechanism; otherwise document that group-level success does not prove every upstream account is healthy.

Until continuous probing exists, closeout comments must state that validation was on-demand and include the exact CLI/API entrypoints used.