Cluster-Forge

Important

Instructions for installing the AMD Enterprise AI reference stack (for most users) are here

A Kubernetes platform automation tool that deploys AMD Enterprise AI reference stack with complete GitOps infrastructure.

Table of Contents

• Overview
• Quick Start
• Architecture
• Components
• Configuration
• Documentation
• License

Overview

Cluster-Forge bundles third-party, community, and in-house components into a single, GitOps-managed stack deployable in Kubernetes clusters. It automates the deployment of a complete AI/ML compute platform with all essential services pre-configured and integrated.

Using a bootstrap-first deployment model, Cluster-Forge establishes GitOps infrastructure (ArgoCD, Gitea, OpenBao) before deploying the complete application stack via ArgoCD's app-of-apps pattern.

Ideal for:

• AI/ML Engineers - Unified platform for model training, serving, and orchestration
• Platform Engineers - Infrastructure automation with GitOps patterns
• DevOps Teams - Consistent deployment across development, staging, and production
• Research Teams - Ephemeral test clusters for experimentation

🚀 Quick Start

Cluster-Forge is deployed by cluster-bloom, which bootstraps the GitOps foundation (ArgoCD, Gitea, OpenBao) and installs the stack via its deploy_clusterforge role. Deployment options (domain, cluster size, enabled/disabled apps, GPU stack family, image repositories) are supplied as cluster-bloom configuration and injected at deploy time.

For end-to-end installation instructions, follow the official AMD Enterprise AI reference stack docs:

➡️ On-Premises Installation Guide

📋 Architecture

Bootstrap-First Deployment

Cluster-Forge uses a three-phase bootstrap process:

Phase 1: Pre-Cleanup

• Detects and removes previous installations when applicable
• Ensures clean state for fresh deployments

Phase 2: GitOps Foundation Bootstrap (Manual Helm Templates)

1. ArgoCD (v8.3.5) - GitOps controller deployed via helm template
2. Gitea (v12.3.0) - Git server with initialization job

Phase 3: App-of-Apps Deployment (ArgoCD-Managed)

• Creates cluster-forge Application pointing to root/ helm chart
• ArgoCD syncs all remaining applications including OpenBao from enabledApps list
• Applications deployed in wave order (-70 to 0) based on dependencies
• OpenBao (v0.18.2) managed via ArgoCD with openbao-init job

Dual Repository GitOps Pattern

Local Mode (Default) - Self-contained cluster-native GitOps:

• Uses local Gitea for both cluster-forge and cluster-values repositories
• Zero external dependencies once bootstrapped
• Initialization handled by gitea-init-job

External Mode - Traditional GitHub-based GitOps:

• Points to external GitHub repository
• Supports custom branch selection for testing

See Values Inheritance Pattern for detailed architecture.

🛠️ Components

Layer 1: GitOps Foundation

• ArgoCD 8.3.5 - GitOps continuous deployment controller
• Gitea 12.3.0 - Self-hosted Git server with SQLite backend
• OpenBao 0.18.2 - Vault-compatible secrets management
• External Secrets 0.15.1 - Secrets synchronization operator

Layer 2: Core Infrastructure

Networking & Security:

• Envoy Gateway v1.7.1 - Gateway API implementation for ingress and routing
• Envoy AI Gateway v0.6.0 - AI/LLM-aware gateway with InferencePool routing
• Inference Extension CRDs v1.5.0 - Gateway API Inference Extension resources
• MetalLB v0.15.2 - Bare metal load balancer
• Cert-Manager v1.18.2 - Automated TLS certificate management
• Kyverno 3.5.1 - Policy engine with modular policy system

Storage & Database:

• CNPG Operator 0.26.0 - CloudNativePG PostgreSQL operator
• SeaweedFS Operator - S3-compatible object storage operator, with S3 storage deployment, default-bucket, models, and datasets buckets

Layer 3: Observability

• Prometheus Operator CRDs 23.0.0 - Metrics infrastructure
• OpenTelemetry Operator 0.93.1 - Telemetry collection
• OTEL-LGTM Stack v1.0.7 - Integrated observability (Loki, Grafana, Tempo, Mimir)

Layer 4: Identity & Access

• Keycloak 26.0.0 - Enterprise IAM with AIRM realm
• Cluster-Auth 0.5.9 - Kubernetes RBAC integration

Layer 5: AI/ML Compute Stack

GPU & Scheduling:

• AMD GPU Operator v1.4.1 - GPU device plugin and drivers
• KubeRay Operator 1.4.2 - Ray distributed computing framework
• Kueue 0.13.0 - Job queueing with multi-framework support
• AppWrapper v1.1.2 - Application-level resource scheduling
• KEDA 2.18.1 - Event-driven autoscaling

ML Serving & Inference:

• KServe v0.16.0 - Model serving platform (Standard deployment mode)
• AIM Engine 0.2.5 - AMD Inference Microservice engine

Workflow & Messaging:

• Kaiwo v0.2.1 - AI workload orchestration
• RabbitMQ v2.15.0 - Message broker for async processing

Layer 6: AIRM Application

• AIRM 2.0.0 - AMD Resource Manager application suite
• AIWB 2.0.0 - AI Workbench application suite
• AIM Cluster Model Source - Cluster resource models for AIRM
• Configurable Image Repositories - Supports custom container registries via cluster-bloom AIRM_IMAGE_REPOSITORY parameter

� Configuration

Cluster Sizing

Three cluster profiles with inheritance-based resource optimization:

Small Clusters (1-5 users, dev/test):

• Single replica deployments
• Reduced resource limits (ArgoCD controller: 2 CPU, 4Gi RAM)
• Adds kyverno-policies-storage-local-path for RWX→RWO PVC mutation
• SeaweedFS volume storage: 250Gi
• Suitable for: Local workstations, development environments

Medium Clusters (5-20 users, team production):

• Requires a minimum of 20 CPU cores
• Single replica with moderate resource allocation
• Same storage policies as small (local-path support)
• ArgoCD controller: 2 CPU, 4Gi RAM
• Default configuration for balanced performance
• Suitable for: Small teams, staging environments

Large Clusters (10s-100s users, enterprise scale):

• Requires a minimum of 20 CPU cores
• OpenBao HA: 3 replicas with Raft consensus
• No local-path policies (assumes distributed storage)
• SeaweedFS volume storage: 500Gi
• Production-grade resource allocation
• Suitable for: Production deployments, multi-tenant environments

See Cluster Size Configuration for detailed specifications.

Values Files

Configuration follows a streamlined inheritance pattern:

• Base: Common applications with alpha-sorted enabledApps
• Size-specific: Only override differences from base (DRY principle)
• Runtime: Domain and cluster-specific parameters injected during bootstrap

Deployment uses YAML merge semantics where size-specific values override base values.yaml settings.

📚 Documentation

Comprehensive documentation is available in the /docs folder:

Topic	Documentation
Getting Started	On-Premises Installation Guide
Configuration	Cluster Size Configuration · Configuration Reference
Architecture	Values Inheritance Pattern
AIM Catalog	AIM model catalog lifecycle · Adding AIM catalog models
Policy System	Kyverno Modular Design
Storage Policies	Kyverno Access Mode Policy
Operations	Backup and Restore
CI/CD	Workflow Documentation

Additional documentation:

• Configuration reference: docs/configuration-reference.md — Root helmParameters, script env vars, platform gates
• Install helpers: scripts/README.md
• SBOM: See /sbom folder for software bill of materials generation and validation

📝 License

Cluster-Forge is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

---

Give Cluster-Forge a try and let us know how it works for you!