ljwx-deploy/release

Release Queue (Legacy Compatibility Only)

release/queue.yaml 已不再是 GitOps v2 的主发布入口。

当前标准链路是：

ReleaseBundle -> ljwx-release-state -> DeployResolution -> deploy-controller-v2 -> ReleaseResult

Flow

1. Service repository publishes immutable ReleaseBundle artifact.
2. ljwx-release-state persists Event / ReleaseBundle / ReleaseRequest / DeployResolution / ReleaseResult.
3. deploy-controller-v2 is the only writer that updates apps/*/overlays/*/kustomization.yaml.
4. Prod image copy is executed by deploy-controller-v2, not by smoke/promoter.
5. release/queue.yaml remains only as an emptied compatibility file for old tooling references.

Superseded Semantics

• superseded is not an error state.
• When multiple pending entries exist for the same service+env, only the newest createdAt remains pending.
• Older pending entries are moved to superseded with supersededAt and reason.

Retry Policy

• Default retry budget N=10.
• If registry readiness check is enabled and digest is not ready, entry is skipped for this cycle (no forced failure).
• Hard processing errors increment attempts; once attempts reach N, item transitions to failed with failedAt and lastError.

Service Mapping

Promoter resolves deployment targets from release/services.yaml:

• overlayPath: Argo application source path file to update.
• kustomizeImageName: image selector in kustomization.yaml.
• harborImage: optional Harbor repository hint for readiness checks and legacy compatibility.
• deployImage: optional explicit runtime repository override.
• argocdApp: app name written into evidence records.

This mapping is the decoupling boundary. Business repos only enqueue queue entries; they do not need deploy path details.

Dual-k3s Same-code Rule

• Use the same queue/evidence/promoter code for both clusters.
• Switch only mapping profile by environment variable:
  • local server k3s: SERVICE_MAP_PATH=release/services.local-k3s.yaml
  • China mainland OrbStack k3s: SERVICE_MAP_PATH=release/services.orbstack-k3s-cn.yaml
• Do not fork promoter logic or queue schema by cluster.

Compatibility Schema

Legacy tools that still read release/queue.yaml expect:

id: "20260302T020000Z-frontend-sha-abc1234"
service: "frontend"
env: "dev"
source:
  image: "harbor.example.com/project/frontend@sha256:..."
  ghcr: "ghcr.io/org/frontend@sha256:..." # optional legacy alias
  tag: "sha-abc1234"
  digest: "sha256:..."
createdAt: "2026-03-02T02:00:00Z"
status: "pending"
attempts: 0
lastError: ""
promotedAt: ""
supersededAt: ""
failedAt: ""