Code Queue Review
148 lines
5.7 KiB
Markdown
148 lines
5.7 KiB
Markdown
# HWLAB DEV Runtime Boundary
|
|
|
|
This reference defines the stable DEV environment, port, k3s, and runtime
|
|
substitution rules.
|
|
|
|
## Public DEV Ports
|
|
|
|
| Surface | URL |
|
|
| --- | --- |
|
|
| Cloud Web browser entry | `http://74.48.78.17:16666/` |
|
|
| API/edge entry | `http://74.48.78.17:16667/` |
|
|
| API/live health | `http://74.48.78.17:16667/health/live` |
|
|
|
|
Public `:6666` and `:6667` are deprecated as browser/API acceptance targets.
|
|
Internal k3s services may still listen on `6667`; do not rewrite that as a
|
|
public endpoint.
|
|
|
|
## Route Shape
|
|
|
|
The public route is:
|
|
|
|
```text
|
|
master hwlab-frps-dev :16666/:16667
|
|
-> D601 hwlab-frpc in namespace hwlab-dev
|
|
-> hwlab-cloud-web on internal :8080 for browser traffic
|
|
-> hwlab-edge-proxy / hwlab-cloud-api on internal :6667 for API and health
|
|
```
|
|
|
|
`deploy/deploy.json` is the source for public endpoint and FRP mapping drift
|
|
checks. Use:
|
|
|
|
```sh
|
|
node scripts/deploy-contract-plan.mjs --check
|
|
```
|
|
|
|
## D601 k3s Source Of Truth
|
|
|
|
D601 native k3s is the DEV runtime source of truth. Commands that observe or
|
|
roll a DEV workload must specify:
|
|
|
|
```sh
|
|
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev get deploy,svc,pod -o wide
|
|
```
|
|
|
|
Do not trust the default `kubectl` context as a DEV runtime signal. On D601 it
|
|
may point at another cluster such as `docker-desktop`.
|
|
|
|
Use the read-only preflight when a runner needs to report k3s visibility:
|
|
|
|
```sh
|
|
node scripts/d601-k3s-readonly-observability.mjs
|
|
```
|
|
|
|
The preflight must not print secret values, kubeconfig material, ConfigMap
|
|
values, or token content.
|
|
|
|
## Cloud API DB DNS Contract
|
|
|
|
`hwlab-cloud-api` reads the DEV database connection string from Secret
|
|
reference `hwlab-cloud-api-dev-db/database-url`. The Secret value is not stored
|
|
in source, not printed by reports, and not required for offline validation.
|
|
|
|
The non-secret DNS contract is source-controlled:
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Service | `cloud-api-db` |
|
|
| Namespace | `hwlab-dev` |
|
|
| Host | `cloud-api-db.hwlab-dev.svc.cluster.local` |
|
|
| Port | `5432` |
|
|
| Port name | `postgres` |
|
|
|
|
`deploy/k8s/base/services.yaml` must include a selectorless
|
|
`Service/cloud-api-db` with that port so k3s DNS has a stable handle before the
|
|
actual DB endpoints are provisioned. A selectorless Service proves only that
|
|
the name can exist in cluster DNS; it does not prove a DB endpoint, credential,
|
|
TCP connection, schema migration, durable persistence, or M4/M5 readiness.
|
|
|
|
`deploy/deploy.json`, `deploy/k8s/base/workloads.yaml`, and
|
|
`internal/cloud/db-contract.mjs` must agree on
|
|
`HWLAB_CLOUD_DB_SERVICE_NAME`, `HWLAB_CLOUD_DB_SERVICE_NAMESPACE`,
|
|
`HWLAB_CLOUD_DB_HOST`, and `HWLAB_CLOUD_DB_PORT`. `npm run validate` checks
|
|
this agreement offline. A live pass still requires `/health/live` to report
|
|
`db.ready=true`, `db.connected=true`, and `liveDbEvidence=true` with secret
|
|
values redacted.
|
|
|
|
The DB readiness contract is layered:
|
|
|
|
| Layer | Required evidence |
|
|
| --- | --- |
|
|
| DNS | The configured target resolves from the `hwlab-cloud-api` runtime path and is not a `.invalid` placeholder. |
|
|
| TCP | A redacted TCP probe reaches the configured Postgres port. |
|
|
| Auth | Authenticated database access succeeds without printing the connection string. |
|
|
| Schema | Required HWLAB schema/migration checks pass without using fixture output as live evidence. |
|
|
|
|
`*.invalid` and `hwlab-dev-db.invalid` are forbidden DEV runtime targets. They
|
|
may appear only as negative test fixtures; source and runtime health must not
|
|
treat them as desired DEV DB endpoints.
|
|
|
|
## Code Agent Provider Contract
|
|
|
|
`hwlab-cloud-api` runs the DEV Code Agent provider through OpenAI Responses.
|
|
Source-controlled manifests must declare only env names, Secret references, and
|
|
non-secret egress settings:
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Provider env | `HWLAB_CODE_AGENT_PROVIDER=openai` |
|
|
| Model env | `HWLAB_CODE_AGENT_MODEL=gpt-5.5` |
|
|
| Provider Secret | `OPENAI_API_KEY` from `hwlab-code-agent-provider/openai-api-key` |
|
|
| DEV egress/base URL | `HWLAB_CODE_AGENT_OPENAI_BASE_URL=http://172.26.26.227:17680/v1/responses` |
|
|
|
|
DEV pods must not call `https://api.openai.com/v1/responses` directly. The base
|
|
URL must use the approved DEV egress/proxy path so provider reachability is a
|
|
repeatable deployment contract instead of a one-off runtime patch.
|
|
|
|
Reports, smokes, and health payloads may show Secret name/key presence,
|
|
`missingEnv`, provider status, model, trace IDs, and redacted egress status.
|
|
They must never print the OpenAI API key, bearer token, database URL password,
|
|
kubeconfig material, or other secret values.
|
|
|
|
## Hotfix To Source Rule
|
|
|
|
DEV runtime hotfixes are temporary recovery actions. After a hotfix proves the
|
|
minimal live path, the durable follow-up is source automation: update manifests,
|
|
contracts, docs, and tests so future rollouts reproduce the same env and safety
|
|
boundaries. The runner must not re-execute the live hotfix, restart services,
|
|
read Secrets, mutate PROD, or claim live evidence from source-only changes.
|
|
|
|
## Runtime Substitution Ban
|
|
|
|
UniDesk services, provider-gateway, backend-core, microservice proxies, local
|
|
fixtures, and runner-local mocks may support scheduling, CI, CD, source checks,
|
|
or dry-runs. They cannot be described as HWLAB runtime and cannot satisfy M3,
|
|
M4, or M5 live evidence.
|
|
|
|
## Stable Sources
|
|
|
|
- [deploy/frp/README.md](../../deploy/frp/README.md): FRP DEV contract.
|
|
- [docs/d601-k3s-readonly-observability.md](../d601-k3s-readonly-observability.md):
|
|
read-only k3s visibility command.
|
|
- [docs/dev-acceptance-matrix.md](../dev-acceptance-matrix.md): DEV endpoint
|
|
and health acceptance.
|
|
- [pikasTech/HWLAB#164](https://github.com/pikasTech/HWLAB/issues/164):
|
|
Code Agent provider and DB live hotfix follow-up contract.
|
|
- [pikasTech/HWLAB#61](https://github.com/pikasTech/HWLAB/issues/61): manual
|
|
rollout review and automation requirements.
|