# 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.

## 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#61](https://github.com/pikasTech/HWLAB/issues/61): manual
  rollout review and automation requirements.