Merge pull request #1185 from rackerlabs/update-argo-workflows-more

cardoe · web-flow · commit 77dad4a2ebe5 · 2025-08-27T18:24:41.000Z
docs: provide details on how to override components and update Argo Workflows
diff --git a/apps/site/argo-workflows.yaml b/apps/site/argo-workflows.yaml
@@ -3,5 +3,3 @@ component: argo
 sources:
   - ref: understack
     path: 'components/argo-workflows'
-  - ref: deploy
-    path: '{{.name}}/manifests/argo-workflows'
diff --git a/components/argo-workflows/sso b/components/argo-workflows/sso
@@ -22,8 +22,5 @@ scopes:
   - groups
   - email
   - profile
-# RBAC Config. >= v2.12
 rbac:
   enabled: false
-# Skip TLS verify, not recommended in production environments. Useful for testing purposes. >= v3.2.4
-insecureSkipVerify: true
diff --git a/docs/deploy-guide/add-remove-app.md b/docs/deploy-guide/add-remove-app.md
@@ -1,45 +1,17 @@
-# Adding / Removing Applications
+# Adding / Removing Components
 
-The applications that are deployed using [ArgoCD][argocd]'s
+UnderStack **Components** are deployed via [ArgoCD]
+as [Applications][argocd-app], these are generated using [ArgoCD][argocd]'s
 [ApplicationSet][argocd-appset] controller. This allows us to use common
-patterns to deploy each of the applications and allow specific environments
-to modify or disable some applications.
+patterns to deploy each of the components and allow specific environments
+to modify or disable some components. See the [Configuring Components](./component-config.md)
+guide for more info on how to do so.
 
-## Modifying an application
+## Adding a Component to UnderStack
 
-To create an environment specific modification to an application you must
-first determine if it's being deployed with Helm or Kustomize.
-
-### Helm
-
-Most of the applications can have their Helm values overridden by adding
-or modifying `$DEPLOY_NAME/helm-configs/$APPLICATION.yaml` in your deployment
-repo.
-
-### Kustomize
-
-To make changes you will need to add or modify files in `$DEPLOY_NAME/manifests/$APPLICATION/`
-in your deployment repo.
-
-## Removing an application for a specific deploy
-
-To remove an application from being deployed, create an `apps.yaml` file in your deployment
-repo at `$DEPLOY_NAME/apps.yaml`). The `apps.yaml` file
-contains a list of objects, where each object has a `component` field that is the name
-of the component (app) and an optional `skip` field that can be set to `true`:
-
-```yaml
-- component: metallb
-  skip: true
-- component: dex
-  skip: false  # optional, defaults to false
-```
-
-## Adding an application to UnderStack
-
-Adding an application to UnderStack involves deciding on the correct ApplicationSet
+Adding a Component to UnderStack involves deciding on the correct ApplicationSet
 (AppSet) to include it in, then going to that AppSet's directory in `apps/<appset>/`
-and adding a YAML file which contains the application configuration.
+and adding a YAML file which contains the Application configuration.
 
 The YAML file should contain:
 
@@ -80,9 +52,10 @@ sources:
 
 ## Removing an application from UnderStack
 
-Removing an application permanently from UnderStack is as easy as
+Removing a Component permanently from UnderStack is as easy as
 deleting its YAML config from its AppSet in the `apps/<appset>/`
 directory.
 
 [argocd]: <https://argo-cd.readthedocs.io/en/stable/>
+[argocd-app]: <https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/>
 [argocd-appset]: <https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/>
