chore: standardize and document how AppSets define apps PUC-603

apps/appsets/components.yaml

@@ -20,6 +20,20 @@ spec:
                 - component: dex
                   skipComponent: '{{has "dex" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
+                    - repoURL: https://charts.dexidp.io
+                      chart: dex
+                      targetRevision: 0.16.0
+                      helm:
+                        releaseName: dex
+                        valuesObject:
+                          config:
+                            issuer: 'https://dex.{{index .metadata.annotations "dns_zone" }}'
+                          env:
+                            DNS_ZONE: '{{index .metadata.annotations "dns_zone" }}'
+                        valueFiles:
+                          - $understack/components/dex/values.yaml
+                          - $deploy/{{.name}}/helm-configs/dex.yaml
+                        ignoreMissingValueFiles: true
                     - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
                       targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
                       path: 'components/dex'
@@ -43,20 +57,6 @@ spec:
                       targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
                       ref: deploy
                       path: '{{.name}}/manifests/dex'
-                    - repoURL: https://charts.dexidp.io
-                      chart: dex
-                      targetRevision: 0.16.0
-                      helm:
-                        releaseName: dex
-                        valuesObject:
-                          config:
-                            issuer: 'https://dex.{{index .metadata.annotations "dns_zone" }}'
-                          env:
-                            DNS_ZONE: '{{index .metadata.annotations "dns_zone" }}'
-                        valueFiles:
-                          - $understack/components/dex/values.yaml
-                          - $deploy/{{.name}}/helm-configs/dex.yaml
-                        ignoreMissingValueFiles: true
                 - component: openstack
                   skipComponent: '{{has "openstack" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
@@ -78,14 +78,6 @@ spec:
                 - component: nautobot
                   skipComponent: '{{has "nautobot" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
-                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
-                      path: 'components/nautobot'
-                      ref: understack
-                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
-                      ref: deploy
-                      path: '{{.name}}/manifests/nautobot'
                     - repoURL: https://nautobot.github.io/helm-charts/
                       chart: nautobot
                       targetRevision: 2.1.3
@@ -106,6 +98,14 @@ spec:
                             # until ArgoCD 2.13.0 is released we cannot use a reference
                             # path: $understack/components/nautobot/nautobot_config.py
                             path: 'https://raw.githubusercontent.com/rackerlabs/understack/{{index .metadata.annotations "uc_repo_ref" }}/components/nautobot/nautobot_config.py'
+                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
+                      path: 'components/nautobot'
+                      ref: understack
+                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+                      ref: deploy
+                      path: '{{.name}}/manifests/nautobot'
                 - component: argo
                   skipComponent: '{{has "argo" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   source:
@@ -191,12 +191,6 @@ spec:
                   componentNamespace: monitoring
                   skipComponent: '{{has "openstack-exporter" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
-                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
-                      ref: understack
-                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
-                      ref: deploy
                     - repoURL: registry.scs.community/openstack-exporter
                       chart: prometheus-openstack-exporter
                       targetRevision: 0.4.5
@@ -205,6 +199,12 @@ spec:
                         valueFiles:
                           - $deploy/{{.name}}/helm-configs/openstack-exporter.yaml
                         ignoreMissingValueFiles: true
+                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
+                      ref: understack
+                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+                      ref: deploy
             selector:
               # by setting the key in the elements 'skipComponent' to 'true' it will skip installing it
               # ArgoCD's templating operates with strings so it's the string "true"

apps/appsets/infra.yaml

@@ -53,9 +53,6 @@ spec:
                 - component: ingress-nginx
                   skipComponent: '{{has "ingress-nginx" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
-                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
-                      ref: deploy
                     - repoURL: https://kubernetes.github.io/ingress-nginx
                       chart: ingress-nginx
                       targetRevision: 4.9.1
@@ -64,13 +61,13 @@ spec:
                         valueFiles:
                           - $deploy/{{.name}}/helm-configs/ingress-nginx.yaml
                         ignoreMissingValueFiles: true
+                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+                      ref: deploy
                 - component: provisioning-ingress-nginx
                   componentNamespace: ingress-nginx
                   skipComponent: '{{has "provisioning-ingress-nginx" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
-                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
-                      ref: deploy
                     - repoURL: https://kubernetes.github.io/ingress-nginx
                       chart: ingress-nginx
                       targetRevision: 4.9.1
@@ -88,6 +85,9 @@ spec:
                         valueFiles:
                           - $deploy/{{.name}}/helm-configs/provisioning-ingress-nginx.yaml
                         ignoreMissingValueFiles: true
+                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+                      ref: deploy
                 - component: cilium
                   skipComponent: '{{has "cilium" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:

apps/appsets/openstack.yaml

@@ -38,14 +38,6 @@ spec:
     spec:
       project: default
       sources:
