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:16667/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.