Deploy a Kubernetes Gateway API namespace topology

CloudBees Beta

This feature is available as a beta release and is subject to change without notice. CloudBees recommends stringent testing in a development environment and a complete review of the documentation and architecture before using it in production.

Modern Cloud Platforms

This content applies only to CloudBees CI on modern cloud platforms.

The Kubernetes Gateway API is a family of API kinds that provide dynamic infrastructure provisioning and advanced traffic routing. It introduces explicit roles and cross-namespace routing capabilities that affect how you organize your operations center, managed controllers, and agents.

In the Gateway API model, you own and manage Gateway and GatewayClass resources. CloudBees CI creates HTTPRoute resources automatically, co-located with the Services they route to. Infrastructure teams manage ingress gateways; application teams deploy CloudBees CI components on Kubernetes.

Table 1. Responsibility model
Customer responsibility	CloudBees CI responsibility
`Gateway` and `GatewayClass` resources	`HTTPRoute` resources (created automatically)
TLS certificates and termination	Route configuration for operations center and managed controllers
`allowedRoutes` configuration for cross-namespace routing	Co-location of `HTTPRoute`s with their target `Service`s
`sectionName` configuration when using multiple `Gateway` listeners	Automatic `sectionName` propagation to generated `HTTPRoute`s
DNS configuration	`Service` endpoints

CloudBees CI may deploy optional services in the same namespace as the operations center. These services include the SSO Relay, the hibernation monitor, and the CasC Controller Bundle Service. These services share the operations center namespace in all topologies and do not affect the topology patterns described here.
Gateway API routes only HTTP/HTTPS traffic through HTTPRoute resources. If your deployment uses remoting over TCP for inbound agents instead of WebSocket transport, agents connect via a Kubernetes NodePort service that bypasses the Gateway entirely. CloudBees recommends WebSocket transport for Gateway API deployments. For setup instructions, refer to Use WebSockets to connect controllers to the operations center. For NodePort configuration, refer to Connect inbound agents using NodePort.

Choose a topology

CloudBees CI supports three namespace topology patterns with Gateway API. In all topologies, the Gateway is in its own namespace, separate from application workloads. Compare the topologies below based on their advantages and trade-offs.

Table 2. Topology comparison
Topology	Pros	Cons	Testing status
Topology A: Separate agent namespace	Recommended for production deployments. Follows CloudBees' recommendation for agent namespace separation. Agents isolated from control plane (security boundary). `Gateway` isolated from application workloads (infrastructure boundary). Simplified Role-Based Access Control (RBAC) to grant teams access to agent namespace only. Infrastructure team manages `Gateway`; application team manages `HTTPRoutes`.	Three namespaces to manage (gateway, CloudBees CI, agents)	Supported and actively tested. Verified with each CloudBees CI release.
Topology B: Per-team namespaces	Full team isolation (two isolated namespaces per team). Teams control controller and agent resources independently. Different resource limits and network policies per team. Agent compromise isolated to single team. Meets compliance requirements for tenant isolation.	High namespace count: 2N+2 namespaces (two per team, one for the operations center, and one for the gateway). Complex RBAC: per-team roles across two namespaces each. Resource overhead from multiple namespaces. Cross-namespace routing complexity.	Supported, but not actively tested.¹ Customer validation recommended.
Topology C: Multi-cluster	Cluster-level isolation (blast radius limited to single cluster). Supports different `Gateway` implementations per cluster (for example, cloud provider-specific). Supports geo-distributed deployments (controllers closer to teams). Same architecture as existing CloudBees CI multi-cluster setups. Independent cluster management.	Multiple `Gateways` to manage (one per cluster). DNS complexity (different ingress points per cluster). Cross-cluster RBAC configuration required (same as existing multi-cluster setup). `Gateway` management overhead per cluster.	Supported, but not actively tested.¹ Customers should validate Gateway-specific aspects.
¹ Not in CloudBees' automated test suite, but supported for customer use with proper validation.

