Skip to content

components.md

Latest commit

 

History

History
697 lines (550 loc) · 32.1 KB

components.md

File metadata and controls

697 lines (550 loc) · 32.1 KB
Raw
description Components of the Rossoctl platform.

Kubernetes deployment pattern

This document provides detailed information about each component of the Rossoctl platform when deployed on Kubernetes.

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.

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:

  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 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:
  prefix: 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

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}'

RossoCortex

Repository: rossoctl/cortex

RossoCortex is Rossoctl's data plane. It is a common interface that sits transparently between an agent and everything it interacts with — models, tools, users, and other agents — and enforces guarantees an agent cannot provide on its own. Its capabilities are delivered as plugins.

RossoCortex is framework-neutral: it works with any agent type, including black-box harnesses, and integrates through multiple paths (an SDK, agent hooks, a gateway, or an orchestration layer). It can be implemented in different ways, and is converging on CPEX as the plugin pipeline that hosts and chains those plugins under the covers.

RossoCortex overview: a common interface that agents reach through an SDK, hooks, a gateway, or orchestration; capabilities such as the AuthBridge identity and access-control grouping, IBAC, SPARC, and Context-guru run as plugins, hosted by the emerging CPEX pipeline

AuthBridge (Identity & Access Control)

AuthBridge is RossoCortex's Identity and Access Control capability grouping. It gives agents and tools a trusted identity and enforces authentication, secure delegation, and access control at every hop, replacing static credentials with dynamic, short-lived, audience-scoped tokens. It can be enabled or disabled.

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

Plugin pipeline

RossoCortex's plugins run in a pipeline. It is converging on CPEX — policy orchestration that composes PDP verdicts (Cedar, OPA) for agentic entities through a declarative policy language — as that pipeline. The capabilities above stay constant regardless of which pipeline hosts the plugins.

Related capabilities

Beyond the AuthBridge identity and access-control grouping, other RossoCortex capabilities are delivered as sibling plugins, each documented on its own page:

  • IBAC — Intent-Based Access Control; denies outbound actions that do not match the user's most-recent declared intent.
  • SPARC — pre-tool reflection; catches hallucinated or ungrounded tool calls before they execute.
  • Context-guru — context compaction; shrinks an agent's tool-output context before it reaches the model.
  • Praxis — emerging.

Foundation

AuthBridge builds on two foundational services shared across RossoCortex:

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

  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 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

Related Documentation