142 lines
5.2 KiB
Markdown
142 lines
5.2 KiB
Markdown
# RIG Operator (Resource Infrastructure Gateway)
|
|
|
|
**RIG Operator** is a Kubernetes operator designed to decouple **Infrastructure Management** (Quotas, Credentials, Providers) from **Cluster Provisioning** (Kubernetes versions, Node sizing).
|
|
|
|
It replaces legacy monolithic provisioners with a **Strategy-Pattern Architecture**, allowing a single operator to manage hybrid fleets (Harvester, vSphere, etc.) using a unified API while strictly enforcing resource quotas.
|
|
|
|
---
|
|
|
|
## 🏗 Architecture & Design
|
|
|
|
### The Problem
|
|
Legacy controllers often mix concerns:
|
|
* *Hardcoded Providers:* Adding vSphere requires rewriting the main loop.
|
|
* *No Accounting:* Users can provision infinite clusters until the underlying storage fills up.
|
|
* *Tight Coupling:* Helm values, RKE2 configs, and VM details are mashed into one huge struct.
|
|
|
|
### The RIG Solution
|
|
RIG segregates responsibilities into three distinct layers, acting as a **Gatekeeper** and **Router**.
|
|
|
|
|
|
|
|
#### 1. The Data Model (Blueprints)
|
|
* **`InfraBlueprint` (The Accountant):** Owned by Platform Admins. Defines **Quotas** (CPU/RAM/Disk), **Credentials**, and points to the specific Provider Config. It automatically tracks usage across all child clusters.
|
|
* **`ClusterBlueprint` (The Request):** Owned by Users. Defines **What** is needed (e.g., "3 nodes, 4 CPU, 16GB RAM") but not **How** it is provided.
|
|
* **`HarvesterBlueprint` / `VsphereBlueprint` (The Tech Specs):** Holds low-level details (Image names, Networks, VM Namespaces).
|
|
|
|
#### 2. The Logic Flow
|
|
1. **Gatekeeper:** Before doing anything, the Controller checks `Infra.Quota`. If `(Used + Request) > Max`, provisioning is **blocked**.
|
|
2. **Router:** The Controller reads `Infra.ProviderRef` and dynamically loads the correct **Strategy** (Harvester vs. vSphere).
|
|
3. **Builder:** A generic `MasterBuilder` combines the Strategy's output with a Base Helm Template to generate the final values.
|
|
|
|
---
|
|
|
|
## 📂 Project Structure
|
|
|
|
| Directory | Role | Description |
|
|
| :--- | :--- | :--- |
|
|
| `api/v1alpha1` | **The Contract** | Defines the CRDs (`ibp`, `cbp`, `hbp`). |
|
|
| `internal/controller` | **The Brain** | `ClusterBlueprint` (Provisioning/Gatekeeping) & `InfraBlueprint` (Accounting). |
|
|
| `internal/provider` | **The Interface** | Defines the `Strategy` interface that all clouds must obey. |
|
|
| `internal/provider/harvester`| **The Implementation** | Logic specific to Harvester (Identity minting, NodePool mapping). |
|
|
| `internal/builder` | **The Assembler** | Merges Strategy output with Helm Templates. Agnostic to the cloud provider. |
|
|
| `internal/helm` | **The Tool** | Wrapper around the Helm SDK (OCI supported). |
|
|
| `internal/templates` | **The Defaults** | Embedded YAML files containing default values (CPU/RAM, UserData). |
|
|
|
|
---
|
|
|
|
## 🚀 Development Workflow
|
|
|
|
### Prerequisites
|
|
* Go 1.22+
|
|
* Helm v3 (Binary)
|
|
* Kubernetes Cluster (or local Kind/Minikube)
|
|
* `kubectl` pointing to your dev cluster
|
|
|
|
### 1. Common Commands
|
|
|
|
**Initial Setup (Download Dependencies):**
|
|
```bash
|
|
go mod tidy
|
|
|
|
```
|
|
|
|
**Update APIs (CRDs):**
|
|
*Run this whenever you edit `api/v1alpha1/*.go*`
|
|
|
|
```bash
|
|
make manifests generate
|
|
|
|
```
|
|
|
|
**Run Locally:**
|
|
*Runs the controller against your current `~/.kube/config` context.*
|
|
|
|
```bash
|
|
make install run
|
|
|
|
```
|
|
|
|
### 2. Debugging (VS Code / Delve)
|
|
|
|
`make run` is great for logs, but if you need to set breakpoints (e.g., to inspect the Helm Values map before it applies), use the debugger.
|
|
|
|
**VS Code `launch.json` Configuration:**
|
|
|
|
```json
|
|
{
|
|
"version": "0.2.0",
|
|
"configurations": [
|
|
{
|
|
"name": "Debug RIG Operator",
|
|
"type": "go",
|
|
"request": "launch",
|
|
"mode": "auto",
|
|
"program": "${workspaceFolder}/cmd/main.go",
|
|
"args": [],
|
|
"env": {
|
|
"KUBECONFIG": "${userHome}/.kube/config"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
|
|
```
|
|
|
|
1. Select **"Debug RIG Operator"** from the Run menu.
|
|
2. Set a breakpoint in `internal/controller/clusterblueprint_controller.go` (e.g., inside the `Reconcile` loop).
|
|
3. Apply a generic cluster manifest to trigger the breakpoint.
|
|
|
|
---
|
|
|
|
## 🛠 Maintenance Guide
|
|
|
|
### "I need to add a new field..."
|
|
|
|
| Scenario | Files to Touch | Command to Run |
|
|
| --- | --- | --- |
|
|
| **Add a field to the API** (e.g., `ProxyURL` to Infra) | `api/v1alpha1/infrablueprint_types.go` | `make manifests generate` |
|
|
| **Update Default CPU/RAM** | `internal/templates/harvester/values.yaml` | `make build` (Recompiles embedded file) |
|
|
| **Change Harvester UserData logic** | `internal/provider/harvester/strategy.go` | `go test ./...` |
|
|
| **Add a new Cloud Provider (e.g. AWS)** | 1. Create `api/.../awsblueprint_types.go`<br>
|
|
|
|
<br>2. Create `internal/provider/aws/strategy.go`<br>
|
|
|
|
<br>3. Update `controller` switch case. | `make manifests generate` |
|
|
|
|
### "The Quota isn't updating!"
|
|
|
|
Remember that the **InfraController** is responsible for math. It watches `ClusterBlueprint` events.
|
|
|
|
1. Check logs: `kubectl logs -l control-plane=controller-manager`
|
|
2. Ensure your Cluster actually points to the correct Infra name (`spec.infraBlueprintRef`).
|
|
|
|
---
|
|
|
|
## 📊 Documentation & Diagrams
|
|
|
|
Visual flows (Mermaid) are available in the `docs/` folder:
|
|
|
|
* `docs/flow-diagram.svg`: High-level Request Flow.
|
|
* `docs/controllerflow.mermaid`: Detailed Controller logic.
|