HWLAB Code Queue
112 lines
4.5 KiB
Markdown
112 lines
4.5 KiB
Markdown
# HWLAB DEV Deploy Apply
|
|
|
|
This document records the DEV-only apply/preflight path for
|
|
`pikasTech/HWLAB#33` and the apply-plan/report path for
|
|
`pikasTech/HWLAB#50`. It targets only the D601 `hwlab-dev` namespace and must
|
|
not be used for PROD.
|
|
|
|
## Scope
|
|
|
|
- Work from latest `origin/main`.
|
|
- Read only HWLAB repository deploy inputs: `deploy/deploy.json`,
|
|
`deploy/artifact-catalog.dev.json`, and `deploy/k8s/dev`.
|
|
- Validate artifact identity, image commit tags, Kubernetes workload/service
|
|
shape, DEV health, and cloud-api DB connectivity.
|
|
- Emit an operator-readable plan in `devDeployApply`: plan/apply boundary,
|
|
expected artifact commit, target namespace, workloads, services, remaining
|
|
blockers, minimal manual commands, and rollback hints.
|
|
- Stop before mutation when artifact publish evidence, registry digests,
|
|
`kubectl`, DEV health, or cloud-api DB connectivity are missing.
|
|
|
|
## Commands
|
|
|
|
Run a preflight that is expected to report blockers on the current skeleton:
|
|
|
|
```sh
|
|
node --check scripts/dev-deploy-apply.mjs
|
|
node --check scripts/src/dev-deploy-apply.mjs
|
|
node scripts/dev-deploy-apply.mjs --dry-run --expect-blocked --write-report
|
|
node scripts/validate-dev-gate-report.mjs
|
|
```
|
|
|
|
Run the existing CLI dry-run surface:
|
|
|
|
```sh
|
|
node tools/hwlab-cli/bin/hwlab-cli.mjs test e2e --env dev --mvp --dry-run
|
|
```
|
|
|
|
Only after CI publish evidence and executor prerequisites exist, a real DEV
|
|
apply requires explicit non-production confirmation:
|
|
|
|
```sh
|
|
node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
|
|
```
|
|
|
|
The script refuses PROD flags, secret-read flags, heavyweight e2e flags, and
|
|
force-push flags. It also refuses to apply if the DEV artifact catalog still
|
|
contains skeleton-only unpublished images.
|
|
|
|
## Report Contract
|
|
|
|
The machine-readable result is written to
|
|
`reports/dev-gate/dev-deploy-report.json` when `--write-report` is used. The
|
|
report remains compatible with the #33 DEV gate validator and adds these
|
|
operator fields:
|
|
|
|
- `devDeployApply.conclusion`: `blocked` while blockers are open, otherwise
|
|
`ready` for human approval.
|
|
- `devDeployApply.applyBoundary`: default no-write behavior, required apply
|
|
flags, DEV-only write scope, no-write scope, and forbidden actions.
|
|
- `devDeployApply.artifactPlan`: expected artifact commit, source commit,
|
|
deploy/catalog commit IDs, publish/registry status, and unpublished services.
|
|
- `devDeployApply.target`: DEV endpoint and `hwlab-dev` namespace.
|
|
- `devDeployApply.workloadPlan` and `servicePlan`: planned Kubernetes
|
|
workloads, containers, images, service IDs, ports, and replica intent.
|
|
- `devDeployApply.manualCommands`: dry-run/report commands before human
|
|
approval; the apply command is present only when the plan is ready.
|
|
- `devDeployApply.rollbackHint`: pre-apply capture commands, deployment
|
|
rollbacks, suspended job cleanup, and post-rollback health checks.
|
|
- `devDeployApply.remainingBlockers`: open blockers with concrete unblock
|
|
hints. These do not claim live apply happened.
|
|
|
|
When `conclusion.status` is `blocked`, operators should clear the listed
|
|
`remainingBlockers` and rerun:
|
|
|
|
```sh
|
|
node scripts/dev-deploy-apply.mjs --dry-run --expect-blocked --write-report
|
|
node scripts/validate-dev-gate-report.mjs
|
|
```
|
|
|
|
When `conclusion.status` is `ready`, run the dry-run plan and validator
|
|
immediately before human approval:
|
|
|
|
```sh
|
|
node scripts/dev-deploy-apply.mjs --dry-run --write-report
|
|
node scripts/validate-dev-gate-report.mjs
|
|
```
|
|
|
|
Only after that approval may the DEV-only apply command be used.
|
|
|
|
## Current Result
|
|
|
|
The current `origin/main` deploy contract is blocked for real DEV apply:
|
|
|
|
- `deploy/artifact-catalog.dev.json` says `ciPublished: false`,
|
|
`registryVerified: false`, `publishState: skeleton-only`, and
|
|
`digest: not_published`.
|
|
- The deploy/catalog artifact commit is `24eb3bf`, which does not match the
|
|
current source commit validated for this apply (`1e8d009e9531`).
|
|
- The runner does not provide `kubectl`, so it cannot read or apply the D601
|
|
`hwlab-dev` namespace.
|
|
- The public DEV health probe at `http://74.48.78.17:6667/health/live` is not
|
|
reachable from this runner.
|
|
- `hwlab-cloud-api` now has a DEV DB env contract placeholder:
|
|
`HWLAB_CLOUD_DB_URL` must come from Secret reference
|
|
`hwlab-cloud-api-dev-db/database-url`, and
|
|
`HWLAB_CLOUD_DB_SSL_MODE=require`. The local health gate still reports DB
|
|
runtime config blocked when those env values are absent, and it never prints
|
|
the connection string.
|
|
|
|
No PROD resource, secret value, UniDesk runtime substitute, browser e2e,
|
|
heavyweight e2e, or force push is part of this flow.
|