rackerlabs · cardoe · Mar 31, 2026 · Mar 31, 2026
diff --git a/charts/argocd-understack/templates/_helpers.tpl b/charts/argocd-understack/templates/_helpers.tpl
@@ -121,6 +121,20 @@ Usage in source path:
 {{- end -}}
 {{- end }}
 
+{{/*
+Render a labels block for ArgoCD Application resources from .Values.appLabels.
+Produces nothing when appLabels is empty or unset.
+
+Usage:
+  {{- include "understack.appLabelsBlock" $ | nindent 2 }}
+*/}}
+{{- define "understack.appLabelsBlock" -}}
+{{- with .Values.appLabels }}
+labels:
+{{- toYaml . | nindent 2 }}
+{{- end -}}
+{{- end }}
+
 {{/*
 Check if a component is enabled by walking the configuration hierarchy.
 Supports both "global" and "site" scopes with appropriate kill switches.

diff --git a/charts/argocd-understack/templates/application-argo-events-workflows.yaml b/charts/argocd-understack/templates/application-argo-events-workflows.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: argo-events

diff --git a/charts/argocd-understack/templates/application-argo-events.yaml b/charts/argocd-understack/templates/application-argo-events.yaml
@@ -7,6 +7,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: argo-events

diff --git a/charts/argocd-understack/templates/application-argo-workflows.yaml b/charts/argocd-understack/templates/application-argo-workflows.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: argo

diff --git a/charts/argocd-understack/templates/application-cdn.yaml b/charts/argocd-understack/templates/application-cdn.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: understack-cdn

diff --git a/charts/argocd-understack/templates/application-cert-manager.yaml b/charts/argocd-understack/templates/application-cert-manager.yaml
@@ -13,6 +13,7 @@ metadata:
     # cert-manager is critical for a number of other charts so sync
     # it right after CRDs and before the default 0 wave
     argocd.argoproj.io/sync-wave: "-1"
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: cert-manager

diff --git a/charts/argocd-understack/templates/application-chrony.yaml b/charts/argocd-understack/templates/application-chrony.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: openstack

diff --git a/charts/argocd-understack/templates/application-cilium.yaml b/charts/argocd-understack/templates/application-cilium.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: cilium

diff --git a/charts/argocd-understack/templates/application-cluster-issuer.yaml b/charts/argocd-understack/templates/application-cluster-issuer.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: cert-manager

diff --git a/charts/argocd-understack/templates/application-cnpg-system.yaml b/charts/argocd-understack/templates/application-cnpg-system.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: cnpg-system

diff --git a/charts/argocd-understack/templates/application-dex.yaml b/charts/argocd-understack/templates/application-dex.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: dex

diff --git a/charts/argocd-understack/templates/application-envoy-configs.yaml b/charts/argocd-understack/templates/application-envoy-configs.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: envoy-gateway

diff --git a/charts/argocd-understack/templates/application-envoy-gateway.yaml b/charts/argocd-understack/templates/application-envoy-gateway.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: envoy-gateway

diff --git a/charts/argocd-understack/templates/application-etcdbackup.yaml b/charts/argocd-understack/templates/application-etcdbackup.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: kube-system

diff --git a/charts/argocd-understack/templates/application-external-dns.yaml b/charts/argocd-understack/templates/application-external-dns.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: external-dns

diff --git a/charts/argocd-understack/templates/application-external-secrets.yaml b/charts/argocd-understack/templates/application-external-secrets.yaml
@@ -10,6 +10,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: external-secrets

diff --git a/charts/argocd-understack/templates/application-global-workflows.yaml b/charts/argocd-understack/templates/application-global-workflows.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: nautobot

diff --git a/charts/argocd-understack/templates/application-ingress-nginx.yaml b/charts/argocd-understack/templates/application-ingress-nginx.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: ingress-nginx

diff --git a/charts/argocd-understack/templates/application-karma.yaml b/charts/argocd-understack/templates/application-karma.yaml
@@ -6,6 +6,7 @@ metadata:
   name: {{ printf "%s-%s" $.Release.Name "karma" }}
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: monitoring

diff --git a/charts/argocd-understack/templates/application-mariadb-operator-crds.yaml b/charts/argocd-understack/templates/application-mariadb-operator-crds.yaml
@@ -10,6 +10,7 @@ metadata:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
     # we always want CRDs to be at -2 sync wave
     argocd.argoproj.io/sync-wave: "-2"
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: mariadb-operator

diff --git a/charts/argocd-understack/templates/application-mariadb-operator.yaml b/charts/argocd-understack/templates/application-mariadb-operator.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: mariadb-operator

diff --git a/charts/argocd-understack/templates/application-monitoring.yaml b/charts/argocd-understack/templates/application-monitoring.yaml
@@ -6,6 +6,7 @@ metadata:
   name: {{ printf "%s-%s" $.Release.Name "monitoring" }}
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: monitoring

diff --git a/charts/argocd-understack/templates/application-nautobot-api-tokens.yaml b/charts/argocd-understack/templates/application-nautobot-api-tokens.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: nautobot

diff --git a/charts/argocd-understack/templates/application-nautobot.yaml b/charts/argocd-understack/templates/application-nautobot.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: nautobot

diff --git a/charts/argocd-understack/templates/application-nautobotop.yaml b/charts/argocd-understack/templates/application-nautobotop.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: nautobotop

diff --git a/charts/argocd-understack/templates/application-openebs.yaml b/charts/argocd-understack/templates/application-openebs.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: openebs

diff --git a/charts/argocd-understack/templates/application-openstack-exporter.yaml b/charts/argocd-understack/templates/application-openstack-exporter.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: monitoring

diff --git a/charts/argocd-understack/templates/application-openstack-helm.yaml b/charts/argocd-understack/templates/application-openstack-helm.yaml
@@ -25,6 +25,7 @@ metadata:
     argocd.argoproj.io/sync-wave: {{ quote . }}
   {{- end }}
   */}}
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: {{ $.Values.site.openstack.namespace }}

