Codex
60 lines
4.5 KiB
Markdown
60 lines
4.5 KiB
Markdown
# DevOps Hygiene
|
|
|
|
This document is the authoritative source for UniDesk deployment hygiene: Git-backed deployment truth, dirty-environment boundaries, bounded manual operations and CI source-auth rules. If the same hygiene rule would need edits in `docs/reference/dev-environment.md`, `docs/reference/deploy.md`, `docs/reference/ci.md`, `docs/reference/dev-ci-runner.md`, `docs/reference/deployment.md`, `AGENTS.md` or `TEST.md`, keep the detailed rule here and leave only a cross-reference elsewhere.
|
|
|
|
## Source Of Truth
|
|
|
|
UniDesk deployment state is healthy only when all three layers point back to pushed Git commits:
|
|
|
|
- Desired state: `origin/master:deploy.json`, `config.json` and committed service manifests.
|
|
- Runtime state: live service metadata, image tags, Deployment annotations/env stamps or Compose labels that identify the deployed commit.
|
|
- Verification state: `deploy plan`, health checks, `server status`, service proxy checks and CI/e2e results that agree with the desired commit.
|
|
|
|
Local worktrees, D601 runtime files, copied scripts, copied images, ad-hoc Kubernetes objects and one-off curl results are never deployment truth.
|
|
|
|
## Prohibited Deployment Truth
|
|
|
|
The following practices are not acceptable as the long-term or hidden source of a working environment:
|
|
|
|
- Hand editing D601 runtime files, k3s manifests, ConfigMaps, Deployments or container env values and treating the live result as source of truth.
|
|
- Rebuilding backend-core, frontend, k3sctl-adapter or other managed services from a dirty worktree on the master server, D601 or an operator machine.
|
|
- Copying large local shell scripts, generated manifests, Docker images or application source to D601 as the main deployment mechanism.
|
|
- Fixing dev or production reachability by adding direct D601 public ports, NodePorts or backend-core hardcoded service entries instead of updating the proper catalog/control bridge.
|
|
- Treating `server rebuild backend-core` as a Rust backend-core iteration path; Rust build/check belongs to D601 dev deploy or D601 CI only.
|
|
- Considering manual curl, kubectl or Docker checks sufficient when live commit metadata, deploy plan, health checks and CI/e2e disagree.
|
|
|
|
## Bounded Manual Operations
|
|
|
|
Manual operations are allowed only when they are narrow, visible and followed by commit-based verification:
|
|
|
|
- `server rebuild dev-frontend-proxy` may update the thin main-server nginx proxy for the public dev UI port; it must not build backend/frontend application code.
|
|
- `deploy apply --service k3sctl-adapter` may update the k3s control bridge catalog through the documented local manifest exception in `docs/reference/deploy.md`.
|
|
- Host SSH/provider-gateway dispatch may start the `ci run-dev-e2e` short launcher described in `docs/reference/dev-ci-runner.md`; it must not carry large shell bodies or become a general deployment path.
|
|
- Read-only smoke checks such as `curl http://74.48.78.17:18083/health`, `server status`, `microservice proxy .../health` and `kubectl get` may validate state, but they do not replace desired-state and live-commit verification.
|
|
|
|
If a manual repair is needed to unblock the platform, the durable fix must be committed and pushed, then redeployed or revalidated through the normal path. Do not preserve the repair only as hidden runtime state.
|
|
|
|
## CI And Private Source Auth
|
|
|
|
Private repository access is part of the CI contract. `ci run` must not rely on unauthenticated HTTPS clone, an operator's local dirty worktree or an ad-hoc secret copied by hand into one PipelineRun.
|
|
|
|
Acceptable source access implementations are:
|
|
|
|
- a first-class CI Git credential installed by `ci install` and referenced by the Tekton Pipeline;
|
|
- an in-cluster Git mirror managed by UniDesk; or
|
|
- the same commit-pinned host-fetch boundary used by `ci run-dev-e2e`, where D601 fetches the manifest commit and passes only verified inputs into Tekton.
|
|
|
|
If a CI repo-check task fails at `git clone` because credentials are unavailable, classify it as a CI infrastructure/auth gap, not as an application test failure.
|
|
|
|
## Verification Priority
|
|
|
|
When checks disagree, use this priority order:
|
|
|
|
1. The pushed desired commit and `deploy.json`/manifest contract.
|
|
2. Live runtime metadata proving which commit is deployed.
|
|
3. Controlled health checks and service proxy checks for the same runtime object.
|
|
4. CI/e2e results tied to the same commit.
|
|
5. Manual curl/kubectl output as supporting evidence only.
|
|
|
|
A passing lower-priority manual check cannot override a higher-priority mismatch. Fix the desired state, deploy path, runtime metadata or CI infrastructure until all layers agree.
|