For topologies not actively tested by CloudBees, CloudBees recommends that you:

Test thoroughly in a non-production environment.
Validate all Gateway API resources (for example, Gateway and HTTPRoute) function correctly.
Document your specific configuration for operational support.
Contact CloudBees Support if you encounter Gateway API-specific issues.

Understand Gateway API concepts

The Gateway API replaces the Ingress resource with a role-oriented model for traffic management.

`Gateway` and `GatewayClass`

A Gateway describes how traffic can be translated to Services within the cluster. It defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does.

A GatewayClass defines which controller implements the Gateway. Implementations include Istio (the CloudBees CI reference implementation), Envoy Gateway, NGINX Gateway Fabric, and various others.

CloudBees CI installation does not create these resources. They must be created and fully functional before installation.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cbci-gateway
  namespace: gateway-resources(1)
spec:
  gatewayClassName: istio(2)
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: ci-example-com-tls
    allowedRoutes:
      namespaces:
        from: Selector(3)
        selector:
          matchLabels:
            cloudbees.com/gateway-routes: enabled▼

1	`Gateway` lives in a dedicated gateway namespace.
2	References the `GatewayClass` that defines which controller manages this `Gateway`.
3	Only `HTTPRoutes` from namespaces matching selector can attach to this listener. Apply the `cloudbees.com/gateway-routes: enabled` label only to namespaces containing operations center or managed controller `Service`s that need `HTTPRoutes`, not to agent namespaces.

TLS termination is configured on Gateway listeners and is the customer’s responsibility. All examples in this document use HTTPS listeners referencing a TLS Secret named ci-example-com-tls via tls.certificateRefs. You must create this Secret in the Gateway namespace (for example, using cert-manager or kubectl create secret tls).

The examples in this document use path-based routing (a single hostname with a path prefix per controller). Subdomain-based routing (for example, controller1.ci.example.com) may require a different Gateway listener configuration, including wildcard hostnames and wildcard TLS certificates.

When using Selector, consider setting a hostname on the listener for additional security. Hostnames restrict which HTTPRoutes can bind based on subdomain matching, providing a second layer of control beyond namespace selection.

`HTTPRoute`

An HTTPRoute defines HTTP routing rules: path-based routing, hostname matching, and backend Service references.

CloudBees CI creates HTTPRoute resources automatically for the operations center and each managed controller. This automatic creation only applies when using Gateway API-based routing, not when using Ingress or OpenShift Routes.

HTTPRoutes are co-located with their backend Services. This co-location eliminates the need for ReferenceGrants.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cjoc-route
  namespace: cloudbees-ci(1)
spec:
  parentRefs:(2)
  - name: cbci-gateway
    namespace: gateway-resources
  hostnames:
  - "ci.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /cjoc
    backendRefs: (3)
    - name: cjoc
      port: 80▼

1	`HTTPRoute` lives in the same namespace as the `Service` it routes to.
2	References the `Gateway` that should handle this route.
3	Backend `Service` reference (in the same namespace, no `ReferenceGrant` needed).

`sectionName` for targeting specific listeners

A sectionName in parentRefs targets a specific listener on the Gateway by name. When omitted, the HTTPRoute attaches to all compatible listeners on the referenced Gateway.

You may need to use a sectionName when the Gateway has multiple listeners (for example, separate http and https listeners).

parentRefs:
- name: cbci-gateway
  namespace: gateway-resources
  sectionName: https(1)▼

1	Targets only the listener named `https` on the `Gateway`.

The Helm chart supports configuring sectionName through Gateway.SectionName.

Gateway:
  Enabled: true
  Name: "cbci-gateway"
  Namespace: "gateway-resources"
  SectionName: "https"(1)▼

1	Optional `sectionName` used by operations center and all services.

Cross-namespace routing with `allowedRoutes`

Gateway API supports cross-namespace routing, but the Gateway must explicitly authorize it.

