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:

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:

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:

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:

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: FRP DEV contract.
docs/d601-k3s-readonly-observability.md: read-only k3s visibility command.
docs/dev-acceptance-matrix.md: DEV endpoint and health acceptance.
pikasTech/HWLAB#164: Code Agent provider and DB live hotfix follow-up contract.
pikasTech/HWLAB#61: manual rollout review and automation requirements.

5.7 KiB Raw Blame History