Kubernetes

​

Overview

​

Architecture

• Platform namespace — Core services: Django web UI, AMS (Agent Management Service), BuildKit, PostgreSQL, Redis, MinIO
• Agents namespace — Each agent gets its own FastAPI deployment, Celery worker, PostgreSQL database, Redis cache, and Ingress with a unique subdomain

​

Prerequisites

​

Start Installation

1

Download Installation Files

Clone the AgentOS Builder repository and navigate to the Kubernetes installer:

Copy

git clone https://github.com/Upsonic/AgentOS-Builder.git
cd AgentOS-Builder/k8s

This directory contains the installer, update script (update.py), and example configuration (platform-config-example.yaml).

2

Run the Installer

Start the installer container. It mounts your kubeconfig for cluster access:

Copy

docker run -d --name agentos-installer \
  -p 5000:5000 \
  -v ~/.kube/config:/root/.kube/config:ro \
  upsonic/agentos-installer:latest

Then open the wizard in your browser:

Copy

http://<SERVER_IP>:5000

Use your server’s actual IP address, not localhost, if you are accessing from a different machine.

3

Cluster Configuration

Select your cluster type and configure namespaces.

• Cluster type — K3s, EKS, GKE, AKS, Kind, bare-metal
• Platform namespace — Where core services run (default: platform)
• Agents namespace — Where agents are deployed (default: agents)

The installer automatically detects your cluster and validates connectivity.

4

Registry Configuration

Configure the container registry for agent images.

• Registry URL — Docker Hub (docker.io/upsonic) or a private registry
• Docker Hub username and access token — Required to pull and push agent images

5

Networking

Configure your domain, load balancer, and TLS settings.

• Domain — Base domain for the platform (e.g., mycompany.com)
• Ingress class — Usually nginx (installed automatically if missing)
• Load balancer — Auto-detected: Klipper (K3s), MetalLB (bare-metal), or Cloud LB (EKS/GKE/AKS)
• TLS — Enable for automatic HTTPS via Let’s Encrypt (requires valid domain and email)

When TLS is enabled, configure cert-manager for automatic certificate provisioning:

If your K3s cluster already has Klipper (ServiceLB) running, the installer will detect it and skip MetalLB installation.

6

Storage

Select the storage class for persistent volumes (databases, file storage).The installer auto-detects available storage classes in your cluster and recommends the best option:

• K3s / Kind — local-path
• EKS — gp3 or gp2
• GKE — standard or premium-rwo
• AKS — managed-csi

7

Credentials

Set up your admin account and platform secrets.

• Admin email and password — For the AgentOS management interface
• Database passwords — Auto-generated, can be customized
• Secret key and Bearer token — Auto-generated for secure inter-service communication

8

Review & Deploy

Review all configuration settings and click Deploy.The installer runs the full deployment pipeline:

1. Create namespaces
2. Install NGINX Ingress Controller
3. Configure Load Balancer
4. Install cert-manager (if TLS enabled)
5. Create secrets
6. Deploy MinIO (object storage)
7. Configure agent registry
8. Deploy Platform (Django web UI)
9. Deploy AMS (Agent Management Service)
10. Configure Ingress routes
11. Configure TLS certificates
12. Deploy Loki (log aggregation)
13. Verify deployment

​

Access Your AgentOS

​

DNS Setup

*.yourdomain.com    →  A  →  <CLUSTER_EXTERNAL_IP>

192.168.1.100  agentos.localhost ams.localhost myagent.agents.localhost

​

Updating AgentOS

cd AgentOS-Builder/k8s
python update.py --dry-run           # Preview changes
python update.py                     # Apply updates to all components
python update.py --component agents  # Update only agents

​

Configuration Reference

cp platform-config-example.yaml platform-config.yaml
# Edit platform-config.yaml with your settings
python update.py

​

Next Steps