unidesk-code-queue-runner
104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# Deploy Contract
|
|
|
|
`deploy.schema.json` defines the future `deploy/deploy.json` manifest shape.
|
|
|
|
The MVP acceptance environment is DEV only. Public endpoint source fields live in
|
|
`deploy/deploy.json`: frontend `http://74.48.78.17:16666` and API/edge
|
|
`http://74.48.78.17:16667`. PROD profile fields may be represented in schema
|
|
for future compatibility, but PROD deployment is not part of MVP acceptance.
|
|
|
|
## L5 DEV Skeleton
|
|
|
|
- `deploy/deploy.json` is the DEV-only deploy manifest.
|
|
- `deploy/deploy.json` is the single source for `health.path`,
|
|
`publicEndpoints`, `frp.proxies`, and `k3s.serviceMappings`.
|
|
- `deploy/k8s/base` contains parseable k3s resource skeletons for the frozen
|
|
HWLAB service IDs rendered from the manifest contract.
|
|
- `deploy/k8s/dev` contains the DEV health contract and endpoint metadata.
|
|
- `hwlab-cloud-api` declares the DEV DB env contract with
|
|
`HWLAB_CLOUD_DB_URL` from Secret reference
|
|
`hwlab-cloud-api-dev-db/database-url` and non-secret
|
|
`HWLAB_CLOUD_DB_SSL_MODE=disable`. Runtime DB readiness dials the redacted
|
|
host parsed from that Secret URL. `cloud-api-db` is only an optional desired
|
|
alias until Service plus Endpoint/EndpointSlice ownership and rollout/apply
|
|
contract exist; see
|
|
[docs/reference/dev-runtime-boundary.md](../docs/reference/dev-runtime-boundary.md).
|
|
The repository records names only, never secret values or a live DB
|
|
connection string; runtime health reports redacted env injection and DB
|
|
connection result classifiers.
|
|
- `hwlab-cloud-api` declares the DEV Code Agent provider contract with
|
|
`OPENAI_API_KEY` from Secret reference
|
|
`hwlab-code-agent-provider/openai-api-key` and
|
|
`HWLAB_CODE_AGENT_OPENAI_BASE_URL` through the DEV egress/proxy path. Source
|
|
checks verify the Secret ref and base-url contract only; they do not prove
|
|
provider connectivity and must not print API key material. Controlled apply
|
|
reports also check that the live `hwlab-cloud-api` Deployment preserves the
|
|
same env names and `secretKeyRef` name/key metadata after apply without
|
|
reading Kubernetes Secret data.
|
|
- `hwlab-cloud-api` also declares `HWLAB_CLOUD_RUNTIME_ADAPTER=postgres` and
|
|
`HWLAB_CLOUD_RUNTIME_DURABLE=true` so DEV can use the Postgres-backed runtime
|
|
adapter once the schema is applied. `/health/live` must still remain degraded
|
|
if DB auth, DB connectivity, or runtime schema readiness is blocked.
|
|
- `deploy/k8s/prod` is a disabled placeholder gate only.
|
|
- `deploy/frp` describes the D601-to-master reverse link without secrets.
|
|
- `deploy/master-edge` describes public edge ownership and health boundaries.
|
|
|
|
Dry-run source rendering:
|
|
|
|
```sh
|
|
node scripts/deploy-contract-plan.mjs --pretty
|
|
node scripts/deploy-contract-plan.mjs --check
|
|
```
|
|
|
|
The deploy contract plan renders and validates only. It does not run frps/frpc,
|
|
does not call `kubectl apply`, does not restart services, and does not touch
|
|
PROD. Later work can wire the same source fields into `hwlab edge apply` or
|
|
`deploy apply`.
|
|
|
|
Desired-state commit/image convergence review:
|
|
|
|
```sh
|
|
node scripts/deploy-desired-state-plan.mjs --plan --pretty
|
|
node scripts/deploy-desired-state-plan.mjs --target-ref origin/main --check
|
|
node scripts/deploy-desired-state-plan.mjs --target-ref origin/main --pretty
|
|
node scripts/deploy-desired-state-plan.mjs --target-tag <tag> --pretty
|
|
node scripts/deploy-desired-state-plan.mjs --promotion-commit <sha> --check
|
|
```
|
|
|
|
The desired-state plan reads only `deploy/deploy.json`,
|
|
`deploy/artifact-catalog.dev.json`, `deploy/k8s/base/workloads.yaml`, and the
|
|
optional artifact report snapshot. It checks that commit IDs, service image
|
|
tags, workload images, and present env mirrors such as `HWLAB_COMMIT_ID`,
|
|
`HWLAB_IMAGE`, `HWLAB_IMAGE_TAG`, and `HWLAB_SKILLS_COMMIT_ID` converge. It
|
|
also blocks if `hwlab-cloud-api` loses the Code Agent provider Secret ref
|
|
`hwlab-code-agent-provider/openai-api-key`, the `OPENAI_API_KEY` env name, or
|
|
the DEV egress proxy base-url env. Without `--check`, `--target-ref` or
|
|
`--target-tag` reports a uniform older desired-state as a read-only promotion
|
|
plan. With `--check`, any explicit target is a hard current-main/commit-pinning
|
|
gate: stale deploy, catalog, workload image, or runtime mirror fields are
|
|
blocked before apply.
|
|
|
|
`deploy/deploy.json` is the deploy truth, but artifact catalog and workload
|
|
refs are part of the same desired-state contract. Promotion updates must move
|
|
all three together by using the refresh command in blocked mode or
|
|
publish-report mode, then run `--target-ref origin/main --check` or the
|
|
promotion commit check. Report files are contextual evidence only and must not
|
|
override these desired-state files.
|
|
|
|
This is source/dry-run support only. It does not prove a registry image exists,
|
|
does not build, pull, push, apply, restart, or touch PROD, and must not be used
|
|
as M3 DEV-LIVE evidence.
|
|
|
|
Next DEV deploy smoke commands, for a separately authorized deployment task:
|
|
|
|
```sh
|
|
npm run check
|
|
node -e "JSON.parse(require('node:fs').readFileSync('deploy/deploy.json','utf8'))"
|
|
kubectl apply --dry-run=server -k deploy/k8s/dev
|
|
curl -fsS http://74.48.78.17:16667/health/live
|
|
node scripts/dev-edge-health-smoke.mjs --live --write-report
|
|
```
|
|
|
|
Do not run PROD deployment or substitute UniDesk backend, provider-gateway, or
|
|
microservice proxy for HWLAB runtime services.
|