Merge pull request #1091 from rackerlabs/update-app-docs

docs: update appset documentation

Author: nicholaskuechler

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

@@ -23,66 +23,66 @@ in your deployment repo.
 
 ## Removing an application for a specific deploy
 
-To remove an application from being deployed, add or modify the `uc_skip_components`
-annotation on the Kubernetes Secret which defines the cluster in the `argocd` namespace.
-The `uc_skip_components` annotation is a string-ified JSON list of applications to
-skip like:
+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
-uc_skip_components: |
-  ["metallb"]
+- component: metallb
+  skip: true
+- component: dex
+  skip: false  # optional, defaults to false
 ```
 
 ## 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 attempting to add.
+Adding an application 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.
+
+The YAML file should contain:
+
+- A `component` field that matches the application name
+- All sources necessary to load the application
+- A `ref` field set to either `understack` or `deploy` instead of explicitly
+  specifying `repoURL` and `targetRevision` for the UnderStack repo and your deploy repo
 
-The general form should be:
+Example application configuration:
 
 {% raw %}
 
 ```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'
+component: dex
+# optional: install into a different namespace than the component name
+# componentNamespace: dex-system
+sources:
+  - repoURL: https://charts.dexidp.io
+    chart: dex
+    targetRevision: 0.16.0
+    helm:
+      releaseName: dex
+      valueFiles:
+        # pulls defaults from the understack repo
+        - $understack/components/dex/values.yaml
+        # pulls overrides from your deploy repo
+        - $deploy/{{.name}}/helm-configs/dex.yaml
+      ignoreMissingValueFiles: true
+  - ref: understack
+    # path should only be here if you have manifests to load
+    path: 'components/dex'
+  - ref: deploy
+    # only needed if manifests should be here
+    path: '{{.name}}/manifests/dex'
 ```
 
 {% endraw %}
 
 ## Removing an application from UnderStack
 
+Removing an application 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-appset]: <https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/>

docs/deploy-guide/management-cluster.md

@@ -94,10 +94,6 @@ different configurations.
 : Git reference to use of the deploy repo. Can only be set for `dev` env
   clusters.
 
-`uc_skip_components`
-: string-ified JSON list of components or services from UnderStack to not
-  install in this cluster.
-
 ### Deploying your Cluster Config
 
 Once you have the Kubernetes secret which defines your cluster config ready