oooi

OpenShift on OpenShift Infra

oooi provides DHCP, split-horizon DNS, and a TLS-passthrough L4 proxy for KubeVirt worker nodes on an isolated VLAN. It gives hosted workers a controlled path to their control plane without exposing the management cluster.

Get started Architecture

---

Use case

When you run OpenShift Hosted Control Planes (HCP) on OpenShift Virtualization with worker VMs attached to an isolated VLAN (attachDefaultNetwork: false), those workers have no route to the hosted control plane Services, which live on the management cluster's pod network. Routes on the hosting cluster's ingress and shared load balancers can expose management-cluster networking to tenant traffic. oooi instead places the required services on the isolated VLAN. The only cross-network traffic is the SNI passthrough traffic needed for the configured control-plane Services.

Capabilities

• Declarative infrastructure

  ---

  One Infra custom resource describes the shared VLAN stack. Create an InfraClusterAttachment for each hosted cluster that uses it. The operator reconciles DHCPServer, DNSServer, and ProxyServer resources and keeps them converged. Namespaced children are garbage-collected on delete; attachment finalizers and cleanup checks handle hosted, cross-namespace, and cluster-scoped resources.

• Static IPAM with KubeVirt awareness

  ---

  Each component gets a fixed IP on the secondary network via Multus. The DHCP server discovers KubeVirt VM interfaces so existing leases stay stable across reconciliation.

• Split-horizon DNS

  ---

  Dual-view CoreDNS: VMs on the VLAN resolve api.*, oauth.*, and *.apps.* names to VLAN addresses. When internalProxyService is configured, management-cluster pods resolve the same names to an internal ClusterIP; otherwise static HCP answers are omitted from the default view. KubeVirt worker aliases are published to the shared proxy only when source addresses are known. Everything else is forwarded upstream.

• TLS passthrough SNI proxy

  ---

  Envoy routes by Server Name Indication without terminating TLS. Certificates never leave the hosted cluster; the proxy sees only encrypted bytes. On a shared VLAN, kubernetes.* aliases are matched to worker source IPs.

• Wildcard apps ingress automation

  ---

  Installs MetalLB into the hosted cluster, creates the *.apps.* LoadBalancer VIP for the default IngressController, wires wildcard SNI backends, and publishes VLAN DNS. The pod-network DNS answer is added only when internalProxyService is configured.

• ExternalDNS integration

  ---

  Declarative labels and annotations on LoadBalancer Services let ExternalDNS publish API, OAuth, and *.apps records to Route53, Azure DNS, or any provider — records follow VIP changes automatically.

How it fits together

flowchart LR
    subgraph VLAN["Isolated VLAN 192.0.2.0/24"]
        W["Worker VMs<br/>(KubeVirt)"]
        D["DHCP · 192.0.2.2"]
        N["CoreDNS · 192.0.2.3"]
        P["Envoy · 192.0.2.4"]
        V["MetalLB VIP · 192.0.2.200"]
    end
    subgraph MGMT["Management cluster"]
        HCP["Hosted control plane<br/>apiserver · oauth · ignition<br/>konnectivity · ingress router"]
    end
    W -->|DHCP| D
    W -->|DNS queries| N
    W -->|"api:6443 / oauth:443 (SNI)"| P
    W -->|"*.apps:80/443"| V
    P -->|L4 passthrough| HCP
    V --> P
    N -.->|static answers| W

For multiple hosted clusters, DNS gives every worker the same proxy address for the aliases kubernetes, kubernetes.default, kubernetes.default.svc, and kubernetes.default.svc.cluster.local. Envoy chooses the control plane from the worker's source /32. The controller obtains those addresses from CAPI Machine.status.addresses, filtered to the shared Infra CIDR. The hostname-SNI alias path uses port 443; the IP-based Kubernetes Service path uses port 6443 without SNI. Both are omitted while the address data is unavailable.

Documentation map

I want to…	Go to
Understand what must exist before installing	Prerequisites
Deploy a hosted cluster end to end	Quickstart
Understand the moving parts	Architecture
Install / upgrade / remove the operator	Installation
Look up an Infra spec field	Infra CR reference
Configure DNS views or upstream resolvers	Split-horizon DNS
Expose consoles and routes (*.apps)	Apps ingress and MetalLB
Publish API, OAuth, and *.apps in public DNS	Public DNS and OAuth publishing
Route several hosted clusters on one VLAN	Multiple hosted clusters
Copy a working manifest	Examples
Verify or debug a running deployment	Operations