Skip to content

Commit f7c9477

Browse files
syedhaseebahmedsyedhaseebahmed
committed
nautobot token creation flow
1 parent cadbfc9 commit f7c9477

File tree

2 files changed

+117
-0
lines changed

2 files changed

+117
-0
lines changed

‎docs/deploy-guide/nautobot-secrets.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Automate Nautobot tokens Provisioning
2+
3+
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.
4+
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
**High-level Flow:**
12+
13+
1. Service account details are stored in **Vault (PasswordSafe)**.
14+
2. A **Kubernetes Secret** is generated in the `nautobot` namespace.
15+
3. **Argo Events** detects the secret creation or update based on the [label](https://github.com/rackerlabs/understack/blob/main/workflows/nautobot/eventsources/k8s-secret-nautobot-token.yaml#L19).
16+
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.
17+
18+
---
19+
20+
## Architecture Diagram (Conceptual)
21+
22+
```text
23+
Vault / PasswordSafe ──▶ K8s Secret (nautobot ns)
24+
│
25+
▼
26+
Argo Event Trigger
27+
│
28+
▼
29+
Ansible Playbook ──▶ Nautobot API
30+
│
31+
▼
32+
User + Token Created
33+
```
34+
35+
---
36+
37+
## Key Components
38+
39+
| Component | Purpose |
40+
|------------|----------|
41+
| **Vault / PasswordSafe** | Stores service account credentials (username, password) securely. |
42+
| **Kubernetes Secret** | Auto-generated representation of the service account in the `nautobot` namespace. |
43+
| **Argo Events** | Detects changes in secrets and triggers an automated workflow. |
44+
| **Ansible Playbook** | Interacts with the Nautobot API to create users and tokens. |
45+
| **ClusterSecretStore** | Enables sharing of secrets between namespaces. |
46+
| **Nautobot API** | Endpoint for managing users and tokens programmatically. |
47+
48+
---
49+
50+
## Required Secrets
51+
52+
| Secret Name | Source | Namespace | Description |
53+
|--------------|---------|------------|--------------|
54+
| `nautobot-superuser-token` | Generated by global cluster | `nautobot` | Used to bootstrap site clusters. |
55+
56+
---
57+
58+
## Usage Flow Summary
59+
60+
1. Add or update service account credentials in **Vault / PasswordSafe**.
61+
2. Vault sync process generates a **Kubernetes Secret** in `nautobot` namespace.
62+
3. **Argo Events** detects the change and triggers a workflow.
63+
4. Workflow launches **Ansible Playbook** to interact with Nautobot API.
64+
5. Nautobot user and token are created or updated accordingly.
65+
6. Secrets are synchronized in different namespaces using `ClusterSecretStore`.
66+
7. Site clusters continue to use local tokens for operations.
67+
68+
---
69+
70+
## Deployment via Argo CD
71+
72+
The Nautobot service account automation is deployed and managed through **Argo CD** using the following application manifests:
73+
74+
| Manifest | Description |
75+
|-----------|--------------|
76+
| [`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. |
77+
| [`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. |
78+
79+
### Deployment Workflow
80+
81+
1. **Global Nautobot Deployment**
82+
- The global Argo CD application (`nautobot.yaml`) deploys the base Nautobot configuration and generates a **superuser token**.
83+
- This token is stored securely as a Kubernetes Secret in the `nautobot` namespace of the global cluster.
84+
- Another responsibility of global cluster is to create superuser token of site clusters.
85+
- example: global cluster (staging) creates site cluster super-user (rxdb-lab) secret and also creates user and token in nautobot.
86+
87+
2. **Site Nautobot Deployment**
88+
- Each site’s Argo CD application (`nautobot-site.yaml`) only creates secrets.
89+
- Now site cluster only creates secret of **superuser** it did not do anything in Nautobot.
90+
- The site retrieves the **superuser token** and uses it to authenticate against Nautobot.
91+
- Site-specific **service accounts and tokens** are then created through Argo Events and Ansible workflows.
92+
- Global cluster's superuser token is not used anywhere in site cluster.
93+
- [`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.
94+
95+
3. **Automation Integration**
96+
- When new site credentials are created in Vault, the change triggers the site-level automation flow.
97+
- The site Nautobot instance creates or updates its user and token accordingly.
98+
99+
---
100+
101+
## Service Account tokens
102+
103+
| nautobot Secret Name | service Secret Name | Service Namespace | token user in Nautobot | Description |
104+
|-----------------------|---------------------|-------------------|----------------------|------------------------------------------------------|
105+
| `ansible-token` | nautobot-token | `nautobot` | cluster-name-ansible | Token used by ansible to access Nautobot. |
106+
| `openstack-token` | nautobot-token | `openstack` | cluster-name-openstack | Token used by openstack services to access Nautobot. |
107+
| `undersync-token` | nautobot-token | `undersync` | cluster-name-undersync | Token used by Undersync to access Nautobot. |
108+
| `workflow-token` | nautobot-token | `argo-events` | cluster-name-workflow | Token used by workflow jobs to access Nautobot. |
109+
110+
---
111+
112+
## References
113+
114+
- **PR:** [rackerlabs/understack#1256](https://github.com/rackerlabs/understack/pull/1256)
115+
116+
---

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@ nav:
135135
- deploy-guide/config-openstack.md
136136
- deploy-guide/secrets-eso-setup.md
137137
- deploy-guide/openstack-svc-users.md
138+
- deploy-guide/nautobot-secrets.md
138139
- deploy-guide/auth.md
139140
- deploy-guide/config-argo-workflows.md
140141
- Starting the Deployment:

0 commit comments

Comments
 (0)