Umbrella Operator

A Kubernetes operator that manages the lifecycle of Kuadrant components using Helm charts rendered at runtime. It replaces per-component operators (authorino-operator, limitador-operator, mcp-gateway-controller) with a single operator that owns component CRs and deploys workloads directly.

Motivation

OLMv1 removes automatic dependency resolution. Kuadrant currently relies on OLMv0 dependency declarations to install component operators. The umbrella operator eliminates these dependencies by:

• Making Helm the primary installation mechanism across all Kubernetes distributions
• Deploying component workloads directly instead of through intermediate operators
• Providing a single OLM package with zero dependency declarations
• Supporting automated migration from existing OLMv0 installations

See RFC: Evolving the Kuadrant Deployment for the full design.

How It Works

1. The operator watches component CRs (e.g. MCPGatewayExtension)
2. On reconcile, it maps the CR spec fields to Helm values
3. It renders the component's Helm chart using the Helm Go SDK (ClientOnly=true, DryRun=true)
4. It applies the rendered manifests via server-side apply

For existing OLMv0 installations, the operator detects resources created by the old component operator (via ownerReferences) and runs a migration sequence: scale down the old operator, strip ownerReferences, apply Helm-rendered resources.

PoC: MCP Gateway Migration

This branch demonstrates the pattern with mcp-gateway. It proves:

• The umbrella operator can deploy mcp-gateway from a single MCPGatewayExtension CR
• It can migrate from an existing OLMv0-managed mcp-gateway installation without disruption
• CR spec changes propagate to the deployed workloads

Prerequisites

• Go 1.24+
• kind
• Helm
• operator-sdk
• kubectl
• Docker

Run the PoC

1. Set up a kind cluster with OLMv0 and mcp-gateway installed via OLM:

make local-olmv0-setup

This creates a kind cluster and installs:

• Gateway API CRDs
• Istio (via Sail operator)
• OLMv0
• Kuadrant operator catalog (OLM dependency)
• mcp-gateway via OLM subscription (installs the full kuadrant stack)
• A Gateway resource and MCPGatewayExtension CR

Wait for the broker-router to be ready. This takes ~5 minutes.

2. Verify the OLMv0 starting state:

# All operators running
kubectl get deployments -n mcp-system

# Broker-router has ownerReferences to the MCPGatewayExtension CR
kubectl get deployment mcp-gateway -n mcp-system -o jsonpath='{.metadata.ownerReferences}' | python3 -m json.tool

3. Run the umbrella operator to migrate:

make local-run

The operator will:

• Detect the OLMv0-managed resources (ownerReferences present)
• Scale down the mcp-controller to 0
• Strip ownerReferences from all managed resources
• Apply Helm-rendered resources via server-side apply
• Log migration complete followed by successfully reconciled MCPGatewayExtension

4. Verify migration completed:

# ownerReferences stripped (empty output)
kubectl get deployment mcp-gateway -n mcp-system -o jsonpath='{.metadata.ownerReferences}'

# Controller scaled to 0
kubectl get deployment mcp-gateway-controller -n mcp-system -o jsonpath='{.spec.replicas}'

# Broker-router still running
kubectl get pods -n mcp-system -l app.kubernetes.io/name=mcp-gateway

5. Verify CR changes propagate:

kubectl patch mcpgatewayextension mcp-gateway-extension -n mcp-system \
  --type=merge \
  -p '{"spec":{"publicHost":"mcp.changed.example.com","backendPingIntervalSeconds":300}}'

# Check deployment updated
kubectl get deployment mcp-gateway -n mcp-system \
  -o jsonpath='{.spec.template.spec.containers[0].command}' | python3 -m json.tool

# Check HTTPRoute updated
kubectl get httproute mcp-gateway-route -n mcp-system -o jsonpath='{.spec.hostnames}'

6. Tear down:

make local-teardown

Fresh install (no OLMv0)

To test the operator deploying mcp-gateway from scratch (no migration):

make local-setup

Then create an MCPGatewayExtension CR:

kubectl apply -f config/local/olmv0/mcpgatewayextension.yaml

Project Structure

├── charts/mcp-gateway/        # Reshaped Helm chart (deploys workloads directly)
├── cmd/main.go                # Operator entrypoint
├── config/local/              # Local development configs (Istio, OLMv0)
├── internal/controller/
│   ├── helm.go                # Chart rendering and manifest application
│   ├── mcpgatewayextension_controller.go  # Reconciler (CR spec → Helm values → apply)
│   └── migration.go           # OLMv0 migration detection and execution
├── Makefile                   # Build, local-setup, local-olmv0-setup targets
└── go.mod

License

Copyright 2026.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.