proposal: support canary deployments

[atkrad]

Problem

Blue/green (#33) flips 100% traffic at once. High-traffic services often need a small % of traffic on the new version first, then ramp or abort from metrics.

Deployah has no weighted traffic split. Native Kubernetes alone does not provide automatic canary analysis; Ingress canary annotations, Gateway API, mesh, or controllers (Argo Rollouts / Flagger) are usually required.

Goals

• Spec can select canary (steps / weight / analysis intent) for role: service.
• Clear platform hook for how weights are implemented (Ingress / Gateway / mesh / controller).
• Promote / abort (or auto from analysis when a controller is configured).
• Plan shows canary objects and weights.
• Reuse shared release. UX and deployah release promote|abort|status from proposal: support blue/green deployments #33 where it fits.

Non-goals

• Blue/green Service-slot flip (proposal: support blue/green deployments #33).
• Building a Deployah metrics engine; use Prometheus/analysis templates via platform provider.
• Replacing rolling default for all apps.
• Helm revision rollback as the primary canary abort path (proposal: support deployah rollback #29); prefer weight back to 0 / abort, with Helm rollback as a blunt escape hatch.

Proposed design (sketch)

components:
  api:
    release:
      strategy: canary
      canary:
        steps:
          - setWeight: 10
          - pause: { duration: 5m }
          - setWeight: 50
          - pause: {}                # manual resume
        # analysis: ...              # when controller provider supports it

Platform:

environments:
  production:
    progressiveDelivery:
      provider: none | ingressNginx | gatewayAPI | argoRollouts | flagger | mesh

v1 recommendation: require a platform progressiveDelivery.provider that can do weights; do not fake canary with replica counts alone. Prefer starting after #33 ships shared release CLI, then implement one provider (Ingress-nginx canary annotations or Argo/Flagger) with capability checks.

Relationship to blue/green (#33)

	Blue/green (#33)	Canary (this issue)
Traffic move	0% -> 100%	0% -> N% -> 100%
v1 Deployah	Native Service slots	Needs weight primitive / controller
Rollback	Selector flip	Weight back to 0 / abort
Phase 2 controllers	Optional Argo/Flagger	Often required for analysis-driven canary

Ship #33 first; reuse deployah release promote|abort|status where possible. Share the platform progressiveDelivery block with #33 Phase 2.

Alternatives considered

1. Fold canary into proposal: support blue/green deployments #33. Different primitives (weights vs binary flip); keep separate.
2. Replica-percent canary without traffic split. Misleading; not real request weighting.
3. Mesh-only canary. Valid provider; should not be the only option.

Compatibility and migration

• Additive; default rolling unchanged.
• Design of progressiveDelivery platform block shared with proposal: support blue/green deployments #33 Phase 2.
• Related: proposal: support configuring rolling update strategy #19 (rolling update), proposal: support KEDA event-driven autoscaling #25 (KEDA), proposal: support deployah rollback #29 (Helm rollback escape hatch), proposal: support blue/green deployments #33 (blue/green), mesh proposal: first-class platform service mesh config #23/proposal: developer mesh traffic intent #24.

Test plan

• Provider capability checks
• Scenario for one provider (ingress canary annotations or Rollouts)
• Manual ramp + abort
• Docs: when canary vs blue/green vs rolling

Checklist

• I searched existing issues and discussions
• This includes enough design detail for implementation (not only a wish)