Rossoctl Components
This document provides detailed information about each component of the Rossoctl platform.
Table of Contents
- Overview
- Architecture Diagram
- Agent Lifecycle Operator
- MCP Gateway
- Plugins adapter
- Rossoctl UI
- Identity & Auth Bridge
- Infrastructure Services
- Supported Agent Frameworks
- Communication Protocols
Overview
Rossoctl is a cloud-native middleware providing a framework-neutral, scalable, and secure platform for deploying and orchestrating AI agents through a standardized REST API. It addresses the gap between agent development frameworks and production deployment by providing:
- Authentication and Authorization — Secure access control for agents and tools
- Trusted Identity — SPIRE-managed workload identities
- Deployment & Configuration — Kubernetes-native lifecycle management
- Scaling & Fault-tolerance — Auto-scaling and resilient deployments
- Discovery — Agent and tool discovery via A2A protocol
- Persistence — State management for agent workflows
Value Proposition
Despite the extensive variety of frameworks available for developing agent-based applications, there is a distinct lack of standardized methods for deploying and operating agent code in production environments, as well as for exposing it through a standardized API. Agents are adept at reasoning, planning, and interacting with various tools, but their full potential can be limited by deployment challenges.
Rossoctl addresses this gap by enhancing existing agent frameworks with production-ready infrastructure.
For a detailed architecture diagram showing component interactions and data flow, see Technical Details.
Architecture Diagram
All the Rossoctl components and their deployment namespaces
┌───────────────────────────────────────────────────────────────────────┐
│ Kubernetes Cluster │
├───────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ rossoctl-system Namespace │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Rossoctl UI │ │ Shipwright │ │ Ingress │ │ Kiali │ │ │
│ │ │ │ │ (Builds) │ │ Gateway │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Workload Namespaces (team1, team2, ...) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ A2A Agents │ │ MCP Tools │ │ Custom │ │ │
│ │ │ (LangGraph, │ │ (weather, │ │ Workloads │ │ │
│ │ │ CrewAI, │ │ slack, │ │ │ │ │
│ │ │ AG2...) │ │ fetch...) │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ |
│ │ gateway-system │ │ mcp-system │ │
│ │ ┌──────────────┐ │ │ ┌──────────────┐ │ │
│ │ │ MCP Gateway │ │ │ │ MCP Broker │ │ │
│ │ │ (Envoy) │ │ │ │ Controller │ │ │
│ │ └──────────────┘ │ │ └──────────────┘ │ │
│ └────────────────────┘ └────────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────────┐ │
│ │ SPIRE │ │ IAM │ │ Istio Ambient │ │
│ │ (Identity) │ │(e.g. Keycloak) | │ (Service Mesh) │ │
│ └────────────────┘ └────────────────┘ └────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────┘
Agent Deployment Architecture
Rossoctl deploys agents using standard Kubernetes workloads (Deployments + Services), providing a simple, portable, and operator-free deployment model.
Capabilities
| Feature | Description |
|---|---|
| Agent Deployment | Deploy agents from source code or container images as Kubernetes Deployments |
| Build Automation | Build agent containers using Shipwright with Buildah |
| Lifecycle Management | Standard Kubernetes Deployment lifecycle (rolling updates, rollbacks, scaling) |
| Configuration Management | Environment variables, secrets, and config maps via Deployment spec |
| Multi-Namespace Support | Deploy agents to isolated team namespaces |
Container Build System
Rossoctl uses Shipwright for building container images from source:
| Strategy | Use Case | Description |
|---|---|---|
buildah-insecure-push | Internal registries | For registries without TLS (dev/Kind clusters) |
buildah | External registries | For registries with TLS (quay.io, ghcr.io, docker.io) |
Shipwright Build Flow:
- UI creates a Shipwright
BuildCR with source configuration - UI creates a
BuildRunCR to trigger the build - UI polls
BuildRunstatus until completion - On success, UI creates the Deployment + Service for the agent
Agent Resources
Agents are deployed as standard Kubernetes resources:
# Deployment - Manages agent pods
apiVersion: apps/v1
kind: Deployment
metadata:
name: weather-service
namespace: team1
labels:
protocol.rossoctl.io/a2a: ""
rossoctl.io/framework: LangGraph
app.kubernetes.io/name: weather-service
app.kubernetes.io/managed-by: rossoctl-ui
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: weather-service
template:
metadata:
labels:
protocol.rossoctl.io/a2a: ""
app.kubernetes.io/name: weather-service
spec:
containers:
- name: agent
image: ghcr.io/rossoctl/weather-service:latest
env:
- name: PORT
value: "8000"
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: openai-secret
key: api-key
ports:
- containerPort: 8000
name: http
# Service - Exposes the agent within the cluster
apiVersion: v1
kind: Service
metadata:
name: weather-service
namespace: team1
labels:
app.kubernetes.io/name: weather-service
spec:
type: ClusterIP
selector:
app.kubernetes.io/name: weather-service
ports:
- name: http
port: 8080
targetPort: 8000
# AgentRuntime - Enrolls the workload with the rossoctl-operator.
# The operator applies the rossoctl.io/type label and triggers
# AuthBridge sidecar injection automatically.
apiVersion: agent.rossoctl.dev/v1alpha1
kind: AgentRuntime
metadata:
name: weather-service
namespace: team1
labels:
app.kubernetes.io/name: weather-service
spec:
type: agent
targetRef:
apiVersion: apps/v1
kind: Deployment
name: weather-service
# Shipwright Build - For building from source
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
name: weather-service
labels:
rossoctl.io/type: agent
protocol.rossoctl.io/a2a: ""
spec:
source:
type: Git
git:
url: https://github.com/rossoctl/examples
revision: main
contextDir: a2a/weather_service
strategy:
name: buildah-insecure-push # or "buildah" for external registries
kind: ClusterBuildStrategy
output:
image: registry.cr-system.svc.cluster.local:5000/weather-service:v0.0.1
Architecture
┌─────────────────────────────────────────────────────┐
│ Rossoctl UI │
├─────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Import │ │ Build │ │ Deploy │ │
│ │ Agent │ │ (Source) │ │ Agent │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Kubernetes API Server │ │
│ │ (Deployment, Service, Build, HTTPRoute) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
Label Standards
All agent workloads use consistent labels for discovery:
| Label | Value | Purpose |
|---|---|---|
rossoctl.io/type | agent | Identifies resource as a Rossoctl agent (operator-managed via AgentRuntime CR) |
protocol.rossoctl.io/<name> | "" | Protocol support (e.g. protocol.rossoctl.io/a2a) |
rossoctl.io/framework | LangGraph, CrewAI, etc. | Agent framework |
app.kubernetes.io/name | <agent-name> | Standard K8s app name |
app.kubernetes.io/managed-by | rossoctl-ui | Resource manager |
MCP Gateway
Repository: Kuadrant/mcp-gateway
The MCP Gateway provides a unified entry point for Model Context Protocol (MCP) servers and tools. It acts as a "front door" for all MCP-based tool interactions.
Capabilities
| Feature | Description |
|---|---|
| Tool Discovery | Automatic discovery and registration of MCP servers |
| Routing | Route agent requests to appropriate MCP tools |
| Authentication | OAuth/token-based authentication for tool access |
| Load Balancing | Distribute requests across tool replicas |
Components
| Component | Namespace | Purpose |
|---|---|---|
mcp-gateway-istio | gateway-system | Envoy proxy for request routing |
mcp-controller | mcp-system | Manages MCPServerRegistration custom resources |
mcp-broker-router | mcp-system | Routes requests to registered MCP servers |
Registering Tools with the Gateway
Tools are registered using Kubernetes Gateway API resources:
# HTTPRoute - Define routing to MCP server
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: weather-tool-route
labels:
mcp-server: "true"
spec:
parentRefs:
- name: mcp-gateway
namespace: gateway-system
hostnames:
- "weather-tool.mcp.local"
rules:
- backendRefs:
- name: weather-tool
port: 9090
# MCPServerRegistration - Register with the gateway
apiVersion: mcp.kuadrant.io/v1alpha1
kind: MCPServerRegistration
metadata:
name: weather-tool-servers
spec:
toolPrefix: weather_
targetRef:
group: gateway.networking.k8s.io
kind: HTTPRoute
name: weather-tool-route
For detailed gateway configuration, see MCP Gateway Instructions.
MCP Tool Builds with Shipwright
Similar to agents, MCP tools can be built from source using Shipwright. The build process is:
- UI creates a Shipwright
BuildCR with source configuration - UI creates a
BuildRunCR to trigger the build - UI polls
BuildRunstatus until completion - On success, UI creates a Deployment + Service for the MCP tool
# Shipwright Build for MCP Tool
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
name: weather-tool
labels:
rossoctl.io/type: tool
protocol.rossoctl.io/streamable_http: ""
spec:
source:
type: Git
git:
url: https://github.com/rossoctl/examples
revision: main
contextDir: mcp/weather_tool
strategy:
name: buildah-insecure-push
kind: ClusterBuildStrategy
output:
image: registry.cr-system.svc.cluster.local:5000/weather-tool:v0.0.1
# Deployment - Manages MCP tool pods
apiVersion: apps/v1
kind: Deployment
metadata:
name: weather-tool
namespace: team1
labels:
protocol.rossoctl.io/mcp: ""
rossoctl.io/transport: streamable_http
app.kubernetes.io/name: weather-tool
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: weather-tool
template:
metadata:
labels:
protocol.rossoctl.io/mcp: ""
rossoctl.io/transport: streamable_http
app.kubernetes.io/name: weather-tool
spec:
containers:
- name: mcp
image: registry.cr-system.svc.cluster.local:5000/weather-tool:v0.0.1
ports:
- containerPort: 8000
name: http
# AgentRuntime - Enrolls the tool with the rossoctl-operator
apiVersion: agent.rossoctl.dev/v1alpha1
kind: AgentRuntime
metadata:
name: weather-tool
namespace: team1
labels:
app.kubernetes.io/name: weather-tool
spec:
type: tool
targetRef:
apiVersion: apps/v1
kind: Deployment
name: weather-tool
For detailed tool deployment instructions, see Importing a New Tool.
Plugins Adapter
Repository: rossoctl/plugins-adapter
The Plugins Adapter enables dynamic plugin loading and execution within Envoy-based gateways, including the MCP gateway, via Envoy's External Processing API (ext_proc). It allows runtime extension of gateway capabilities without recompiling or redeploying the gateway.
Capabilities
| Feature | Description |
|---|---|
| Dynamic Plugin Loading | Load and update plugins without traffic disruption |
| Request/Response Control | Inspect, modify, or block based on headers and body |
| Bring-Your-Own (BYO) Logic | Implement plugins in any language |
| Guardrails Enforcement | Implement security policies, content filtering, and compliance checks |
Rossoctl UI
Location: rossoctl/ui-v2/
A modern web dashboard built with React (PatternFly frontend and FastAPI backend for managing agents and tools.
Architecture
| Component | Technology | Description |
|---|---|---|
| Frontend | React + PatternFly | Single-page application served by nginx |
| Backend | FastAPI + Python | REST API for Kubernetes interactions |
Features
| Feature | Description |
|---|---|
| Agent Import | Import A2A agents from any framework via Git URL or container image |
| Tool Deployment | Deploy MCP tools directly from source or container image |
| Interactive Testing | Chat interface to test agent capabilities |
| Monitoring | View traces, logs, and network traffic via Phoenix (optional) and Kiali |
| Authentication | Keycloak-based login/logout with OAuth2 |
| MCP Gateway | Browse and test MCP tools via MCP Inspector |
Pages
| Page | Purpose |
|---|---|
| Home | Overview and quick actions |
| Agents | List, import, and manage agents |
| Tools | List, import, and manage MCP tools |
| MCP Gateway | View MCP Gateway status and launch MCP Inspector |
| Observability | Access Phoenix traces (when enabled) and Kiali network dashboards |
| Admin | Keycloak and system configuration |
Access
# Kind cluster
open http://rossoctl-ui.localtest.me:8080
# OpenShift
kubectl get route rossoctl-ui -n rossoctl-system -o jsonpath='{.status.ingress[0].host}'
Identity & Auth Bridge
Repository: rossoctl/cortex/AuthBridge
Rossoctl provides a unified framework for identity and authorization in agentic systems, replacing static credentials with dynamic, short-lived tokens. We call this collection of assets Auth Bridge.
Auth Bridge solves a critical challenge in microservices and agentic architectures: how can workloads authenticate and communicate securely without pre-provisioned static credentials?
Auth Bridge Components
| Component | Purpose | Repository |
|---|---|---|
| AuthProxy | Inbound JWT validation (JWKS) and outbound token exchange | AuthBridge/AuthProxy |
| SPIRE | Workload identity and attestation | External |
| Keycloak | Identity provider and access management | External |
Keycloak Client Registration (Operator-Managed)
Keycloak client registration is handled by the rossoctl-operator's ClientRegistrationReconciler controller:
- Reconciles AgentRuntime CRs to apply
rossoctl.io/typelabels to target workloads and trigger sidecar injection - Uses SPIFFE ID as client identifier (e.g.,
spiffe://localtest.me/ns/team/sa/my-agent) - Reads Keycloak admin credentials from the operator namespace (
rossoctl-system) - Creates a secret in the agent namespace containing client credentials
- Eliminates the need for admin credentials in agent namespaces
AuthProxy
An Envoy-based sidecar that handles both inbound JWT validation and outbound token exchange, using an external processor (ext-proc) for token operations:
Incoming request
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ WORKLOAD POD │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AuthProxy Sidecar (Envoy + Ext Proc) │ │
│ │ │ │
│ │ INBOUND: Validate JWT (signature, issuer, audience via │ │
│ │ JWKS). Return 401 if invalid. │ │
│ │ OUTBOUND: Exchange token for target audience via Keycloak │ │
│ │ (RFC 8693). HTTPS traffic passes through as-is. │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │ │
│ ┌─────┘ └─────┐ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Application │ │ Keycloak │ │
│ └──────────────┘ └──────────────┘ │
└────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────┐
│ TARGET SERVICE │
│ (aud: auth-target) │
└─────────────────────┘
Key Features:
- Inbound JWT Validation — Validates token signature, expiration, and issuer using JWKS keys fetched from Keycloak. Optionally validates the audience claim. Returns HTTP 401 for missing or invalid tokens.
- Outbound Token Exchange — Performs OAuth 2.0 Token Exchange (RFC 8693) to replace the caller's token with one scoped to the target service audience
- Transparent to applications — Traffic interception via iptables; no application code changes required
- Configuration — Inbound validation is configured via
ISSUER(required) andEXPECTED_AUDIENCE(optional) environment variables. Outbound exchange usesTOKEN_URL,CLIENT_ID,CLIENT_SECRET(provided by the operator via secret), andTARGET_AUDIENCE.
SPIRE (Workload Identity)
SPIRE provides cryptographic workload identities using the SPIFFE standard.
| Component | Purpose |
|---|---|
| SPIRE Server | Issues SVIDs (SPIFFE Verifiable Identity Documents) |
| SPIRE Agent | Node-level agent that attests workloads |
| CSI Driver | Mounts SVID certificates into pods |
Identity Format: spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>
Keycloak (Access Management)
Keycloak manages user authentication and OAuth/OIDC flows.
| Feature | Description |
|---|---|
| User Management | Create and manage Rossoctl users |
| Client Registration | OAuth clients for agents and UI (automated registration via rossoctl-operator's ClientRegistrationReconciler) |
| Token Exchange | Exchange tokens between audiences (RFC 8693) |
| SSO | Single sign-on across Rossoctl components |
Authorization Pattern
The Agent and Tool Authorization Pattern replaces static credentials with dynamic SPIRE-managed identities, enforcing least privilege and continuous authentication:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ User │────▶│ Keycloak │────▶│ Agent │────▶│ Tool │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────┐
│ SPIRE Server │
│ (Issues short-lived identities) │
└─────────────────────────────────────────┘
- User authenticates with Keycloak, receives access token
- Agent receives user context via delegated token
- Agent identity is attested by SPIRE
- Tool access uses exchanged tokens with minimal scope
Security Properties:
- No Static Secrets - Credentials are dynamically generated at pod startup
- Short-Lived Tokens - JWT tokens expire and must be refreshed
- Audience Scoping - Tokens are scoped to specific audiences, preventing reuse
- Transparent to Application - Token exchange is handled by the sidecar
For detailed overview of Identity and Authorization Patterns, see the Identity Guide.
Tornjak (SPIRE Management UI)
# UI
open http://spire-tornjak-ui.localtest.me:8080/
Infrastructure Services
Ingress Gateway
The Ingress Gateway routes external HTTP requests to internal services using the Kubernetes Gateway API.
- Namespace:
rossoctl-system - Implementation: Istio Gateway
Istio Ambient Mesh
Istio Ambient provides service mesh capabilities without sidecar proxies.
| Component | Purpose |
|---|---|
| Ztunnel | Node-local proxy for mTLS and traffic interception |
| Waypoint | Optional L7 proxy for advanced traffic policies |
Benefits:
- Zero-config mTLS between services
- No sidecar resource overhead
- Transparent to applications
Kiali (Service Mesh Observability)
Kiali provides visualization of the service mesh topology and traffic flows.
Phoenix (Tracing) -- Optional
LLM observability and tracing for agent interactions. Phoenix is disabled by default and can be enabled via components.phoenix.enabled: true in both the rossoctl-deps and rossoctl charts. Requires components.otel.enabled: true.
Skillberry Store (Skill Registry) -- Optional
In-cluster skillberry-store skill registry. Disabled by default; enabled via components.skillberryStore.enabled: true in the rossoctl chart (the Kind setup script's --with-skills flag sets it automatically). When enabled, the store runs as a single-replica Deployment (REST API on 8000, web UI on 8002, filesystem storage on a PVC at /data) and the chart seeds the rossoctl-skill-autosync-config ConfigMap so the backend autosync loop polls it — no external registry or --skill-registry-allowed-hosts allow-listing required. Behavior is additionally gated by featureFlags.externalSkills. The store UI is exposed via an HTTPRoute at http://skillberry-store.<domain>:8080, and the Rossoctl UI's "Manage in Skillberry Store" links point there (the ConfigMap also carries a store-ui-url the backend surfaces, since the in-cluster registry-url is server-side only and not browser-reachable).
Because the store serves its UI with the Vite dev server (which rejects unknown Host headers), the chart sets VITE_ALLOWED_HOSTS on the store pod to the gateway host (derived from skillberryStore.allowedHosts, defaulting to skillberry-store.<domain>) so the gateway URL works. This requires a store image with VITE_ALLOWED_HOSTS support (≥ 0.2.0).
The image defaults to ghcr.io/skillberry-ai/skillberry-store:0.2.0 and is overridable via skillberryStore.image.tag / skillberryStore.image.repository (Helm) or the SKILLBERRY_STORE_TAG / SKILLBERRY_STORE_IMAGE env vars (Kind setup script). Additional store environment variables can be injected via skillberryStore.extraEnv (a list of standard core/v1 EnvVar entries, so both literal value and valueFrom secret/configMap references are supported); these are appended after the chart-managed SBS_* / ENABLE_UI variables. See docs/skills.md for usage.
Supported Agent Frameworks
Rossoctl is framework-neutral and supports agents built with any framework that can be exposed via the A2A protocol:
| Framework | Description | Use Case |
|---|---|---|
| LangGraph | Graph-based agent orchestration | Complex workflows with explicit control |
| CrewAI | Role-based multi-agent collaboration | Autonomous goal-driven teams |
| AG2 (AutoGen) | Multi-agent conversation framework | Conversational agents |
| Llama Stack | Meta's agent framework | ReAct-style patterns |
| BeeAI | IBM's agent framework | Enterprise agents |
Example Agents
| Agent | Framework | Description |
|---|---|---|
weather-service | LangGraph | Weather information assistant |
a2a-currency-converter | LangGraph | Currency exchange rates |
a2a-contact-extractor | Marvin | Extract contact info from text |
slack-researcher | AutoGen | Slack research assistant |
Communication Protocols
A2A (Agent-to-Agent)
A2A is Google's standard protocol for agent communication.
Features:
- Agent discovery via Agent Cards
- Standardized task execution API
- Streaming support for long-running tasks
Endpoints:
GET /.well-known/agent-card.json # Agent Card (discovery)
POST / # Send message/task
GET /tasks/{id} # Get task status
MCP (Model Context Protocol)
MCP is Anthropic's protocol for tool integration.
Features:
- Tool discovery and invocation
- Resource access
- Prompt templates
Endpoints:
POST /mcp # MCP JSON-RPC messages