Skip to main content

Rossoctl Components

This document provides detailed information about each component of the Rossoctl platform.

Table of Contents


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

FeatureDescription
Agent DeploymentDeploy agents from source code or container images as Kubernetes Deployments
Build AutomationBuild agent containers using Shipwright with Buildah
Lifecycle ManagementStandard Kubernetes Deployment lifecycle (rolling updates, rollbacks, scaling)
Configuration ManagementEnvironment variables, secrets, and config maps via Deployment spec
Multi-Namespace SupportDeploy agents to isolated team namespaces

Container Build System

Rossoctl uses Shipwright for building container images from source:

StrategyUse CaseDescription
buildah-insecure-pushInternal registriesFor registries without TLS (dev/Kind clusters)
buildahExternal registriesFor registries with TLS (quay.io, ghcr.io, docker.io)

Shipwright Build Flow:

  1. UI creates a Shipwright Build CR with source configuration
  2. UI creates a BuildRun CR to trigger the build
  3. UI polls BuildRun status until completion
  4. 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:

LabelValuePurpose
rossoctl.io/typeagentIdentifies resource as a Rossoctl agent (operator-managed via AgentRuntime CR)
protocol.rossoctl.io/<name>""Protocol support (e.g. protocol.rossoctl.io/a2a)
rossoctl.io/frameworkLangGraph, CrewAI, etc.Agent framework
app.kubernetes.io/name<agent-name>Standard K8s app name
app.kubernetes.io/managed-byrossoctl-uiResource 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

FeatureDescription
Tool DiscoveryAutomatic discovery and registration of MCP servers
RoutingRoute agent requests to appropriate MCP tools
AuthenticationOAuth/token-based authentication for tool access
Load BalancingDistribute requests across tool replicas

Components

ComponentNamespacePurpose
mcp-gateway-istiogateway-systemEnvoy proxy for request routing
mcp-controllermcp-systemManages MCPServerRegistration custom resources
mcp-broker-routermcp-systemRoutes 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:

  1. UI creates a Shipwright Build CR with source configuration
  2. UI creates a BuildRun CR to trigger the build
  3. UI polls BuildRun status until completion
  4. 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

FeatureDescription
Dynamic Plugin LoadingLoad and update plugins without traffic disruption
Request/Response ControlInspect, modify, or block based on headers and body
Bring-Your-Own (BYO) LogicImplement plugins in any language
Guardrails EnforcementImplement 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

ComponentTechnologyDescription
FrontendReact + PatternFlySingle-page application served by nginx
BackendFastAPI + PythonREST API for Kubernetes interactions

Features

FeatureDescription
Agent ImportImport A2A agents from any framework via Git URL or container image
Tool DeploymentDeploy MCP tools directly from source or container image
Interactive TestingChat interface to test agent capabilities
MonitoringView traces, logs, and network traffic via Phoenix (optional) and Kiali
AuthenticationKeycloak-based login/logout with OAuth2
MCP GatewayBrowse and test MCP tools via MCP Inspector

Pages

PagePurpose
HomeOverview and quick actions
AgentsList, import, and manage agents
ToolsList, import, and manage MCP tools
MCP GatewayView MCP Gateway status and launch MCP Inspector
ObservabilityAccess Phoenix traces (when enabled) and Kiali network dashboards
AdminKeycloak 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

ComponentPurposeRepository
AuthProxyInbound JWT validation (JWKS) and outbound token exchangeAuthBridge/AuthProxy
SPIREWorkload identity and attestationExternal
KeycloakIdentity provider and access managementExternal

Keycloak Client Registration (Operator-Managed)

Keycloak client registration is handled by the rossoctl-operator's ClientRegistrationReconciler controller:

  • Reconciles AgentRuntime CRs to apply rossoctl.io/type labels 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) and EXPECTED_AUDIENCE (optional) environment variables. Outbound exchange uses TOKEN_URL, CLIENT_ID, CLIENT_SECRET (provided by the operator via secret), and TARGET_AUDIENCE.

SPIRE (Workload Identity)

SPIRE provides cryptographic workload identities using the SPIFFE standard.

ComponentPurpose
SPIRE ServerIssues SVIDs (SPIFFE Verifiable Identity Documents)
SPIRE AgentNode-level agent that attests workloads
CSI DriverMounts 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.

FeatureDescription
User ManagementCreate and manage Rossoctl users
Client RegistrationOAuth clients for agents and UI (automated registration via rossoctl-operator's ClientRegistrationReconciler)
Token ExchangeExchange tokens between audiences (RFC 8693)
SSOSingle 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) │
└─────────────────────────────────────────┘
  1. User authenticates with Keycloak, receives access token
  2. Agent receives user context via delegated token
  3. Agent identity is attested by SPIRE
  4. 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.

ComponentPurpose
ZtunnelNode-local proxy for mTLS and traffic interception
WaypointOptional 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:

FrameworkDescriptionUse Case
LangGraphGraph-based agent orchestrationComplex workflows with explicit control
CrewAIRole-based multi-agent collaborationAutonomous goal-driven teams
AG2 (AutoGen)Multi-agent conversation frameworkConversational agents
Llama StackMeta's agent frameworkReAct-style patterns
BeeAIIBM's agent frameworkEnterprise agents

Example Agents

AgentFrameworkDescription
weather-serviceLangGraphWeather information assistant
a2a-currency-converterLangGraphCurrency exchange rates
a2a-contact-extractorMarvinExtract contact info from text
slack-researcherAutoGenSlack 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