How to handle stage specific application configuration changes over Kargo

[rklonner]

I understand the concept of using Kargo to promote changes of a "base" configuration through stages.

However, I am not sure how to cleanly do this within Kargo for bringing stage specific changes in. I know that this is not happening regularly but as the rendered manifests are saved on branches created by Kargo I think it should be managed in a visible way over Kargo.

Let's use the kargo-demo example and assume we want to change the configmap in the uat stage
https://github.com/akuity/kargo-demo/blob/main/stages/uat/configmap.yaml

This change will only come in when running the steps in the PromotionTask for the uat stage and kustomize build is executed and committed to the uat branch.

Reapplying the same freight that is already on uat feels not right as I bring in this changes "only" implicitly.

Would I have to create warehouses for every stage to "subscribe" to this configuration for changes?

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  annotations:
    kargo.akuity.io/refresh: "2025-12-24T13:45:41Z"
  name: staging-config
  namespace: kargo-demo
spec:
  freightCreationPolicy: Automatic
  interval: 5m0s
  subscriptions:
  - git:
      branch: main
      commitSelectionStrategy: NewestFromBranch
      discoveryLimit: 20
      includePaths:
      - stages/uat/
      repoURL: https://github.com/akuity/kargo-demo.git

and make it a direct source for the uat stage along with the other requsted freight that will come from the upstream stage like so:

spec:
  promotionTemplate:
    spec:
      steps:
      - task:
          name: promote
  requestedFreight:
  - origin:
      kind: Warehouse
      name: kargo-demo
    sources:
      stages:
      - dev
  - origin:
      kind: Warehouse
      name: staging-config
    sources:
      direct: true

For only staging this would conceptionally look like this - an additional warehouse attached per stage (image is taken from a different experiment but shows what I mean)

It also feels like a bit of an overhead, especially if one does have a lot of stages and multiple different prod stages.

I wanted to ask if the community is implementing it that way or if I am missing something.

Many thanks in advance.

[bhoppeadoy]

@rklonner I came in here with the same question. Have you made any progress on how to handle this?

To expand, if you're testing a new property that is environment specific, You add it to the stages/dev/ configuration. This now becomes freight and you can promote it to the dev stage, which which will render the manifests for dev.

After testing in dev, we now need to add the property to stages/uat configuration. With the current flow, adding this will create a new freight that only dev stage sees. So you have to promote it to dev (which doesn't actually do anything in dev), then promote it again to stage in order for it to render the manifests for uat.

For production, you have to repeat the same thing 3 more times. Doesn't seem very effecient.

[krancour]

Personally, I probably would give each Stage its own secondary Warehouse. The DAG might look a bit disorderly, but it's an accurate model of what you're trying to achieve.

[rklonner]

@bhoppeadoy: Yes this is exactly what I mean and I did not make any progress here.

@krancour: Thanks for having a look and confirming that the approach with the stage specific additional warehouses seems to be the way to go.

[david-curran-90]

@rklonner
We actually have a templating framework that puts the stage specific configuration in place. Kargo is used as the initiator for this process when it creates the PR and does some other things besides

Have you looked into using configmaps to hold the stage specific config? https://docs.kargo.io/user-guide/reference-docs/expressions#configmapname Could achieve what you want without the ugly DAG?

[bhoppeadoy]

@david-curran-90
Can you explain more on your approach?

From looking at this, to make it work you would have to create a configmap within the kargo project namespace before using it. I don't see how this would work as the configmaps that we use to hold stage specific config are dynamically generated from helm charts during promotion.