diff --git a/docs/deploy-guide/component-config.md b/docs/deploy-guide/component-config.md
@@ -0,0 +1,102 @@
+# Configuring Components
+
+The term **Component** in UnderStack is analogous to an [Application][argocd-app] in [ArgoCD][argocd].
+It is typically tied to one Helm chart or Kustomize deployment. So OpenStack
+Keystone is a **Component** in UnderStack, which lives in `components/keystone`
+in the source tree. In some cases, like OpenStack services,
+there are shared resources so UnderStack will have another **Component** called
+openstack, which lives in `components/openstack` in the source tree, which
+other OpenStack services depend on.
+
+There are three different ways to alter the configuration of a **Component**
+which depends on what you need to achieve.
+
+1. Altering how and what ArgoCD deploys to the cluster
+2. Altering the Helm values or Kustomize overlays
+3. Altering state used by the containers that have been deployed
+
+## Modifying the deployment
+
+In your deployment repo, you will have `$DEPLOY_NAME/apps.yaml`
+(see [Deploy Repo](./deploy-repo.md) for more details) which is
+a list of objects, each object maps to one **Component** and must have
+a field `component` with the string value matching an existing component.
+
+### Disabling a component
+
+To disable for example the `metallb` **Component** you would add to your
+`apps.yaml` something like:
+
+```yaml title="$DEPLOY_NAME/apps.yaml"
+- component: metallb
+  skip: true
+```
+
+The `skip` field is optional and assumed to be `false` otherwise but
+if set to `true` will prevent ArgoCD from deploying it.
+
+### Changing sources used by ArgoCD
+
+We utilize [ArgoCD][argocd] [ApplicationSets][argocd-appset] to create
+the [ArgoCD][argocd] [Applications][argocd-app].
+In all cases we default the template to being a multi-source `Application`.
+You can modify the sources that are used by default by editing your `$DEPLOY_NAME/apps.yaml`
+To change this set your own `sources` list for the **Component** you wish to
+modify. There are two special cased sources available which automatically
+set the `repoUrl` and `targetRevision` fields which are the UnderStack repo
+and your own deployment repo. These can be used by having a `ref` field with
+the value `understack` or `deploy` respectively.
+
+```yaml title="$DEPLOY_NAME/apps.yaml"
+- component: argo
+  sources:
+    - ref: deploy
+      path: deploy_name/manifests/argo-workflows
+```
+
+The above would replace the default behavior to only source from your
+deployment repo for the `argo` **Component** from the specified path.
+
+Another example would be:
+
+```yaml title="$DEPLOY_NAME/apps.yaml"
+- component: openstack
+  sources:
+    - ref: understack
+      path: component/openstack
+      helm:
+        valueFiles:
+          - $deploy/deploy_name/helm-configs/openstack.yaml
+    - ref: deploy
+```
+
+This would utilize the Helm chart in the UnderStack repo while using the
+values file from your deployment repo. This configuration is actually what
+the default for this **Component** is.
+
+You can see the defaults by looking in the `apps` directory in the UnderStack
+repo under the `global`, `site`, and `openstack` directories.
+
+## Modifying component Helm values or Kustomize
+
+To create an environment specific modification to an **Component** you must
+first determine if it's being deployed with Helm or Kustomize.
+
+### Helm
+
+Most of the applications can have their Helm values overridden by adding
+or modifying `$DEPLOY_NAME/helm-configs/$COMPONENT.yaml` in your deployment
+repo.
+
+### Kustomize
+
+To make changes you will need to add or modify files in `$DEPLOY_NAME/manifests/$COMPONENT/`
+in your deployment repo.
+
+## Modifying Environment State
+
+TODO: more to come
+
+[argocd]: <https://argo-cd.readthedocs.io/en/stable/>
+[argocd-app]: <https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/>
+[argocd-appset]: <https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/>
diff --git a/docs/deploy-guide/config-argo-workflows.md b/docs/deploy-guide/config-argo-workflows.md
@@ -20,6 +20,7 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 
 resources:
+- https://github.com/rackerlabs/understack.git//components/argo-workflows/?ref=$TAG_OR_main_OR_OTHER_REF
 - ingress.yaml
 
 configMapGenerator:
diff --git a/docs/deploy-guide/extra-sites.md b/docs/deploy-guide/extra-sites.md
@@ -27,7 +27,6 @@ place it where we've cloned understack. A complete file would look like:
 # this can remain as the literal value and will ensure it computes the right path
 UC_DEPLOY="$(cd "$(dirname ${BASH_SOURCE[0]})" && git rev-parse --show-toplevel)"
 DEPLOY_NAME="my-site"
-DNS_ZONE=home.lab
 UC_DEPLOY_EMAIL="my@email"
 NO_ARGOCD=yes
 ```
@@ -69,7 +68,6 @@ metadata:
     uc_repo_ref: HEAD
     uc_deploy_git_url: "${UC_DEPLOY_GIT_URL}"
     uc_deploy_ref: HEAD
-    dns_zone: "${DNS_ZONE}"
   labels:
     argocd.argoproj.io/secret-type: cluster
 type: Opaque
diff --git a/go/understackctl/cmd/argocd/templates/argoSecretDeployRepo.tmpl b/go/understackctl/cmd/argocd/templates/argoSecretDeployRepo.tmpl
@@ -16,4 +16,3 @@ metadata:
     uc_repo_ref: "HEAD"
     uc_deploy_git_url: "{{ .UC_DEPLOY_GIT_URL }}"
     uc_deploy_ref: "HEAD"
-    dns_zone: "{{ .DNS_ZONE }}"
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -128,6 +128,7 @@ nav:
     - Quick Start: deploy-guide/gitops-install.md
     - Preparing Our Deployment:
       - deploy-guide/deploy-repo.md
+      - deploy-guide/component-config.md
       - deploy-guide/auth.md
       - deploy-guide/config-argo-workflows.md
     - Starting the Deployment:
