Rossoctl Components

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

Overview
Architecture Diagram
MCP Gateway
Plugins adapter
Rossoctl UI
Cortex
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.

Architecture Diagram

All the Rossoctl components and their deployment namespaces

Rossoctl architecture: components and their deployment namespaces within a Kubernetes cluster

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 Build CR with source configuration
UI creates a BuildRun CR to trigger the build
UI polls BuildRun status 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 enrolls the
# workload with Cortex 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

UI Architecture

Rossoctl UI architecture: Import Agent, Build (Source), and Deploy Agent actions acting through the Kubernetes API Server

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 Build CR with source configuration
UI creates a BuildRun CR to trigger the build
UI polls BuildRun status 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}'

Cortex

Repository: rossoctl/cortex

Cortex is the security layer of Rossoctl for agentic systems. It gives every agent and tool a trusted identity and enforces authentication, secure delegation, access control, and safe behavior at each hop, replacing static credentials with dynamic, short-lived, audience-scoped tokens.

This solves a critical challenge in microservices and agentic architectures: how can workloads authenticate and communicate securely without pre-provisioned static credentials, while ensuring each action stays within what the user actually intended?

What Cortex provides

Capability	Description
Trusted Identity	Cryptographic workload identities issued by SPIFFE/SPIRE, backed by attestation
Authentication	Validation of inbound tokens — signature, issuer, and audience
Secure Delegation	OAuth 2.0 Token Exchange (RFC 8693) with per-target audience scoping
Client Registration	Automated Keycloak client provisioning for each workload, keyed by its SPIFFE identity
Access Control	Policy-driven allow/deny decisions on agent and tool actions
Guardrails	Content and behavior safety enforcement around agent activity

Technologies Cortex supports

Cortex delivers these capabilities through a set of security technologies, and that set grows over time. The concepts above stay constant regardless of which technology enforces them.

Technology	Role	Status
CPEX	Policy orchestration and access control — composes PDP verdicts (Cedar, OPA) for agentic entities using a declarative policy language	Supported
IBAC	Intent-Based Access Control — denies outbound actions that do not match the user's most-recent declared intent	Supported
SPARC	Pre-tool reflection — catches hallucinated or ungrounded tool calls before they execute	Supported
Praxis	—	Emerging

Foundation

Cortex builds on two foundational services:

Service	Role
SPIRE	Issues cryptographic workload identities (SVIDs) via node-level attestation. Identity format: `spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>`
Keycloak	Identity provider for user authentication, OAuth/OIDC flows, token exchange, and SSO across Rossoctl components

Client registration with Keycloak is automated per workload, keyed by the workload's SPIFFE identity, so agent namespaces never need admin credentials. SPIRE identities can be inspected through the Tornjak UI (http://spire-tornjak-ui.localtest.me:8080/).

Authorization Pattern

The Agent and Tool Authorization Pattern replaces static credentials with dynamic SPIRE-managed identities, enforcing least privilege and continuous authentication:

Authorization pattern: User to Keycloak to Agent to Tool, each backed by short-lived identities from the SPIRE Server

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 happens outside application code; no changes required

For a detailed overview of Identity and Authorization Patterns, see the Identity Guide.

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.

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

Table of Contents​

Overview​

Value Proposition​

Architecture Diagram​

Agent Deployment Architecture​

Capabilities​

Container Build System​

Agent Resources​

UI Architecture​

Label Standards​

MCP Gateway​

Capabilities​

Components​

Registering Tools with the Gateway​

MCP Tool Builds with Shipwright​

Plugins Adapter​

Capabilities​

Rossoctl UI​

Architecture​

Features​

Pages​

Access​

Cortex​

What Cortex provides​

Technologies Cortex supports​

Foundation​

Authorization Pattern​

Infrastructure Services​

Ingress Gateway​

Istio Ambient Mesh​

Kiali (Service Mesh Observability)​

Phoenix (Tracing) -- Optional​

Supported Agent Frameworks​

Example Agents​

Communication Protocols​

A2A (Agent-to-Agent)​

MCP (Model Context Protocol)​

Related Documentation​

Table of Contents

Overview

Value Proposition

Architecture Diagram

Agent Deployment Architecture

Capabilities

Container Build System

Agent Resources

UI Architecture

Label Standards

MCP Gateway

Capabilities

Components

Registering Tools with the Gateway

MCP Tool Builds with Shipwright

Plugins Adapter

Capabilities

Rossoctl UI

Architecture

Features

Pages

Access

Cortex

What Cortex provides

Technologies Cortex supports

Foundation

Authorization Pattern

Infrastructure Services

Ingress Gateway

Istio Ambient Mesh

Kiali (Service Mesh Observability)

Phoenix (Tracing) -- Optional

Supported Agent Frameworks

Example Agents

Communication Protocols

A2A (Agent-to-Agent)

MCP (Model Context Protocol)

Related Documentation