Deploying a Global Cluster

The Global cluster hosts shared services
that exist once per partition, such as Nautobot (DCIM/IPAM),
Dex (SSO/OIDC), and global workflows. This guide walks through
setting up a Global cluster from scratch using an incremental approach:
start with everything disabled, verify ArgoCD connectivity, then enable
components one at a time.

Prerequisites

Before starting, ensure:

You have a running Management cluster with
ArgoCD deployed
You have a deployment repository initialized
Your target Kubernetes cluster has a CNI (e.g., Cilium) configured
and operational
Your target Kubernetes cluster has a storage provisioner configured
and operational

Create the Initial Configuration

Initialize your global cluster configuration using understackctl:

cd /path/to/deploy-repo
understackctl deploy init my-global --type global

This creates my-global/deploy.yaml with all global components enabled:

my-global/deploy.yaml

understack_url: https://github.com/rackerlabs/understack.git
deploy_url: https://github.com/my-org/my-deploy.git
global:
  enabled: true
  cert_manager:
    enabled: true
  cilium:
    enabled: true
  dex:
    enabled: true
  external_secrets:
    enabled: true
  # ... additional global components

To start with everything disabled for initial ArgoCD connectivity testing,
edit the file to set enabled: false:

global:
  enabled: false

Create the manifest directories:

understackctl deploy update my-global

Register the Cluster with ArgoCD

Your Global cluster must be registered as a cluster in ArgoCD on the
Management cluster. See Management Cluster
for details on creating the cluster secret.

When creating your cluster secret, set the role annotation to global:

metadata:
  annotations:
    understack.rackspace.com/role: global

TODO

Detailed end-to-end cluster registration documentation is a work in
progress. For now, refer to the
Management Cluster and
ArgoCD Helm Chart
documentation.

Verify ArgoCD Connectivity

Once the cluster is registered, commit and push your deploy repo changes.
Verify that ArgoCD can see your cluster and that the application is healthy
(even though nothing is deployed yet).

# on the management cluster
kubectl get applications -n argocd | grep my-global

Enable Components

With ArgoCD connectivity confirmed, you can begin enabling components one
at a time. After enabling each component, commit and push your changes,
then verify the ArgoCD Application becomes healthy before moving on.

cert-manager

cert-manager provides TLS certificate management. Enable
it in your deploy.yaml and provide your ClusterIssuer manifests.

my-global/deploy.yaml (update)

global:
  enabled: true

  cert_manager:
    enabled: true

After enabling, run understackctl deploy update my-global to create the
directory. Place your ClusterIssuer resource(s) in
my-global/cert-manager/. These define how certificates will be
issued for services in your cluster.

External DNS

External DNS automates DNS record management for services.

my-global/deploy.yaml (update)

global:
  # ...
  external_dns:
    enabled: true

Dex

Dex provides OIDC-based SSO across UnderStack services. Dex
requires both Helm value overrides and manifests.

my-global/deploy.yaml (update)

global:
  # ...
  dex:
    enabled: true

Create the component directories and Helm values file:

After enabling, run `understackctl deploy update my-global` to create the
directory. Configure your authentication in the Helm values file:

```yaml title="my-global/dex/values.yaml"
# See the Dex configuration guide for details on what goes here

For details on configuring Dex authentication, see
Configuring Dex and Authentication.

Next Steps

Continue enabling components in your deploy.yaml as needed. The full
list of available global components and their defaults can be found in the
argocd-understack values.yaml or the
ArgoCD Helm Chart guide.

A typical global cluster will eventually enable most or all of the
following:

Component	Purpose
`cert_manager`	TLS certificate management
`cilium`	CNI network policies
`cnpg_system`	Cloud Native PostgreSQL operator
`dex`	SSO/OIDC provider
`envoy_gateway`	API gateway
`etcdbackup`	etcd backup
`external_dns`	DNS record automation
`external_secrets`	Secrets management
`global_workflows`	Argo Events and Workflows
`ingress_nginx`	Ingress controller
`monitoring`	Prometheus/Grafana monitoring
`nautobot`	Network Source of Truth
`nautobotop`	Nautobot Kubernetes operator
`openebs`	Storage (if using OpenEBS)
`openstack_resource_controller`	OpenStack resource operator
`opentelemetry_operator`	OpenTelemetry operator
`otel_collector`	Observability collector
`rabbitmq_system`	RabbitMQ operator
`rook`	Storage (if using Rook/Ceph)
`sealed_secrets`	Sealed Secrets operator
`understack_cluster_issuer`	UnderStack cert-manager ClusterIssuer

For each component that requires environment-specific configuration, you
can provide:

Helm value overrides in my-global/<component>/values.yaml
Kustomize manifests in my-global/<component>/

See Configuring Components for details on these
customization methods.