`Gateway` `allowedRoutes`

The allowedRoutes.namespaces.from field controls which namespaces can attach HTTPRoutes to a Gateway:

Same (default): Only HTTPRoutes in the Gateway's namespace can attach. Since CloudBees CI HTTPRoutes are co-located with Services in application namespaces (not the Gateway namespace), this setting prevents HTTPRoutes from attaching.
All: HTTPRoutes from any namespace can attach. This setting allows any namespace in the cluster to create routes through your Gateway, including namespaces running untrusted workloads, and should not be used in a production environment.

Selector: HTTPRoutes from namespaces matching a label selector can attach. This is the recommended option for production.

Use Selector for production deployments. All permits any namespace in the cluster to attach routes to the Gateway, which is a security risk. Same is too restrictive for CloudBees CI because HTTPRoutes must be co-located with their Services in application namespaces.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shared-gateway
  namespace: gateway-resources(1)
spec:
  gatewayClassName: istio
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: ci-example-com-tls
    allowedRoutes:
      namespaces:
        from: Selector(2)
        selector:
          matchLabels:
            cloudbees.com/gateway-routes: enabled(3)▼

1	`Gateway` in a gateway specific namespace.
2	Only namespaces with matching labels can attach `HTTPRoutes`.
3	Apply the `cloudbees.com/gateway-routes: enabled` label to namespaces containing the operations center or managed controller `Service`s. Do not label agent namespaces.

The Gateway API specification also defines ReferenceGrant for authorizing cross-namespace references. CloudBees CI does not require ReferenceGrant because allowedRoutes handles HTTPRoute attachment and HTTPRoutes are co-located with their backend Services.

Cross-namespace example

The following example shows a Gateway in a gateway specific namespace with an HTTPRoute in the CloudBees CI namespace, using Selector-based authorization:

# In the gateway-resources namespace (shared gateway)
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shared-gateway
  namespace: gateway-resources
spec:
  gatewayClassName: istio
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: ci-example-com-tls
    allowedRoutes:
      namespaces:
        from: Selector(1)
        selector:
          matchLabels:
            cloudbees.com/gateway-routes: enabled
---
# In cloudbees-ci namespace
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cjoc-route
  namespace: cloudbees-ci(2)
spec:
  parentRefs:
  - name: shared-gateway
    namespace: gateway-resources(3)
  hostnames:
  - "ci.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /cjoc
    backendRefs:
    - name: cjoc
      port: 80(4)▼

1	`Gateway` allows routes only from namespaces with matching labels.
2	`HTTPRoute` co-located with `Service` (namespace must have `cloudbees.com/gateway-routes: enabled` label).
3	Cross-namespace `Gateway` reference (permitted by `allowedRoutes`).
4	Backend `Service` in same namespace as `HTTPRoute` (no `ReferenceGrant` needed).

Topology A: Separate agent namespace

In this topology, the operations center and managed controllers are in one namespace, agents are in a separate namespace, and the Gateway is in its own namespace. CloudBees recommends separating agents from control plane components. A dedicated Gateway namespace keeps customer-managed infrastructure isolated from application workloads.

This is the recommended production topology for customers that do not need complete controller isolation. Agents run in their own namespace for security and resource management. The dedicated Gateway namespace separates customer-managed infrastructure from CloudBees CI components.

Separate agent namespace topology

┌─────────────────────────────────────────────────┐
│  Namespace: gateway-resources                   │
│                                                 │
│  ┌──────────┐                                   │
│  │ Gateway  │                                   │
│  └──────────┘                                   │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│  Namespace: cloudbees-ci                        │
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │   CJOC   │  │ Ctrlr-1  │  │ Ctrlr-2  │       │
│  │ (Service)│  │(Service) │  │(Service) │       │
│  └──────────┘  └──────────┘  └──────────┘       │
│                                                 │
│  HTTPRoutes: cjoc-route, ctrlr-1-route, ...     │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│  Namespace: cloudbees-agents                    │
│                                                 │
│  ┌──────────────────────────────────────┐       │
│  │              Agent Pods              │       │
│  └──────────────────────────────────────┘       │
└─────────────────────────────────────────────────┘

