Architecture

High-Level Architecture

The platform is composed of four primary layers that work together to deliver end-to-end integration workflow lifecycle management on OpenShift.

Component Technologies & Versions

The OpenShift Integration Operator platform leverages modern, cloud-native technologies. Below is a summary of the core technologies and their key framework versions.

CRD Model

The IntegrationFlow custom resource (platform.io/v1alpha1, short name iflow) is namespaced and drives the full lifecycle.

Spec Fields

See platform comparison and migration guide.

Status Fields

Reconciliation Loop

When an IntegrationFlow is created or updated, the reconciler branches on spec.deploymentMode:

GitOps Mode (default)

When deploymentMode is GITOPS (or unset), the reconciler executes the following steps in order:

1. Scaffold — The ScaffoldingService generates a worker project from the selected engine (CAMEL or SONATAFLOW) and the Kaoto design payload. Status phase: Scaffolding.
2. Git Push — The GitOpsService commits and pushes scaffolded source to the configured Git repository and branch. On failure, phase is set to Error.
3. Tekton — A PipelineRun is created referencing the cluster Pipeline integration-flow-build, passing git URL, branch, commit SHA, and flow name as parameters. Status phase: Building.
4. ArgoCD — The ArgoCD Application name (iflow-<flowName>) is recorded in status for tracking. ArgoCD syncs the built image to the target cluster(s). Status phase: Deploying → Running.
5. Deploy — Worker pods start executing the integration flow. HPA monitors load and scales replicas within configured bounds.

Ephemeral Mode (Quick Try)

When deploymentMode is EPHEMERAL, Git push, Tekton, and ArgoCD are skipped. The reconciler scaffolds in memory and deploys runtime resources directly via EphemeralRuntimeService:

1. Scaffold — Generate worker artifacts from kaotoDesign (no Git commit).
2. Deploy — Type-specific deployer creates ConfigMap + Deployment (Camel Route), Kamelet/Pipe CRs (Camel K), Job (Camel Test), or SonataFlow CR in kogito-bpm.
3. TTL — Set status.ephemeralExpiresAt; on expiry, phase becomes Expired and deployments scale to zero.
4. Cleanup — Finalizer platform.io/ephemeral-cleanup removes labeled resources on delete.
5. Promote — POST /api/flows/{name}/promote-to-gitops switches to GitOps and triggers the standard pipeline.

Telemetry Pipeline

Runtime observability flows from OpenTelemetry collectors through the operator API to the console plugin, enabling real-time visual feedback on the Kaoto canvas.

1. OpenTelemetry — Worker pods emit traces and metrics to the OTel collector (otel-collector:4317 by default).
2. Operator API — The operator exposes /api/telemetry/stream/{flowId} as a Server-Sent Events (SSE) stream and /api/telemetry/snapshot/{flowId} for point-in-time node status.
3. Console Canvas — The TelemetryOverlay component subscribes to the SSE stream and colors Kaoto nodes based on per-node health (healthy, degraded, error) and latency.

MCP Bridge

The Model Context Protocol (MCP) bridge enables AI-powered workflow steps by connecting integration flows to external MCP tool servers.

Tool Discovery

GET /api/mcp/tools?serverUrl=<mcp-server> sends a JSON-RPC 2.0 tools/list request to the MCP server and returns available tool definitions with name, description, and input schema.

Tool Invocation

POST /api/mcp/tools/{toolName}/call?serverUrl=<mcp-server> sends a JSON-RPC 2.0 tools/call request with the tool name and arguments. The response content can be consumed by Camel processors or SonataFlow function states in the worker runtime.

POST /api/mcp/tools/web_search/call?serverUrl=https://mcp.example.com
Content-Type: application/json

{ "query": "OpenShift integration patterns" }

Security and SSRF mitigation

The serverUrl query parameter accepts any URL when the allowlist is empty — the operator will proxy JSON-RPC requests to that host from inside the cluster. This creates a potential server-side request forgery (SSRF) vector if untrusted users can obtain a valid Kubernetes token.

• Production: Always configure an allowlist via Helm — only prefix-matched URLs are accepted.
• Auth: Every call requires Authorization: Bearer <k8s-token> validated via TokenReview.
• Empty allowlist: Permits all URLs (development only).

helm upgrade --install openshift-integration-operator \
  helm/openshift-integration-operator \
  --namespace openshift-integration \
  --set mcp.allowedServerUrls[0]=https://mcp.example.com \
  --set mcp.allowedServerUrls[1]=http://mcp-tools.internal.svc

See also Troubleshooting — MCP allowlist and AI Models & MCP.

Worker Autoscaling

Each IntegrationFlow with a worker Deployment gets its own HorizontalPodAutoscaler (HPA v2). The reconciler creates one HPA per flow with scaleTargetRef pointing at that flow's Deployment — not a shared global autoscaler.

• GitOps flows: base/hpa.yaml is scaffolded to Git and synced by Argo CD on each target cluster.
• Ephemeral flows: The reconciler creates iflow-<name>-hpa targeting iflow-<name>-worker.
• Min replicas: 1 (Helm workers.minReplicas)
• Max replicas: 10 (Helm workers.maxReplicas)
• CPU target: 70% utilization (workers.targetCPUUtilization)
• Memory target: 80% utilization (workers.targetMemoryUtilization)

With ten flows in Running phase, each flow scales independently based on its own worker pod utilization. Disable autoscaling globally with workers.enabled=false.

helm upgrade --install openshift-integration-operator \
  helm/openshift-integration-operator \
  --namespace openshift-integration \
  --set workers.maxReplicas=20