feat: option to replicate shared resources to all project namespaces by jessesuen · Pull Request #5789 · akuity/kargo

jessesuen · 2026-02-25T09:33:29Z

Partially resolves #5788

Adds a new resource replication reconciler to the management controller. Secrets & ConfigMaps in the kargo-shared-resources Namespace, annotated with kargo.akuity.io/replicate-to: "*" are automatically copied into every Project namespace. For example:

apiVersion: v1
kind: Secret
metadata:
  name: my-shared-secret
  namespace: kargo-shared-resources
  annotations:
    kargo.akuity.io/replicate-to: "*"
data:
  foo: dmFsdWUtMg0KDQo=

This enables Argo Rollouts AnalysisTemplates (including Job Pods) to consume them, as it is not possible for cross-namespace secret references.

Key behaviors:

Source resource gets kargo.akuity.io/finalizer finalizer on first reconcile; deletion is blocked until all managed replicas are cleaned up.
Replicated resources carry replicated-from and replicated-sha labels; the SHA label is a 16-char truncated SHA-256 of the resource data.
The replicated-sha label is used to detect and optimize when content updates are necessary to be copied to replicated resources. If sha is the same, the update is skipped.
User-created resources with the same name (no replicated-from label) are left untouched (conflict avoidance).
Removing the replicate-to annotation triggers the same cleanup path as source secret deletion.
A Project watch handler re-enqueues all annotated source secrets when a new Project appears, ensuring immediate replication.

Remaining work:

Documentation
Mutating Webhook should prevent modifications to replicated resources
UI checkbox option for replicating a resource

Adds a new shared-secrets replication reconciler to the management controller. Secrets in kargo-shared-resources annotated with kargo.akuity.io/replicate-to: "*" are automatically copied into every Project namespace, enabling Argo Rollouts AnalysisTemplates (and Job Pods) to consume them without cross-namespace secret references. Key behaviors: - Source secret gets kargo.akuity.io/replicated finalizer on first reconcile; deletion is blocked until all managed replicas are cleaned up. - Replicated secrets carry replicated-from and replicated-sha labels; the SHA label is a 16-char truncated SHA-256 of the secret data used to detect external modifications. - Externally modified replicas are never overwritten or deleted. - User-created secrets with the same name (no replicated-from label) are left untouched (conflict avoidance). - Removing the replicate-to annotation triggers the same cleanup path as source secret deletion. - A Project watch handler re-enqueues all annotated source secrets when a new Project appears, ensuring immediate replication. - Orphaned replicas in non-project namespaces are pruned on each reconcile pass. - kargo-shared-resources is now always included in the management controller's Secret namespace cache, independent of the legacy migration controller. Signed-off-by: Jesse Suen <jesse@akuity.io>

Signed-off-by: Jesse Suen <jesse@akuity.io>

- computeDataHash now factors in labels and annotations (excluding replication-managed labels and kubectl/replicate-to annotations) - syncToProjectNamespace carries source labels and annotations to replicas - List call in Reconcile filters to out-of-date replicas only (replicated-sha notin [sourceHash]) to skip unnecessary updates - Remove orphaned-namespace cleanup: Project deletion cascades to the namespace, which deletes replicated Secrets automatically Signed-off-by: Jesse Suen <jesse@akuity.io>

…nd ConfigMaps Signed-off-by: Jesse Suen <jesse@akuity.io>

…n on startup Signed-off-by: Jesse Suen <jesse@akuity.io>

Signed-off-by: Jesse Suen <jesse@akuity.io>

netlify · 2026-02-25T09:33:36Z

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	`6fcc80a`
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/699ec1ede578c400078842bf
😎 Deploy Preview	https://deploy-preview-5789.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 project configuration.

jessesuen · 2026-02-25T09:40:34Z

In addition to the unit tests, this was manually tested end-to-end to cover various corner cases, including:

adding the annotation after creation
removing the annotation after creation
removing the annotation while the controller was down, ensuring it cleaned up when it came back up
creating a project when controller was down, ensuring Secrets/Configmaps were created when it came back up
modifying the contents of the Secret/Configmap

