docs: add details about our Argo Workflows / Events installation

Document how Argo Workflows and Argo Events are currently installed and
how we should utilize them.

Author: cardoe

docs/design-guide/argo-events.md

@@ -0,0 +1,78 @@
+# Argo Events
+
+The UnderStack project utilizes [Argo Events][argo-events] to provide
+uniform event-driven automation. Operations can be provided within
+UnderStack or defined by users to provide additional operations on
+events.
+
+Some examples of how UnderStack utilizes Argo Events are:
+
+* Listen to OpenStack notifications via RabbitMQ message queues
+* Propagate updates to Nautobot for inventory synchronization
+* Trigger asynchronous operations that are outside the scope of OpenStack plugins
+* Maintain loose coupling between OpenStack and external automation workflows
+
+## Architecture & Security Model
+
+[Argo Events][argo-events] operates within the namespace (argo-events),
+while the actual [EventSources][argo-events-eventsource] and [Sensors][argo-events-sensor]
+run in other namespaces on the cluster.
+
+### Argo Events Configuration
+
+We install the controller and the validating webhook into the (argo-events)
+namespace.
+
+## EventSource and Sensor Configuration
+
+[Sensors][argo-events-sensor] must be co-located with the [EventSource][argo-events-eventsource]
+they are using so you will find them in multiple namespaces.
+
+### Proper Definitions
+
+You must configure the `dependencies` section of your [Sensor][argo-events-sensor]
+correctly for it to properly trigger on events. For example below is
+a partial snippet of an [argo-events-eventsource] named `openstack-neutron`
+which provides one event named `notifications`:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: EventSource
+metadata:
+  name: openstack-neutron  # THIS IS YOUR eventSourceName
+spec:
+  amqp:
+    notifications:  # THIS IS YOUR eventName
+      url: amqp://localhost
+      routingKey: key
+```
+
+Your [Sensor][argo-events-sensor] would need to be defined as follows:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Sensor
+metadata:
+  name: my-sensor
+spec:
+  dependencies:
+  - eventName: notifications  # MUST MATCH ABOVE
+    eventSourceName: openstack-neutron  # MUST MATCH ABOVE
+    name: your-choice
+```
+
+### Service Accounts
+
+[ServiceAccount][argo-events-sensor-sa]s need to be specifically
+configured for the [Sensor][argo-events-sensor] to be able to execute
+the operation that you would like to happen in response to the event. These
+service accounts should be created with the minimal permissions necessary
+for the sensor and to then execute the operation. For example, many of our
+existing [Sensor][argo-events-sensor]s execute [Argo Workflow](./argo-workflows.md)s
+in response to a trigger so they only need to be able to create the workflow
+from the workflowtemplate.
+
+[argo-events]: <https://argoproj.github.io/argo-events/>
+[argo-events-sensor]: <https://argoproj.github.io/argo-events/concepts/sensor/>
+[argo-events-eventsource]: <https://argoproj.github.io/argo-events/concepts/event_source/>
+[argo-events-sensor-sa]: <https://argoproj.github.io/argo-events/service-accounts/#service-account-for-sensors>

docs/design-guide/argo-workflows.md

@@ -0,0 +1,52 @@
+# Argo Workflows
+
+The UnderStack project utilizes [Argo Workflows][argo-wf] as its
+workflow orchestration engine for managing complex, multi-step
+operations across the infrastructure stack. [Argo Workflows][argo-wf]
+provides a Kubernetes-native approach to defining and executing
+workflows, enabling reliable automation of provisioning, deployment,
+and maintenance tasks.
+
+## Architecture & Security Model
+
+[Argo Workflows][argo-wf] operates within a dedicated namespace (argo),
+while the actual workflows run in another dedicated namespace (argo-events),
+to ensure proper security isolation and resource control. This separation
+is provided by [Argo Workflows][argo-wf] but poorly documented upstream which
+they call [Managed Namespace][argo-wf-managed-ns].
+
+### Argo Workflows Configuration
+
+We do not use the `namespace-install.yaml` provided by the project as it
+combines everything into one YAML and we need to split it out. It combines:
+
+* CRDs
+* Argo Server, which is the UI and the API for Argo Workflows and Argo Events
+* Argo Workflows Controller, which is the executor for the workflow and creates
+the pods
+* Server Role, which is the Role and RoleBinding for the Argo Server to access
+the workflow, the pods, the logs, and inputs for user visibility
+* Workflow Controller Role, which is the Role and RoleBinding to give the controller
+access to run and manage the workflows.
+
+The CRDs, the Argo Server, and the Argo Workflow Controller will all be installed
+into the (argo) namespace while the 2 Roles and RoleBindings need to be installed
+into the namespace where the workflow execute, which is (argo-events).
+
+The Argo Server and the Workflow Controller additionally need access to additional
+resources. The Argo Server needs access to the configmap, the SSO secret
+
+## Template-Only Execution Model
+
+Understack enforces a strict template-only execution model where all workflows
+must be pre-defined as [WorkflowTemplate][argo-wf-tmpl]s. This approach ensures:
+
+* Consistency: All workflows follow approved patterns and standards
+* Security: No arbitrary workflow submission; all templates are reviewed and versioned
+* Reusability: Common operations are defined once and parameterized for different
+use cases
+* Governance: Changes to workflows go through code review and CI/CD processes
+
+[argo-wf]: <https://argo-workflows.readthedocs.io/en/latest/>
+[argo-wf-managed-ns]: <https://argo-workflows.readthedocs.io/en/stable/managed-namespace/>
+[argo-wf-tmpl]: <https://argo-workflows.readthedocs.io/en/stable/workflow-templates/>

mkdocs.yml

@@ -120,6 +120,8 @@ nav:
   - 'Design Guide':
     - design-guide/intro.md
     - design-guide/neutron-networking.md
+    - design-guide/argo-workflows.md
+    - design-guide/argo-events.md
   - 'Deployment Guide':
     - deploy-guide/welcome.md
     - deploy-guide/requirements.md