pikasTech-HWLAB/docs/dev-deploy-apply.md

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:

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:

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:

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:

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:

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 has no DEV DB connection configuration and its local health payload reports db.connected: false.

No PROD resource, secret value, UniDesk runtime substitute, browser e2e, heavyweight e2e, or force push is part of this flow.