jessesuen · 2026-02-25T09:52:39Z

api/v1alpha1/annotations.go

+	// AnnotationValueReplicateToAll is the annotation value for
+	// AnnotationKeyReplicateTo that causes a resource to be replicated to all
+	// Project namespaces.
+	AnnotationValueReplicateToAll = "*"


I am considering introducing an annotation, kargo.akuity.io/replicated-at: 2026-02-25T01:49:00Z timestamp to indicate when the resource was replicated. This might help end user (or even kargo devs) debug when things changed (e.g., if an admin updated the Secret/ConfigMap from underneath an AnalysisRun).

EronWright · 2026-02-25T17:34:21Z

pkg/controller/management/replication/replication.go

+
+	if existing == nil {
+		// Either no replica exists yet, or it already has the current SHA
+		// (filtered out by the List). Try to create; handle AlreadyExists.


Is it necessary to call Create in the case where the replicated object exists with a matching SHA? If you were to not filter it, and compare the SHA here (which I see you do anyway later), could the Create call be avoided?

I think you are right about this. I think this logic used to make sense before I added an optimization in the list query. I will revisit this.

EronWright · 2026-02-25T17:35:12Z

pkg/controller/management/replication/replication.go

+
+	// Sync to each project namespace.
+	for ns := range projectNamespaces {
+		if err := r.syncToProjectNamespace(ctx, srcObj, ns, sourceHash, existingByNamespace[ns]); err != nil {


nit: parallelize

pkg/controller/management/replication/replication.go

EronWright · 2026-02-25T17:46:36Z

pkg/controller/management/replication/replication.go

+		destObj.SetLabels(replicaLabels(src, sourceHash))
+		destObj.SetAnnotations(replicaAnnotations(src))
+		r.adapter.copyFields(destObj, src)
+		if err := r.client.Create(ctx, destObj); err != nil {


nit: set the FieldManager

jessesuen added 8 commits February 24, 2026 18:43

chore: fix linting issues

0a9d50f

Signed-off-by: Jesse Suen <jesse@akuity.io>

feat(management): generalize shared resource replication to Secrets a…

c71b3a9

…nd ConfigMaps Signed-off-by: Jesse Suen <jesse@akuity.io>

fix(replication): reconcile resources with finalizer but no annotatio…

bd412ae

…n on startup Signed-off-by: Jesse Suen <jesse@akuity.io>

refactor: reuse existing finalizer

2838a27

Signed-off-by: Jesse Suen <jesse@akuity.io>

fix: only reconcile secrets that are labeled properly

33721c9

Signed-off-by: Jesse Suen <jesse@akuity.io>

refactor: reorganize adapters into separate files

6fcc80a

Signed-off-by: Jesse Suen <jesse@akuity.io>

jessesuen requested a review from a team as a code owner February 25, 2026 09:33

jessesuen commented Feb 25, 2026

View reviewed changes

EronWright reviewed Feb 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: option to replicate shared resources to all project namespaces#5789

feat: option to replicate shared resources to all project namespaces#5789
jessesuen wants to merge 8 commits intoakuity:mainfrom
jessesuen:feat/replication

jessesuen commented Feb 25, 2026 •

edited

Loading

Uh oh!

netlify bot commented Feb 25, 2026 •

edited

Loading

Uh oh!

jessesuen commented Feb 25, 2026 •

edited

Loading

Uh oh!

jessesuen Feb 25, 2026

Uh oh!

EronWright Feb 25, 2026 •

edited

Loading

Uh oh!

jessesuen Feb 25, 2026

Uh oh!

EronWright Feb 25, 2026

Uh oh!

Uh oh!

EronWright Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jessesuen commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-kargo-io ready!

Uh oh!

jessesuen commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jessesuen Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

EronWright Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jessesuen Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

EronWright Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

EronWright Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jessesuen commented Feb 25, 2026 •

edited

Loading

netlify bot commented Feb 25, 2026 •

edited

Loading

jessesuen commented Feb 25, 2026 •

edited

Loading

EronWright Feb 25, 2026 •

edited

Loading