feat(api): make PromotionTemplate dedicated resource

[hiddeco]

Fixes: #2827

This makes the PromotionTemplate a namespaced resource and allows it to be referenced in a Stage in addition to being embedded. By doing this, and in combination with the support for variables introduced in Kargo 1.1.x, promotions that are the same across Stages can now avoid duplication.

For example:

---
apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionTemplate
metadata:
  name: promote-to-stage
  namespace: guestbook
spec:
  vars:
  - name: gitRepo
    value: https://github.com/example/guestbook.git
  - name: srcPath
    value: ./src
  - name: outPath
    value: ./out
  - name: targetBranch
    value: stage/${{ ctx.stage }}
  steps:
  - uses: git-clone
    config:
      repoURL: ${{ vars.gitRepo }}
      checkout:
      - fromFreight: true
        path: ${{ vars.srcPath }}
      - branch: ${{ vars.targetBranch }}
        create: true
        path: ${{ vars.outPath }}
  - uses: git-clear
    config:
      path: ${{ vars.outPath }}
  - uses: kustomize-set-image
    as: update-image
    config:
      path: ${{ vars.srcPath }}/base
      images:
      - image: public.ecr.aws/nginx/nginx
  - uses: kustomize-build
    config:
      path: ${{ vars.srcPath }}/stages/${{ ctx.stage }}
      outPath: ${{ vars.outPath }}
  - uses: git-commit
    as: commit
    config:
      path: ${{ vars.outPath }}
      messageFromSteps:
      - update-image
  - uses: git-push
    config:
      path: ${{ vars.outPath }}
      targetBranch: ${{ vars.targetBranch }}
  - uses: argocd-update
    config:
      apps:
      - name: example-${{ ctx.stage }}
        sources:
        - repoURL: ${{ vars.gitRepo }}
          desiredCommit: ${{ outputs.commit.commit }}
---
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: dev
  namespace: guestbook
spec:
  # ...omitted for brevity
  promotionTemplateRef:
    name: promote-to-stage
---
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: staging
  namespace: guestbook
spec:
  # ...omitted for brevity
  promotionTemplateRef:
    name: promote-to-stage

Note: While working on this, I could think of two future improvements people may desire:

1. The ability to provide "last mile" variables, to e.g. overwrite PromotionTemplate defaults and/or provide Stage-specific variables which are hard to derive based on the context. For example, because the folder structure is not set up to equal or incorporate Stage names.
2. Conditional execution of steps, i.e. being able to define an if on a step to only execute if ctx.stage == "dev". This would allow a PromotionTemplate to be used for a wider set of Stages and could further avoid duplication and/or a desire to do "compositions" as is being opted in [Feature Idea/Suggestion] promotionTemplates as a CRD of its own? #2827.

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	56368c3
🔍 Latest deploy log	https://app.netlify.com/sites/docs-kargo-io/deploys/674f24b822fb9b0008e172c4
😎 Deploy Preview	https://deploy-preview-3022.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 52.47525% with 48 lines in your changes missing coverage. Please review.

Project coverage is 51.11%. Comparing base (bfd30f1) to head (2934704).
Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/controller/stages/regular_stages.go	34.78%	12 Missing and 3 partials ⚠️
internal/webhook/promotiontemplate/webhook.go	33.33%	12 Missing ⚠️
internal/api/promote_downstream_v1alpha1.go	62.96%	8 Missing and 2 partials ⚠️
internal/api/promote_to_stage_v1alpha1.go	64.70%	5 Missing and 1 partial ⚠️
cmd/controlplane/webhooks.go	0.00%	3 Missing ⚠️
api/v1alpha1/stage_types.go	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3022      +/-   ##
==========================================
+ Coverage   51.07%   51.11%   +0.04%     
==========================================
  Files         283      284       +1     
  Lines       25382    25474      +92     
==========================================
+ Hits        12963    13022      +59     
- Misses      11720    11751      +31     
- Partials      699      701       +2     

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

[jessesuen]

Instead of a single ref, I think we should support chaining together multiple, so they can be composed

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: staging
  namespace: guestbook
spec:
  steps:
  - templateRef:
      name: precheck-stuff
  - templateRef:
      name: gitops-stuff
  - uses: http
      config:
         url: http://foo.com/
  - templateRef:
      name: notification-stuff

[krancour]

Safe to close, knowing #3121 is the new direction?