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

docs: reference sub2api operations skill

Browse Source
This commit is contained in:
Codex
2026-06-09 06:53:53 +00:00
parent 8a7c570009
commit 53f319ea9d
3 changed files with 8 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/platform-infra.md
+5 -4
View File
@@ -12,8 +12,9 @@
## 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.
- The canonical deployment entrypoint is `bun scripts/cli.ts platform-infra sub2api plan|apply|status|validate|codex-pool`; daily operation procedures live in `$unidesk-sub2api` at `~/.agents/skills/unidesk-sub2api/SKILL.md`. This reference keeps only development boundaries and project-specific source-of-truth rules.
- Raw `kubectl` through `trans G14:k3s` is only for bounded diagnosis and evidence, not a formal mutate path.
- The image version is controlled by `config/platform-infra/sub2api.yaml`. Image update procedures are daily operations owned by `$unidesk-sub2api`; the development boundary is that image choices remain YAML-controlled.
- 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.
@@ -38,7 +39,7 @@ The request path is:
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.
Adding an upstream should be a fast YAML operation: create the corresponding local `~/.codex/config.toml.<profile>` and `auth.json.<profile>` inputs, add one `profiles.entries` item, then run `platform-infra sub2api codex-pool plan|sync --confirm`. Removing an upstream is also a YAML operation: remove the `profiles.entries` item, then run `sync --confirm`; the sync path deletes only matching `unidesk-codex-*` accounts that are marked `unidesk_managed=true` and absent from YAML. Do not add code or CI/CD for ordinary pool membership changes. Code changes are only appropriate when the YAML schema needs a new reusable capability such as account-level WebSocket mode or per-account upstream User-Agent.
Adding, removing, exposing, validating, and configuring local Codex consumers are daily operations covered by `$unidesk-sub2api`. The development rule is that ordinary pool membership changes stay YAML-only and do not add code or CI/CD. Code changes are only appropriate when the YAML schema needs a new reusable capability such as account-level WebSocket mode or per-account upstream User-Agent.
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.
@@ -55,7 +56,7 @@ 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.
- `platform-infra sub2api validate` and `platform-infra sub2api codex-pool validate` are on-demand checks. Operational usage is documented in `$unidesk-sub2api`; 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: