docs: nautobot token creation flow

docs/deploy-guide/nautobot-secrets.md

@@ -0,0 +1,127 @@
+# Automate Nautobot tokens Provisioning
+
+This document explains the design, flow, and deployment details of the automated Nautobot tokens provisioning system implemented in the UnderStack project. The feature enables seamless creation and synchronization of Nautobot service accounts and tokens across multiple site clusters using Vault(Passwordsafe), Kubernetes, Argo Events, and Ansible.
+
+---
+
+## Overview
+
+The automation ensures that whenever service account credentials are created or updated in Vault (PasswordSafe), corresponding Nautobot users and tokens are automatically provisioned. The workflow is fully event-driven, eliminating manual intervention for user and token management.
+
+**High-level Flow:**
+
+1. Service account details are stored in **Vault (PasswordSafe)**.
+   Below is the format we expect the credentials to be stored
+
+      ```json
+       {
+         "credential": {
+           "username": "my-nautobot-creds",
+           "password": "{\"password\": \"abcxyz\", \"token\": \"rvwe3457797fd4321a79a5f06830701b8xyz12\"}"
+         }
+       }
+    ```
+
+2. A **Kubernetes Secret** is generated in the `nautobot` namespace.
+3. **Argo Events** detects the secret creation or update based on the [`token/type=nautobot` label](https://github.com/rackerlabs/understack/blob/main/workflows/nautobot/eventsources/k8s-secret-nautobot-token.yaml#L19).
+4. An [**Ansible job**](https://github.com/rackerlabs/understack/blob/main/ansible/playbooks/nautobot-user-token.yaml) runs automatically to create the corresponding user and token in Nautobot.
+
+---
+
+## Architecture Diagram (Conceptual)
+
+```text
+Vault / PasswordSafe ──▶ K8s Secret (nautobot ns)
+          │
+          ▼
+    Argo Event Trigger
+          │
+          ▼
+  Ansible Playbook ──▶ Nautobot API
+          │
+          ▼
+   User + Token Created
+```
+
+---
+
+## Key Components
+
+| Component | Purpose |
+|------------|----------|
+| **Vault / PasswordSafe** | Stores service account credentials (username, password) securely. |
+| **Kubernetes Secret** | Auto-generated representation of the service account in the `nautobot` namespace. |
+| **Argo Events** | Detects changes in secrets and triggers an automated workflow. |
+| **Ansible Playbook** | Interacts with the Nautobot API to create users and tokens. |
+| **ClusterSecretStore** | Enables sharing of secrets between namespaces. |
+| **Nautobot API** | Endpoint for managing users and tokens programmatically. |
+
+---
+
+## Required Secrets
+
+| Secret Name | Source | Namespace | Description |
+|--------------|---------|------------|--------------|
+| `nautobot-superuser-token` | Generated by global cluster | `nautobot` | Used to bootstrap site clusters. |
+
+---
+
+## Usage Flow Summary
+
+1. Add or update service account credentials in **Vault / PasswordSafe**.
+2. Vault sync process generates a **Kubernetes Secret** in `nautobot` namespace. ExternalSecret will be in SyncError state if details are not present in **Vault / PasswordSafe**.
+3. **Argo Events** detects the change and triggers a workflow.
+4. Workflow launches **Ansible Playbook** to interact with Nautobot API.
+5. Nautobot user and token are created or updated accordingly.
+6. Secrets are synchronized in different namespaces using `ClusterSecretStore`.
+7. Site clusters continue to use local tokens for operations.
+
+---
+
+## Deployment via Argo CD
+
+The Nautobot service account automation is deployed and managed through **Argo CD** using the following application manifests:
+
+| Manifest | Description |
+|-----------|--------------|
+| [`apps/global/nautobot.yaml`](https://github.com/rackerlabs/understack/blob/main/apps/global/nautobot.yaml) | Defines the global Nautobot deployment. This configuration is responsible for creating the superuser token and bootstrapping global secrets. |
+| [`apps/site/nautobot-site.yaml`](https://github.com/rackerlabs/understack/blob/main/apps/site/nautobot-site.yaml) | Defines the per-site Nautobot instance deployment. Each site has its own set of credentials, secrets, and Argo workflows that utilize the superuser token from the global cluster. |
+
+### Deployment Workflow
+
+1. **Global Nautobot Deployment**
+    - The global Argo CD application (`nautobot.yaml`) deploys the base Nautobot configuration and generates a **superuser token**.
+    - This token is stored securely as a Kubernetes Secret in the `nautobot` namespace of the global cluster.
+    - Another responsibility of global cluster is to create superuser token of site clusters.
+      - example: global cluster (staging) creates site cluster super-user (rxdb-lab) secret and also creates user and token in nautobot.
+
+2. **Site Nautobot Deployment**
+    - Each site’s Argo CD application (`nautobot-site.yaml`) only creates secrets.
+    - Now site cluster only creates secret of **superuser** it did not do anything in Nautobot.
+    - The site retrieves the **superuser token** and uses it to authenticate against Nautobot.
+    - Site-specific **service accounts and tokens** are then created through Argo Events and Ansible workflows.
+    - Global cluster's superuser token is not used anywhere in site cluster.
+    - [`Nautobot Secretstore`](https://raw.githubusercontent.com/rackerlabs/understack/main/components/nautobot/secretstore-nautobot.yaml) will provide specific application tokens to respective applications in their namespaces.
+
+3. **Automation Integration**
+    - When new site credentials are created in Vault, the change triggers the site-level automation flow.
+    - The site Nautobot instance creates or updates its user and token accordingly.
+
+---
+
+## Service Account tokens
+
+| nautobot Secret Name  | service Secret Name | Service Namespace | token user in Nautobot | Description                                          |
+|-----------------------|---------------------|-------------------|----------------------|------------------------------------------------------|
+| `ansible-token` | nautobot-token | `nautobot`        | cluster-name-ansible | Token used by ansible to access Nautobot.            |
+| `openstack-token` | nautobot-token | `openstack`       | cluster-name-openstack | Token used by openstack services to access Nautobot. |
+| `undersync-token` | nautobot-token | `undersync`       | cluster-name-undersync | Token used by Undersync to access Nautobot.          |
+| `workflow-token` | nautobot-token | `argo-events`     | cluster-name-workflow | Token used by workflow jobs to access Nautobot.      |
+
+---
+
+## References
+
+- **PR:** [rackerlabs/understack#1256](https://github.com/rackerlabs/understack/pull/1256)
+
+---

mkdocs.yml

@@ -135,6 +135,7 @@ nav:
       - deploy-guide/config-openstack.md
       - deploy-guide/secrets-eso-setup.md
       - deploy-guide/openstack-svc-users.md
+      - deploy-guide/nautobot-secrets.md
       - deploy-guide/auth.md
       - deploy-guide/config-argo-workflows.md
     - Starting the Deployment: