Skip to content

Commit b07679f

Browse files
cardoecardoe
authored
Merge pull request #1643 from rackerlabs/create-cluster-docs
docs: initial documentation on building a global and site clusters
2 parents 9e9e087 + e9b510c commit b07679f

5 files changed

Lines changed: 639 additions & 3 deletions

File tree

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ $(ACTIVATE): requirements-docs.txt
3131
.PHONY: wftmpls
3232
wftmpls: $(WFTMPLS) $(ACTIVATE)
3333
@mkdir -p docs/workflows
34-
@rm docs/workflows/*.md
34+
@rm -f docs/workflows/*.md
3535
@$(PYTHON) scripts/argo-workflows-to-mkdocs.py components/global-workflows docs/workflows
3636
@$(PYTHON) scripts/argo-workflows-to-mkdocs.py components/site-workflows docs/workflows
3737
@$(PYTHON) scripts/argo-workflows-to-mkdocs.py workflows docs/workflows

‎docs/deploy-guide/deploy-repo.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,20 +22,30 @@ mkdir -p my-site/{manifests,helm-configs,inventory}
2222

2323
cat <<- EOF > my-global/deploy.yaml
2424
---
25-
name: my-global
2625
understack_url: https://github.com/rackerlabs/understack.git
2726
understack_ref: v0.0.5 # replace with the tag or git reference you want to use
2827
deploy_url: git@github.com:my-org/my-deploy.git
2928
deploy_ref: HEAD
29+
30+
global:
31+
enabled: false
32+
33+
site:
34+
enabled: false
3035
EOF
3136

3237
cat <<- EOF > my-site/deploy.yaml
3338
---
34-
name: my-site
3539
understack_url: https://github.com/rackerlabs/understack.git
3640
understack_ref: v0.0.5
3741
deploy_url: git@github.com:my-org/my-deploy.git
3842
deploy_ref: HEAD
43+
44+
global:
45+
enabled: false
46+
47+
site:
48+
enabled: false
3949
EOF
4050
```
4151

‎docs/deploy-guide/global-cluster.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Deploying a Global Cluster
2+
3+
The [Global cluster](./welcome.md#system-division) hosts shared services
4+
that exist once per partition, such as [Nautobot][nautobot] (DCIM/IPAM),
5+
[Dex][dex] (SSO/OIDC), and global workflows. This guide walks through
6+
setting up a Global cluster from scratch using an incremental approach:
7+
start with everything disabled, verify ArgoCD connectivity, then enable
8+
components one at a time.
9+
10+
## Prerequisites
11+
12+
Before starting, ensure:
13+
14+
- You have a running [Management cluster](./management-cluster.md) with
15+
ArgoCD deployed
16+
- You have a [deployment repository](./deploy-repo.md) initialized
17+
- Your target Kubernetes cluster has a **CNI** (e.g., Cilium) configured
18+
and operational
19+
- Your target Kubernetes cluster has a **storage provisioner** configured
20+
and operational
21+
22+
## Create the Cluster Directory
23+
24+
In your deployment repository, create a directory named after your cluster.
25+
This name must match the cluster name registered in ArgoCD.
26+
27+
```bash title="From the deploy repo root"
28+
mkdir -p my-global/{manifests,helm-configs}
29+
```
30+
31+
## Create the Initial deploy.yaml
32+
33+
Create a `deploy.yaml` in your cluster directory. This file combines the
34+
repository metadata and the Helm values for the
35+
[argocd-understack][argocd-helm-chart] chart into a single
36+
file.
37+
38+
Start with **everything disabled** so you can verify ArgoCD connectivity
39+
before deploying any workloads.
40+
41+
```yaml title="my-global/deploy.yaml"
42+
---
43+
understack_url: https://github.com/rackerlabs/understack.git
44+
understack_ref: v0.1.0 # replace with the tag or git reference you want to use
45+
deploy_url: https://github.com/my-org/my-deploy.git
46+
deploy_ref: HEAD
47+
48+
global:
49+
enabled: false
50+
51+
site:
52+
enabled: false
53+
```
54+
55+
## Register the Cluster with ArgoCD
56+
57+
Your Global cluster must be registered as a cluster in ArgoCD on the
58+
Management cluster. See [Management Cluster](./management-cluster.md#configuring-your-global-andor-site-cluster-in-argocd)
59+
for details on creating the cluster secret.
60+
61+
When creating your cluster secret, set the role annotation to `global`:
62+
63+
```yaml
64+
metadata:
65+
annotations:
66+
understack.rackspace.com/role: global
67+
```
68+
69+
!!! note "TODO"
70+
Detailed end-to-end cluster registration documentation is a work in
71+
progress. For now, refer to the
72+
[Management Cluster](./management-cluster.md) and
73+
[ArgoCD Helm Chart](../operator-guide/argocd-helm-chart.md)
74+
documentation.
75+
76+
## Verify ArgoCD Connectivity
77+
78+
Once the cluster is registered, commit and push your deploy repo changes.
79+
Verify that ArgoCD can see your cluster and that the application is healthy
80+
(even though nothing is deployed yet).
81+
82+
```bash
83+
# on the management cluster
84+
kubectl get applications -n argocd | grep my-global
85+
```
86+
87+
## Enable Components
88+
89+
With ArgoCD connectivity confirmed, you can begin enabling components one
90+
at a time. After enabling each component, commit and push your changes,
91+
then verify the ArgoCD Application becomes healthy before moving on.
92+
93+
### cert-manager
94+
95+
[cert-manager][cert-manager] provides TLS certificate management. Enable
96+
it in your `deploy.yaml` and provide your ClusterIssuer manifests.
97+
98+
```yaml title="my-global/deploy.yaml (update)"
99+
global:
100+
enabled: true
101+
102+
cert_manager:
103+
enabled: true
104+
```
105+
106+
Create a directory for your cluster issuer manifests:
107+
108+
```bash
109+
mkdir -p my-global/manifests/cert-manager
110+
```
111+
112+
Place your `ClusterIssuer` resource(s) in this directory. These define how
113+
certificates will be issued for services in your cluster.
114+
115+
### External DNS
116+
117+
[External DNS][external-dns] automates DNS record management for services.
118+
119+
```yaml title="my-global/deploy.yaml (update)"
120+
global:
121+
# ...
122+
external_dns:
123+
enabled: true
124+
```
125+
126+
### Dex
127+
128+
[Dex][dex] provides OIDC-based SSO across UnderStack services. Dex
129+
requires both Helm value overrides and manifests.
130+
131+
```yaml title="my-global/deploy.yaml (update)"
132+
global:
133+
# ...
134+
dex:
135+
enabled: true
136+
```
137+
138+
Create the manifests directory and Helm values file:
139+
140+
```bash
141+
mkdir -p my-global/manifests/dex
142+
```
143+
144+
Configure your authentication in the Helm values file:
145+
146+
```yaml title="my-global/helm-configs/dex.yaml"
147+
# See the Dex configuration guide for details on what goes here
148+
```
149+
150+
For details on configuring Dex authentication, see
151+
[Configuring Dex](./config-dex.md) and [Authentication](./auth.md).
152+
153+
## Next Steps
154+
155+
Continue enabling components in your `deploy.yaml` as needed. The full
156+
list of available global components and their defaults can be found in the
157+
[argocd-understack values.yaml][values] or the
158+
[ArgoCD Helm Chart guide](../operator-guide/argocd-helm-chart.md).
159+
160+
A typical global cluster will eventually enable most or all of the
161+
following:
162+
163+
| Component | Purpose |
164+
|---|---|
165+
| `cert_manager` | TLS certificate management |
166+
| `cilium` | CNI network policies |
167+
| `cnpg_system` | Cloud Native PostgreSQL operator |
168+
| `dex` | SSO/OIDC provider |
169+
| `envoy_gateway` | API gateway |
170+
| `etcdbackup` | etcd backup |
171+
| `external_dns` | DNS record automation |
172+
| `external_secrets` | Secrets management |
173+
| `global_workflows` | Argo Events and Workflows |
174+
| `ingress_nginx` | Ingress controller |
175+
| `monitoring` | Prometheus/Grafana monitoring |
176+
| `nautobot` | Network Source of Truth |
177+
| `nautobotop` | Nautobot Kubernetes operator |
178+
| `openebs` | Storage (if using OpenEBS) |
179+
| `openstack_resource_controller` | OpenStack resource operator |
180+
| `opentelemetry_operator` | OpenTelemetry operator |
181+
| `otel_collector` | Observability collector |
182+
| `rabbitmq_system` | RabbitMQ operator |
183+
| `rook` | Storage (if using Rook/Ceph) |
184+
| `sealed_secrets` | Sealed Secrets operator |
185+
| `understack_cluster_issuer` | UnderStack cert-manager ClusterIssuer |
186+
187+
For each component that requires environment-specific configuration, you
188+
can provide:
189+
190+
- **Helm value overrides** in `my-global/helm-configs/<component>.yaml`
191+
- **Kustomize manifests** in `my-global/manifests/<component>/`
192+
193+
See [Configuring Components](./component-config.md) for details on these
194+
customization methods.
195+
196+
[nautobot]: <https://docs.nautobot.com/>
197+
[dex]: <https://dexidp.io/>
198+
[cert-manager]: <https://cert-manager.io/>
199+
[external-dns]: <https://kubernetes-sigs.github.io/external-dns/>
200+
[argocd-helm-chart]: <../operator-guide/argocd-helm-chart.md>
201+
[values]: <https://github.com/rackerlabs/understack/blob/main/charts/argocd-understack/values.yaml>

0 commit comments

Comments
 (0)