Configuration examples

Gateway configuration (in the gateway-resources namespace):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cbci-gateway
  namespace: gateway-resources(1)
spec:
  gatewayClassName: istio
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: ci-example-com-tls
    allowedRoutes:
      namespaces:
        from: Selector(2)
        selector:
          matchLabels:
            cloudbees.com/gateway-routes: enabled▼

1	`Gateway` in a dedicated gateway namespace.
2	Allow `HTTPRoutes` from labeled namespaces to attach.

HTTPRoutes remain in the cloudbees-ci namespace (co-located with Services):

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cjoc-route
  namespace: cloudbees-ci(1)
spec:
  parentRefs:
  - name: cbci-gateway
    namespace: gateway-resources(2)
  hostnames:
  - "ci.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /cjoc
    backendRefs:
    - name: cjoc
      port: 80▼

1	`HTTPRoute` co-located with `Service`.
2	Cross-namespace `Gateway` reference (permitted by `allowedRoutes`).

Deploy and configure with Helm

Create namespaces:

kubectl create namespace gateway-resources
kubectl create namespace cloudbees-ci
kubectl create namespace cloudbees-agents▼

Label the cloudbees-ci namespace for Gateway allowedRoutes:

kubectl label namespace cloudbees-ci cloudbees.com/gateway-routes=enabled▼

Deploy the Gateway in the gateway-resources namespace (customer responsibility).

Install operations center and managed controllers in the cloudbees-ci namespace with values.yaml:

Gateway:
  Enabled: true(1)
  Name: "cbci-gateway"(2)
  Namespace: "gateway-resources"(3)
  # SectionName: "https"(4)

Agents:
  SeparateNamespace:
    Enabled: true
    Name: "cloudbees-agents"(5)
    Create: true▼

1	Enable Gateway API support.
2	Name of the `Gateway` resource.
3	Namespace where `Gateway` is deployed.
4	Optional: target a specific `Gateway` listener by name (refer to `sectionName` for targeting specific listeners).
5	Agent namespace name.

For complete installation steps, refer to Install CloudBees CI on modern cloud platforms with Kubernetes Gateway API.

Topology B: Per-team namespaces

In this topology, each team has two dedicated namespaces: one for managed controllers and one for agents. operations center and Gateway remain centralized.

This topology is intended for high-security or compliance-driven environments that require full team isolation. It requires a mature Kubernetes operations team comfortable with complex RBAC across many namespaces. Consider this topology when:

Compliance requires strict tenant isolation.
Teams have vastly different resource requirements.
Security policies mandate separate agent namespaces per team.

Per-team agent namespaces topology

┌─────────────────────────────────────────────────┐
│  Namespace: gateway-resources                   │
│                                                 │
│  ┌──────────┐                                   │
│  │ Gateway  │                                   │
│  └──────────┘                                   │
└─────────────────────────────────────────────────┘

┌────────────────────────────┐  ┌───────────────┐  ┌──────────────┐
│  Namespace:                │  │  Namespace:   │  │  Namespace:  │
│  cloudbees-ci              │  │  team-a       │  │  team-a-     │
│                            │  │               │  │  agents      │
│  ┌──────────┐              │  │  ┌─────────┐  │  │              │
│  │   CJOC   │              │  │  │Ctrlr-A  │  │  │  ┌───────┐   │
│  │ (Service)│              │  │  │(Service)│  │  │  │Agents │   │
│  └──────────┘              │  │  └─────────┘  │  │  └───────┘   │
│                            │  │               │  │              │
│  HTTPRoute: cjoc-route     │  │  HTTPRoute:   │  │              │
└────────────────────────────┘  │  ctrlr-a-route│  │              │
                                └───────────────┘  └──────────────┘

                                ┌───────────────┐  ┌──────────────┐
                                │  Namespace:   │  │  Namespace:  │
                                │  team-b       │  │  team-b-     │
                                │               │  │  agents      │
                                │  ┌─────────┐  │  │              │
                                │  │Ctrlr-B  │  │  │  ┌───────┐   │
                                │  │(Service)│  │  │  │Agents │   │
                                │  └─────────┘  │  │  └───────┘   │
                                │               │  │              │
                                │  HTTPRoute:   │  │              │
                                │  ctrlr-b-route│  │              │
                                └───────────────┘  └──────────────┘

