feat: (cluster) Promotion tasks

[hiddeco]

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	2ca2524
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-io/deploys/6781133e5754630008f417fd
😎 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 76.84887% with 72 lines in your changes missing coverage. Please review.

Project coverage is 51.49%. Comparing base (db17a2a) to head (8a79c51).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/directives/promotions.go	66.15%	18 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/kargo/promotion_builder.go	97.95%	2 Missing and 1 partial ⚠️
internal/controller/promotions/promotions.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3121      +/-   ##
==========================================
+ Coverage   51.27%   51.49%   +0.21%     
==========================================
  Files         285      288       +3     
  Lines       25706    25944     +238     
==========================================
+ Hits        13182    13360     +178     
- Misses      11824    11881      +57     
- Partials      700      703       +3     

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

[krancour]

Since we only built out enough of promoCtx to get us through this, promotCtx.State will be empty. I suppose that's actually ok in this (pardon the overload) context?

[hiddeco]

Yes, I think so but it may have been better to use an explicit nil here.

[krancour]

Explicit nil sgtm, maybe with a brief comment about why that arg is unimportant in this context?

Really this is a nit... so however you want to deal with it is fine, even if it's do nothing.

[hiddeco]

Upon closer inspection, I do think we need to pass some state here. In addition, I have also a vague suspicion we may actually need the outputs as well while evaluating the individual fields because theoretically, the values can not just originate from variables.

[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]

Making sure I understand the rational for having InflateSteps() separate from Build()...

I presume that by not having Build() automatically inflate, we are preserving the possibility of a Promo having been defined manually and submitted via kubectl, in which case, building isn't necessary, but expansion is?

[hiddeco]

Build is for creating a Promotion based on a Stage (or rather, the Promotion template within). Which we do in several places, either through the API or CLI.

InflateSteps is what always happens on the server-side, and ensures that even if a Promotion would be created through kubectl (as you suggest) — we still handle the core logic of correctly inflating any references we find into actual steps.

[krancour]

Ok... so I agree with the rationale for keeping them separate, but is there any reason we inflate server side, but we don't build server side?

Could the mutating webhook we discussed build if steps == nil and then inflate unconditionally? As opposed to calling build in several different places?

[hiddeco]

We discussed this offline, and partly because of debugging reasons and introducing too many sprinkles of magic. It is better to keep the builder in place so you have some (meaningful) YAML to hold on to.

[krancour]

Is there any edge case here where we lose anything important through the use of maps?

I'm thinking something like this, which seems dumb but possible, might be such a case?

vars:
- name: foo
  value: bar
- name: foo
  value: ${{ vars.foo + vars.foo }}

[krancour]

The second would clobber the first in the map, but the result would be an error, I think, instead of "barbar".

[hiddeco]

This is still an issue, the plan is to inflate them as:

1. task-level vars
2. task-step-level vars

Which would allow the task-step-level to overwrite (or utilize) the task-level variable.

The only concern I have with this approach is that the promotion-level variables then can not overwrite the task-level (default) variables, because they are evaluated before any of the variables in the above list (and a task-level variable with the same name would thus overwrite this value).

[krancour]

Same question about maps as here.

[jessesuen]

While I know ClusterPromotionTask is technically accurate, I wonder if we want to term this "GlobalPromotionTask". We already refer to credentials and ServiceAccounts that are to be used in a global capacity as "global" credentials and global serviceaccounts, and this would be along those lines.

The "cluster" is less meaningful since kargo is not really used in a workload cluster.