diff --git a/charts/argocd-understack/templates/application-openstack-memcached.yaml b/charts/argocd-understack/templates/application-openstack-memcached.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: openstack

diff --git a/charts/argocd-understack/templates/application-openstack-resource-controller.yaml b/charts/argocd-understack/templates/application-openstack-resource-controller.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: orc-system

diff --git a/charts/argocd-understack/templates/application-openstack.yaml b/charts/argocd-understack/templates/application-openstack.yaml
@@ -13,6 +13,7 @@ metadata:
     argocd.argoproj.io/sync-wave: {{ quote . }}
   {{- end }}
   */}}
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: {{ .Values.site.openstack.namespace }}

diff --git a/charts/argocd-understack/templates/application-opentelemetry-operator.yaml b/charts/argocd-understack/templates/application-opentelemetry-operator.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: opentelemetry-operator

diff --git a/charts/argocd-understack/templates/application-openvswitch.yaml b/charts/argocd-understack/templates/application-openvswitch.yaml
@@ -7,6 +7,7 @@ metadata:
   name: {{ printf "%s-%s" $.Release.Name "openvswitch" }}
   finalizers:
   - resources-finalizer.argocd.argoproj.io
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: {{ $.Values.site.openstack.namespace }}

diff --git a/charts/argocd-understack/templates/application-otel-collector.yaml b/charts/argocd-understack/templates/application-otel-collector.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: otel-collector

diff --git a/charts/argocd-understack/templates/application-ovn.yaml b/charts/argocd-understack/templates/application-ovn.yaml
@@ -7,6 +7,7 @@ metadata:
   name: {{ printf "%s-%s" $.Release.Name "ovn" }}
   finalizers:
   - resources-finalizer.argocd.argoproj.io
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: {{ $.Values.site.openstack.namespace }}

diff --git a/charts/argocd-understack/templates/application-prometheus-operator-crds.yaml b/charts/argocd-understack/templates/application-prometheus-operator-crds.yaml
@@ -10,6 +10,7 @@ metadata:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
     # we always want CRDs to be at -2 sync wave
     argocd.argoproj.io/sync-wave: "-2"
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: monitoring

diff --git a/charts/argocd-understack/templates/application-rabbitmq-system.yaml b/charts/argocd-understack/templates/application-rabbitmq-system.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: rabbitmq-system

diff --git a/charts/argocd-understack/templates/application-rook.yaml b/charts/argocd-understack/templates/application-rook.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: rook-ceph

diff --git a/charts/argocd-understack/templates/application-sealed-secrets.yaml b/charts/argocd-understack/templates/application-sealed-secrets.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: kube-system

diff --git a/charts/argocd-understack/templates/application-site-workflows.yaml b/charts/argocd-understack/templates/application-site-workflows.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: openstack

diff --git a/charts/argocd-understack/templates/application-snmp-exporter.yaml b/charts/argocd-understack/templates/application-snmp-exporter.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: monitoring

diff --git a/charts/argocd-understack/templates/application-undersync.yaml b/charts/argocd-understack/templates/application-undersync.yaml
@@ -8,6 +8,7 @@ metadata:
   - resources-finalizer.argocd.argoproj.io
   annotations:
     argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true
+{{- include "understack.appLabelsBlock" $ | nindent 2 }}
 spec:
   destination:
     namespace: undersync

diff --git a/charts/argocd-understack/values.yaml b/charts/argocd-understack/values.yaml
@@ -27,6 +27,10 @@ deploy_ref: HEAD
 # @default -- "" (no prefix, just Release.Name)
 deploy_path_prefix:
 
+# -- Additional labels to apply to all generated ArgoCD Application resources.
+# @default -- {}
+appLabels: {}
+
 # -- This block is for setting up the UnderStack global specific ArgoCD Applications
 global:
   # -- Enable/disable deploying the global specific applications

diff --git a/docs/deploy-guide/deploy-repo.md b/docs/deploy-guide/deploy-repo.md
@@ -73,6 +73,33 @@ You can verify all required files exist with:
 understackctl deploy check my-site
 ```
 
+### Top-level Chart Settings
+
+In addition to component sections, `deploy.yaml` supports top-level settings that apply across all generated ArgoCD Applications:
+
+| Key | Description |
+|-----|-------------|
+| `understack_url` | UnderStack source repository URL |
+| `understack_ref` | Git ref (branch, tag, or commit) to deploy from |
+| `deploy_url` | Your deployment repository URL |
+| `deploy_ref` | Git ref for the deployment repository |
+| `deploy_path_prefix` | Optional path prefix within the deploy repo |
+| `cluster_server` | Target cluster API server URL |
+| `appLabels` | Additional labels applied to every ArgoCD Application |
+
+`appLabels` is useful for identifying which cluster or partition an Application belongs to when managing multiple clusters through a single ArgoCD instance:
+
+```yaml title="my-site/deploy.yaml"
+understack_url: https://github.com/rackerlabs/understack.git
+deploy_url: git@github.com:my-org/my-deploy.git
+appLabels:
+  understack.rackspace.com/cluster: my-site
+  understack.rackspace.com/partition: us-east
+site:
+  enabled: true
+  # ...
+```
+
 ### Managing Components
 
 To enable or disable components, edit the component sections in `deploy.yaml`: