feat: (cluster) Promotion tasks

[hiddeco]

Fixes: #2827

This pull request introduces the PromotionTask and ClusterPromotionTask resources to Kargo. These new resource types allow you to streamline Stage resources by bundling commonly shared promotion steps into reusable tasks, which can be referenced in promotion templates.

PromotionTask example

---
apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionTask
metadata:
  name: open-pr-and-wait
  namespace: my-project
spec:
  vars:
  - name: repoURL
  - name: sourceBranch
  - name: targetBranch
    value: main
  steps:
  - uses: git-open-pr
    as: open-pr
    config:
      repoURL: ${{ vars.repoURL }}
      createTargetBranch: true
      sourceBranch: ${{ vars.sourceBranch }}
      targetBranch: ${{ vars.targetBranch }}
  - uses: git-wait-for-pr
    as: wait-for-pr
    config:
      repoURL: ${{ vars.repoURL }}
      prNumber: ${{ task.outputs['open-pr'].prNumber }}
  - uses: compose-output
    as: output
    config:
      mergeCommit: ${{ task.outputs['wait-for-pr'].commit }}

Stage example

---
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: staging
  namespace: my-project
spec:
  requestedFreight:
  - origin:
      kind: Warehouse
      name: kargo-demo
    sources:
      direct: true
  promotionTemplate:
    spec:
      vars:
      - name: repoURL
        value: https://github.com/example/repository.git
      - name: srcPath
        value: ./src
      - name: outPath
        value: ./out
      - name: targetBranch
        value: stage/${{ ctx.stage }}
      steps:
      # ...omitted for brevity
      - uses: git-push
        as: push
        config:
          path: ${{ vars.outPath }}
          generateTargetBranch: true
      - task:
          name: open-pr-and-wait
          kind: ClusterPromotionTask
        as: pr
        vars:
        - name: sourceBranch
          value: ${{ outputs.push.branch }}

Full example for testing

https://gist.githubusercontent.com/hiddeco/df2da6a88ad1966642ed6ee94bad9787/raw/a886da867108c4ef970dec2b137e81f6a4b1f6fe/tasks.yaml

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	911cc13
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-io/deploys/678192a4bf0caf000866add8
😎 Deploy Preview	https://deploy-preview-3121.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

Attention: Patch coverage is 78.77095% with 76 lines in your changes missing coverage. Please review.

Project coverage is 51.79%. Comparing base (1313f03) to head (911cc13).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/directives/promotions.go	69.51%	21 Missing and 4 partials ⚠️
internal/directives/output_composer.go	33.33%	16 Missing ⚠️
internal/webhook/promotiontask/webhook.go	33.33%	12 Missing ⚠️
api/v1alpha1/promotion_types.go	0.00%	8 Missing ⚠️
internal/directives/simple_engine_promote.go	53.33%	6 Missing and 1 partial ⚠️
cmd/controlplane/webhooks.go	0.00%	3 Missing ⚠️
internal/webhook/promotion/webhook.go	62.50%	2 Missing and 1 partial ⚠️
internal/api/promote_downstream_v1alpha1.go	85.71%	0 Missing and 1 partial ⚠️
internal/controller/promotions/promotions.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3121      +/-   ##
==========================================
+ Coverage   51.55%   51.79%   +0.23%     
==========================================
  Files         288      291       +3     
  Lines       26188    26460     +272     
==========================================
+ Hits        13502    13705     +203     
- Misses      11960    12026      +66     
- Partials      726      729       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[krancour]

This wasn't introduced by this PR, but this internal/kargo package has been bugging me for a while because I don't feel like the package has a clearly defined purpose. (Maybe it does, and I'm failing to see it.)

If I'm not wrong, there's certainly no need to untangle this knot to get this PR merged, but (again, only if I'm right), I wonder if there's any other place that might be appropriate for the new functionality added to the package, in particular NewPromotionBuilder().

[hiddeco]

The only alternative I can think of is inventing a new promotion package, but I do not really like this alternative either...

[krancour]

We can put a pin in it. Fortunately there are only a couple packages like this that seem to have collected unrelated bits of functionality over time for lack of a better home.

[krancour]

This isn't a new problem, but the PR's making me more aware of it...

It seems that now, as before, we build out a Promo's steps from the template in three places:

1. Promote to Stage API endpoint
2. Promote to downstream Stages API endpoint
3. Auto-Promotion by the Stage reconciler

In all cases, a Promo's steps are defined when it's created.

I'll avoid the question of whether it's better to copy/expand steps when the Promo is created vs being done by the Promo reconciler when the Promo's started (because I could see it both ways and we may have to confront this eventually), but the weird side effect of the Promo reconciler not doing it is that you can't create a Promo with kubectl unless you defined all the steps yourself. There's no way to say: "This Stage, this piece of Freight, and let the controller fill in the steps."

Should we at least have the Promo reconciler build/expand steps just-in-time if a work on a Promo starts and its steps are empty?

[hiddeco]

This is an excellent point, but I wonder if instead of doing this — wouldn't it be better to introduce a modifying webhook?

[krancour]

I think I like that idea best, actually. In this case, we could drop the kargo.NewPromotionBuilder(s.client).Build() from three locations it's in now and just let the mutating webhook handle for all cases? That sounds like a win.

[hiddeco]

We would still need some sort of builder, I think. But the inflation would happen as a secondary step in a single place.

[krancour]

Oh... I didn't mean drop the builder. Just drop three calls to it in favor of one.

[krancour]

🔥