Configuration examples

This topology extends the separate agent namespace pattern from Topology A: Separate agent namespace with per-team isolation for both controllers and agents.

Gateway configuration (in the gateway-resources namespace):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cbci-gateway
  namespace: gateway-resources(1)
spec:
  gatewayClassName: istio
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: ci-example-com-tls
    allowedRoutes:
      namespaces:
        from: Selector(2)
        selector:
          matchLabels:
            cloudbees.com/gateway-routes: enabled▼

1	`Gateway` in a gateway specific namespace.
2	Only namespaces with the `cloudbees.com/gateway-routes: enabled` label can attach `HTTPRoutes`.

HTTPRoute for team controller (in team namespace):

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ctrlr-a-route
  namespace: team-a(1)
spec:
  parentRefs:
  - name: cbci-gateway
    namespace: gateway-resources(2)
  hostnames:
  - "ci.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /team-a/controller-1
    backendRefs:
    - name: ctrlr-a
      port: 80▼

1	`HTTPRoute` co-located with controller `Service` in team namespace.
2	Cross-namespace `Gateway` reference.

Each team’s managed controller is configured (via Configuration as Code (CasC) or the UI) to provision agents in the team’s dedicated agent namespace (for example, team-a-agents). Same agent namespace separation as Topology A: Separate agent namespace, applied per team.

Deploy and configure with Helm

Create namespaces for each team (controller + agents):

kubectl create namespace gateway-resources
kubectl create namespace cloudbees-ci
kubectl create namespace team-a
kubectl create namespace team-a-agents
kubectl create namespace team-b
kubectl create namespace team-b-agents▼

Label namespaces that contain operations center or managed controller Services for Gateway allowedRoutes:
```
kubectl label namespace cloudbees-ci cloudbees.com/gateway-routes=enabled
kubectl label namespace team-a cloudbees.com/gateway-routes=enabled
kubectl label namespace team-b cloudbees.com/gateway-routes=enabled▼
```
Do not label agent namespaces (team-a-agents, team-b-agents). Only namespaces containing Services that need HTTPRoutes require the cloudbees.com/gateway-routes: enabled label.
Deploy the Gateway in the gateway-resources namespace (customer responsibility).
Install operations center in the cloudbees-ci namespace with values.yaml:
```
Gateway:
  Enabled: true
  Name: "cbci-gateway"
  Namespace: "gateway-resources"
  # SectionName: "https"(1)▼
```
1 Optional: target a specific Gateway listener by name (refer to sectionName for targeting specific listeners).

For each team’s controller namespace, create values.yaml:

Gateway:
  Enabled: true
  Name: "cbci-gateway"
  Namespace: "gateway-resources"

OperationsCenter:
  Enabled: false(1)

Master:
  Enabled: true
  OperationsCenterNamespace: cloudbees-ci(2)

Agents:
  Enabled: true
  SeparateNamespace:
    Enabled: true
    Name: team-a-agents(3)▼

1	Disable operations center in team controller namespaces.
2	Reference the namespace where the operations center is deployed.
3	Team-specific agent namespace.

Install Helm release in each team’s controller namespace:

helm install team-a-controllers cloudbees/cloudbees-core \
  --namespace team-a \
  -f values-team-a.yaml▼

