|
|
|
@@ -25,9 +25,44 @@ truth.
|
|
|
|
|
| Stage | Current HWLAB state | Required next behavior |
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
| 1. Long-term reference | This file records DEV deployment, Cloud Web publish, API/edge/health, frp, D601 registry, k3s rollout, rollback, and verification rules. `AGENTS.md` indexes it. | Keep process issues as sources only; update this reference when a deployment rule changes. |
|
|
|
|
|
| 2. CLI or controlled scripts | Existing controlled entrypoints cover contract planning, desired-state planning, artifact publish, DEV apply/report, k3s read-only visibility, and Cloud Web checks. Rollback is documented as commands/report hints but is not yet one unified CLI command. | Converge check, plan, publish, apply, rollback, status, and verify into HWLAB CLI or a small controlled script surface backed by `deploy/deploy.json`. |
|
|
|
|
|
| 2. CLI or controlled scripts | `scripts/dev-cd-apply.mjs` is the only formal DEV CD side-effect entrypoint for publish, desired-state refresh, apply, and live verify. Other controlled scripts still cover contract planning, dry-run planning, preflight, single-step internals, k3s read-only visibility, and Cloud Web checks. Rollback is documented as commands/report hints but is not yet one unified CLI command. | Converge check, plan, rollback, status, and verify into HWLAB CLI while preserving the single transaction lock for side effects backed by `deploy/deploy.json`. |
|
|
|
|
|
| 3. UniDesk CI/CD plus images | DEV services are imageized and published to the D601 registry. D601 rollout still includes manual bridge steps for Cloud Web and frp/k3s execution. | Move build, publish, desired-state refresh, rollout, post-deploy validation, and report upload into standard UniDesk CI/CD jobs without replacing HWLAB runtime. |
|
|
|
|
|
|
|
|
|
|
## DEV CD Transaction
|
|
|
|
|
|
|
|
|
|
The stable DEV CD side-effect command is:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This command is the only formal path that may publish DEV artifacts, refresh
|
|
|
|
|
desired-state from the publish report, apply to `hwlab-dev`, and verify public
|
|
|
|
|
`16666/16667` in one run. It reads `deploy/deploy.json` at transaction start,
|
|
|
|
|
records the manifest hash and target commit, acquires
|
|
|
|
|
`Lease/hwlab-dev/hwlab-dev-cd-lock`, runs the internal steps serially, writes
|
|
|
|
|
`reports/dev-gate/dev-cd-apply.json`, and releases the Lease.
|
|
|
|
|
|
|
|
|
|
The Lease is a deployment-plane mutex, not a desired-state source. Its
|
|
|
|
|
annotations record at least `promotionCommit`, `deployJsonHash`,
|
|
|
|
|
`ownerTaskId`, `transactionId`, `phase`, `startedAt`, `updatedAt`,
|
|
|
|
|
`ttlSeconds`, `liveBefore`, and `targetNamespace`. `deploy/deploy.json`,
|
|
|
|
|
`deploy/artifact-catalog.dev.json`, and `deploy/k8s/base/workloads.yaml`
|
|
|
|
|
remain the only authoritative deploy inputs.
|
|
|
|
|
|
|
|
|
|
If another transaction holds the Lease, the command must stop before publish or
|
|
|
|
|
apply with structured `deploy-lock-held` output that includes holder,
|
|
|
|
|
promotion commit, phase, target namespace, and retry seconds. Expired locks are
|
|
|
|
|
not silently overwritten; taking over a stale lock requires both
|
|
|
|
|
`--break-stale-lock` and `--confirm-dev`, and the previous holder is retained
|
|
|
|
|
in audit annotations/report fields.
|
|
|
|
|
|
|
|
|
|
The old side-effect commands are now internal transaction steps. Direct manual
|
|
|
|
|
use of `scripts/dev-artifact-publish.mjs --publish` or
|
|
|
|
|
`scripts/dev-deploy-apply.mjs --apply` without `HWLAB_CD_TRANSACTION_ID` is
|
|
|
|
|
rejected with `cd-transaction-required`; preflight, build, dry-run, check, and
|
|
|
|
|
read-only modes remain available.
|
|
|
|
|
|
|
|
|
|
## Artifact Publish
|
|
|
|
|
|
|
|
|
|
DEV artifacts publish to the D601 local/internal registry:
|
|
|
|
@@ -36,18 +71,22 @@ DEV artifacts publish to the D601 local/internal registry:
|
|
|
|
|
127.0.0.1:5000/hwlab/*
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The stable publish command is:
|
|
|
|
|
The single-step publish command is a transaction-internal side-effect step:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
node scripts/dev-artifact-publish.mjs --publish
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For a single Cloud Web image:
|
|
|
|
|
It only runs in side-effect mode when `HWLAB_CD_TRANSACTION_ID` is set by
|
|
|
|
|
`scripts/dev-cd-apply.mjs`. Use `node scripts/dev-cd-apply.mjs --apply
|
|
|
|
|
--confirm-dev --confirmed-non-production --write-report` for normal DEV CD.
|
|
|
|
|
|
|
|
|
|
For Cloud Web source freshness before the transaction:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
node web/hwlab-cloud-web/scripts/check.mjs
|
|
|
|
|
node web/hwlab-cloud-web/scripts/build.mjs
|
|
|
|
|
node scripts/dev-artifact-publish.mjs --publish --services hwlab-cloud-web
|
|
|
|
|
node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Cloud Web must build `web/hwlab-cloud-web/dist` before publish because the
|
|
|
|
@@ -130,7 +169,12 @@ services may still use internal `6667`.
|
|
|
|
|
|
|
|
|
|
## Cloud Web Manual DEV Rollout
|
|
|
|
|
|
|
|
|
|
The verified manual path for `hwlab-cloud-web` is:
|
|
|
|
|
This section is retained as historical operational baseline for what the
|
|
|
|
|
transaction reproduces. New DEV side effects should use
|
|
|
|
|
`scripts/dev-cd-apply.mjs`; do not bypass the Lease with ad hoc publish,
|
|
|
|
|
`kubectl set image`, or restart commands.
|
|
|
|
|
|
|
|
|
|
The previous verified manual path for `hwlab-cloud-web` was:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
cd /home/ubuntu/workspace/hwlab
|
|
|
|
@@ -141,6 +185,9 @@ KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev set image deployment/h
|
|
|
|
|
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev rollout status deployment/hwlab-cloud-web --timeout=180s
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
That historical sequence is no longer the normal side-effect path; direct
|
|
|
|
|
`--publish` is rejected unless it is called by the transaction.
|
|
|
|
|
|
|
|
|
|
The rollout must use D601 native k3s:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
@@ -171,16 +218,18 @@ scroll, and an internal Markdown help surface. The frontend contract is
|
|
|
|
|
|
|
|
|
|
## Apply Boundary
|
|
|
|
|
|
|
|
|
|
`scripts/dev-deploy-apply.mjs` is the DEV-only apply/report path. A real apply
|
|
|
|
|
requires explicit non-production flags:
|
|
|
|
|
`scripts/dev-deploy-apply.mjs` is the DEV-only apply/report backend. A real
|
|
|
|
|
apply requires the transaction environment created by `scripts/dev-cd-apply.mjs`
|
|
|
|
|
plus explicit non-production flags:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The apply path must stop before mutation when artifact evidence, registry
|
|
|
|
|
digests, kube access, DEV health, or required runtime readiness are missing.
|
|
|
|
|
It must not read secret values or target PROD.
|
|
|
|
|
Direct manual `--apply` calls without `HWLAB_CD_TRANSACTION_ID` return
|
|
|
|
|
`cd-transaction-required`. The apply path must stop before mutation when
|
|
|
|
|
artifact evidence, registry digests, kube access, DEV health, or required
|
|
|
|
|
runtime readiness are missing. It must not read secret values or target PROD.
|
|
|
|
|
|
|
|
|
|
Suspended template Jobs are immutable in `spec.template`. Only the explicit
|
|
|
|
|
DEV allowlist may be replaced by the apply script:
|
|
|
|
@@ -220,9 +269,10 @@ use the repo-owned scripts below instead of ad hoc shell fragments.
|
|
|
|
|
| Check deployment contract and FRP/endpoint drift | `node scripts/deploy-contract-plan.mjs --check` | Fold into `hwlab deploy check --env dev`. |
|
|
|
|
|
| Plan desired image/workload state | `node scripts/deploy-desired-state-plan.mjs --plan --pretty` and `node scripts/deploy-desired-state-plan.mjs --promotion-commit <sha> --check` | Fold into `hwlab deploy plan --env dev --file deploy/deploy.json` with a promotion commit gate. |
|
|
|
|
|
| Preflight artifact publish | `node scripts/dev-artifact-publish.mjs --preflight` | Keep as backend for `hwlab artifact publish --preflight`. |
|
|
|
|
|
| Publish DEV images | `node scripts/dev-artifact-publish.mjs --publish` | CI job should run this and upload digest reports. |
|
|
|
|
|
| Refresh catalog/desired state | `node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json` | Make refresh an explicit CLI/CD step after publish. |
|
|
|
|
|
| Apply DEV rollout | `node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report` | Keep apply behind confirmation flags and route through CLI/CD approval. |
|
|
|
|
|
| Publish/apply/verify DEV | `node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report` | Keep as the single side-effect transaction and run from repo-owned DEV CI/CD. |
|
|
|
|
|
| Publish DEV images | `node scripts/dev-artifact-publish.mjs --publish` inside `HWLAB_CD_TRANSACTION_ID` | Internal step only; direct side-effect calls are rejected. |
|
|
|
|
|
| Refresh catalog/desired state | `node scripts/refresh-artifact-catalog.mjs --target-ref origin/main --publish-report reports/dev-gate/dev-artifacts.json` | Internal transaction step after publish; read/write desired-state only from repo files. |
|
|
|
|
|
| Apply DEV rollout | `node scripts/dev-deploy-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report` inside `HWLAB_CD_TRANSACTION_ID` | Internal transaction step; direct side-effect calls are rejected. |
|
|
|
|
|
| Roll back DEV Deployment | `kubectl -n hwlab-dev rollout undo deployment/<name>` with explicit D601 kubeconfig | Add `hwlab deploy rollback --env dev --service <id> --to-revision <n>`. |
|
|
|
|
|
| Verify status | `curl` checks plus `node scripts/d601-k3s-readonly-observability.mjs` | Add `hwlab deploy verify --env dev --write-report`. |
|
|
|
|
|
|
|
|
|
|
Code Queue Review