-        - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
-          path: components/{{.component}}/
-          targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
-          ref: understack
-        - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
-          targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
-          path: '{{.name}}/manifests/{{.component}}'
-          ref: deploy
         - repoURL: https://tarballs.opendev.org/openstack/openstack-helm/
           chart: '{{.component}}'
           targetRevision: '{{.chartVersion}}'
@@ -58,6 +50,14 @@ spec:
               - $deploy/{{.name}}/helm-configs/{{.component}}.yaml
             # don't require all the values files
             ignoreMissingValueFiles: true
+        - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
+          path: components/{{.component}}/
+          targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
+          ref: understack
+        - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+          targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+          path: '{{.name}}/manifests/{{.component}}'
+          ref: deploy
       ignoreDifferences:
         - kind: Secret
           name: keystone-fernet-keys

apps/appsets/operators.yaml

@@ -20,13 +20,6 @@ spec:
                   componentNamespace: rook-ceph
                   skipComponent: '{{has "rook" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
-                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
-                      path: 'operators/rook'
-                      ref: understack
-                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
-                      ref: deploy
                     - repoURL: https://charts.rook.io/release
                       chart: rook-ceph
                       targetRevision: v1.15.0
@@ -45,6 +38,13 @@ spec:
                           - $understack/operators/rook/values-cluster.yaml
                           - $deploy/{{.name}}/helm-configs/rook-cluster.yaml
                         ignoreMissingValueFiles: true
+                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
+                      path: 'operators/rook'
+                      ref: understack
+                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+                      ref: deploy
                 - component: cnpg-system
                   skipComponent: '{{has "cnpg-system" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
@@ -70,16 +70,8 @@ spec:
                       targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
                       path: 'operators/rabbitmq-system'
                 - component: monitoring
-                  componentNamespace: monitoring
                   skipComponent: '{{has "monitoring" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
                   sources:
-                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
-                      path: 'operators/monitoring'
-                      ref: understack
-                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
-                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
-                      ref: deploy
                     - repoURL: https://prometheus-community.github.io/helm-charts
                       chart: kube-prometheus-stack
                       targetRevision: 62.6.0
@@ -89,6 +81,13 @@ spec:
                           - $understack/operators/monitoring/values.yaml
                           - $deploy/{{.name}}/helm-configs/monitoring.yaml
                         ignoreMissingValueFiles: true
+                    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
+                      path: 'operators/monitoring'
+                      ref: understack
+                    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+                      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+                      ref: deploy
             selector:
               # by setting the key in the elements 'skipComponent' to 'true' it will skip installing it
               # ArgoCD's templating operates with strings so it's the string "true"

docs/deploy-guide/add-remove-app.md

@@ -36,7 +36,47 @@ uc_skip_components: |
 ## Adding an application to UnderStack
 
 Adding an application to be part of UnderStack involves modifying the
-`apps/appsets/*.yaml` file that is appropriate for what you are
+`apps/appsets/*.yaml` file that is appropriate for what you are attempting to add.
+
+The general form should be:
+
+```yaml
+# list item per ArgoCD Application
+# the component value will appear as the ArgoCD Application name
+- component: dex
+  # the below line can be added to install this into a different namespace than the component
+  # componentNamespace: dex-system
+  # this allows this component to not be installed
+  skipComponent: '{{has "dex" ((default "[]" (index .metadata.annotations "uc_skip_components") | fromJson))}}'
+  # defines all the sources used, the upstream chart or upstream source should come first
+  # uc_repo_ in this context is the understack repo
+  # uc_deploy_ in this context is the deploy specific repo
+  sources:
+    - repoURL: https://charts.dexidp.io
+      chart: dex
+      targetRevision: 0.16.0
+      helm:
+        releaseName: dex
+        valueFiles:
+        # this pulls defaults from the understack repo
+          - $understack/components/dex/values.yaml
+        # this pulls overrides from your deploy repo
+          - $deploy/{{.name}}/helm-configs/dex.yaml
+        # this makes it so the above don't have to exist
+        ignoreMissingValueFiles: true
+    - repoURL: '{{index .metadata.annotations "uc_repo_git_url"}}'
+      targetRevision: '{{index .metadata.annotations "uc_repo_ref"}}'
+      # path should only be here if you have manifests you want loaded
+      path: 'components/dex'
+      # ref is used above in the chart for the valueFiles
+      ref: understack
+    - repoURL: '{{index .metadata.annotations "uc_deploy_git_url"}}'
+      targetRevision: '{{index .metadata.annotations "uc_deploy_ref"}}'
+      # ref is used in the chart valueFiles
+      ref: deploy
+      # only needed if manifests should be here
+      path: '{{.name}}/manifests/dex'
+```
 
 ## Removing an application from UnderStack