For complete installation steps, refer to Install CloudBees CI on modern cloud platforms with Kubernetes Gateway API.

Topology C: Multi-cluster

In this topology, CloudBees CI components are distributed across multiple Kubernetes clusters, with a Gateway providing ingress routing in each cluster. This is CloudBees CI’s existing multi-cluster model with Gateway API instead of Ingress.

In this topology, each cluster runs its own Gateway, and CloudBees CI creates HTTPRoutes locally within each cluster.

Requirements:

Each cluster must have its own Gateway (Gateway API does not support cross-cluster Gateways).
DNS must route to the correct cluster’s Gateway ingress point.
Follow existing multi-cluster setup requirements: rbac.installCluster: true in secondary clusters.

For multi-cluster networking considerations, refer to Multiple cluster setups.

Multi-cluster with Gateway API topology

┌─────────── Main Cluster ───────────┐
│  Namespace: gateway-resources      │
│  ┌──────────┐                      │
│  │Gateway-1 │                      │
│  └──────────┘                      │
│                                    │
│  Namespace: cloudbees-ci           │
│  ┌──────────┐                      │
│  │   CJOC   │                      │
│  │ (Service)│                      │
│  └──────────┘                      │
│                                    │
│  ┌──────────┐  ┌──────────┐        │
│  │ Ctrlr-1  │  │ Ctrlr-2  │        │
│  │(Service) │  │(Service) │        │
│  └──────────┘  └──────────┘        │
│                                    │
│  HTTPRoutes: cjoc-route,           │
│  ctrlr-1-route, ctrlr-2-route      │
└────────────────────────────────────┘

┌──── Secondary Cluster (Team A) ────┐
│  Namespace: gateway-resources      │
│  ┌──────────┐                      │
│  │Gateway-2 │                      │
│  └──────────┘                      │
│                                    │
│  Namespace: cloudbees-ci           │
│  ┌──────────┐  ┌──────────┐        │
│  │ Ctrlr-A1 │  │ Ctrlr-A2 │        │
│  │(Service) │  │(Service) │        │
│  └──────────┘  └──────────┘        │
│                                    │
│  HTTPRoutes: ctrlr-a1-route,       │
│  ctrlr-a2-route                    │
└────────────────────────────────────┘

Configuration examples

Each cluster has its own Gateway resource in a dedicated namespace.

Gateway API does not support cross-cluster Gateway sharing. Gateway resources are cluster-scoped from a deployment perspective.

Gateway in main cluster (with operations center):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cbci-gateway-main
  namespace: gateway-resources(1)
spec:
  gatewayClassName: istio
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: ci-example-com-tls
    allowedRoutes:
      namespaces:
        from: Selector(2)
        selector:
          matchLabels:
            cloudbees.com/gateway-routes: enabled▼

1	`Gateway` in dedicated namespace.
2	Only namespaces with the `cloudbees.com/gateway-routes: enabled` label can attach `HTTPRoutes`.

Gateway in secondary cluster (Team A):

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cbci-gateway-team-a
  namespace: gateway-resources(1)
spec:
  gatewayClassName: istio(2)
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      certificateRefs:
      - name: ci-example-com-tls
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            cloudbees.com/gateway-routes: enabled▼

1	`Gateway` in dedicated namespace.
2	Can be a different `GatewayClass` per cluster (for example, cloud provider-specific implementations).

HTTPRoute in main cluster:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cjoc-route
  namespace: cloudbees-ci
spec:
  parentRefs:
  - name: cbci-gateway-main
    namespace: gateway-resources(1)
  hostnames:
  - "ci.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /cjoc
    backendRefs:
    - name: cjoc
      port: 80▼

1	References `Gateway` in the same cluster.

HTTPRoute in secondary cluster:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ctrlr-a1-route
  namespace: cloudbees-ci(1)
