System Architecture

UIS follows a two-tier architecture that separates cluster management from cluster workloads. A containerized management environment (the provision host) deploys and manages services on any Kubernetes cluster.

Core Principles

Separation of Management and Runtime

• Provision Host contains ALL tools needed to manage the cluster
• Cluster runs ONLY application workloads and services
• Management happens through standard Kubernetes APIs

Self-Contained Management Environment

• All management tools isolated in the provision host container
• Same tool versions across all environments
• Works identically on any host machine

Declarative Configuration

• All cluster state defined in manifests and playbooks
• Same configuration produces identical results everywhere
• All configuration tracked in Git

Tier 1: Provision Host (Management Layer)

The provision host is a container image that includes everything needed to deploy and manage services. You interact with it through the ./uis CLI on your host machine.

What's Inside

The container image contains:

• Ansible playbooks — Service deployment logic for all 26+ services
• Helm charts — Templated Kubernetes deployments
• Kubernetes manifests — Declarative service definitions
• UIS CLI — The uis-cli.sh command dispatcher

Pre-installed Tools

• kubectl, helm — Kubernetes management
• ansible — Infrastructure automation
• k9s — Terminal-based Kubernetes dashboard
• jq, yq — JSON/YAML processing
• git, curl, wget — Development utilities

Your Local Configuration

Two directories on your host machine are mounted into the container:

• .uis.extend/ — Enabled services, cluster settings, tool preferences
• .uis.secrets/ — Passwords, API keys, certificates (gitignored)

These are the only files you manage locally. Everything else is baked into the container image.

Tier 2: Kubernetes Cluster (Runtime Layer)

The cluster provides container orchestration for all application services. UIS supports multiple runtime options:

Option	Use Case
Rancher Desktop	Local development (default)
Azure AKS	Production cloud
Ubuntu Server	Self-hosted production
Raspberry Pi	Edge computing, home lab

Deployment Flow

Using the CLI

Stack Deployment

Deploy a full package of related services:

Multi-Cluster Management

The same provision host can manage multiple Kubernetes clusters by switching kubeconfig contexts:

Switch between clusters with:

./uis shell
kubectl config use-context rancher-desktop
kubectl config use-context azure-aks

The same ./uis deploy commands work identically on any cluster — only the Kubernetes endpoint changes.

Learn More

• How Deployment Works — Deep dive into the deploy flow, dependency resolution, health checks, and stacks