spec:
  parentRefs:
  - name: cbci-gateway-team-a
    namespace: gateway-resources(2)
  hostnames:
  - "ci-team-a.example.com"(3)
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /team-a/controller-1
    backendRefs:
    - name: ctrlr-a1
      port: 80▼

1	Same namespace name across clusters (`cloudbees-ci`).
2	References `Gateway` in the same cluster.
3	Different hostname per cluster; DNS must route to correct cluster’s `Gateway`.

Deploy and configure with Helm

Each cluster needs its own Gateway resource.

Refer to Multiple cluster setups for instructions on:

Creating namespaces across clusters
Configuring rbac.installCluster: true in secondary clusters
Setting up operations center cluster endpoints
Creating kubeconfig files for secondary clusters

Gateway API-specific additions:

Deploy Gateway in the main cluster:

kubectl apply -f main-cluster-gateway.yaml --namespace gateway-resources▼

Deploy Gateway in each secondary cluster:

kubectl apply -f secondary-cluster-gateway.yaml --namespace gateway-resources --context <secondary-cluster-context>▼

Configure DNS routing:
- Main cluster DNS (for example, ci.example.com) resolves to main cluster Gateway ingress IP.
- Secondary cluster DNS (for example, ci-team-a.example.com) resolves to secondary cluster Gateway ingress IP.
Configure operations center cluster endpoints with correct hostname patterns per cluster (this is the same as the existing multi-cluster setup).

HTTPRoutes are created automatically by CloudBees CI in each cluster and reference the Gateway in their respective cluster. No cross-cluster HTTPRoute configuration needed.

For complete installation steps, refer to Install CloudBees CI on modern cloud platforms with Kubernetes Gateway API.

Namespace topologies to avoid

The following namespace topologies are discouraged or unsupported:

Agents in the same namespace as controllers: Users with Item/Configure or Job/Run permissions can create pods in the controller namespace. This creates a security risk. CloudBees does not support this configuration unless you explicitly set Agents.SeparateNamespace.Enabled: false. Always use a separate agent namespace.
Gateway in agent namespace: Agents execute untrusted code and should not share a namespace with infrastructure components like Gateway. This creates a security risk.
HTTPRoutes not co-located with Services: Separating HTTPRoutes from their backend Services adds operational complexity with no benefit. CloudBees CI co-locates them by default.
Separate Gateway per controller: Each Gateway typically provisions a LoadBalancer. Using one Gateway per controller wastes resources and defeats Gateway API’s shared ingress model.
All components in a single namespace: Deploying Gateway, operations center, managed controllers, and agents in one namespace removes all security boundaries between infrastructure and application workloads.

For all deployments, use one of the supported topologies described above.

Gateway API namespace topology summary

You manage Gateway resources; CloudBees CI creates HTTPRoutes that are co-located with Services.
Topology A: Separate agent namespace is the recommended production topology.
Cross-namespace routing requires Gateway allowedRoutes authorization.
CloudBees actively tests Topology A: Separate agent namespace; other topologies are supported but require customer validation.

For more on multi-namespace and multi-cluster deployment patterns, refer to Deploy CloudBees CI across multiple Kubernetes namespaces and clusters.

Deploy a Kubernetes Gateway API namespace topology

Choose a topology

Understand Gateway API concepts

Gateway and GatewayClass

HTTPRoute

sectionName for targeting specific listeners

Cross-namespace routing with allowedRoutes

Gateway allowedRoutes

Cross-namespace example

Topology A: Separate agent namespace

Configuration examples

Deploy and configure with Helm

Topology B: Per-team namespaces

Configuration examples

Deploy and configure with Helm

Topology C: Multi-cluster

Configuration examples

Deploy and configure with Helm

Namespace topologies to avoid

Gateway API namespace topology summary

`Gateway` and `GatewayClass`

`HTTPRoute`

`sectionName` for targeting specific listeners

Cross-namespace routing with `allowedRoutes`

`Gateway` `allowedRoutes`