Install CloudBees CI on modern cloud platforms with Kubernetes Gateway API

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.

Follow these steps to install CloudBees CI with Gateway API for traffic routing. When Gateway API is enabled, CloudBees CI automatically creates HTTPRoute resources for the operations center and all managed controllers.

Prerequisites

Complete the following before starting the installation:

Platform: Complete the pre-installation requirements for your cloud platform:
Gateway API: Verify Kubernetes Gateway API prerequisites, including your Gateway API controller, CustomResourceDefinitions (CRDs), GatewayClass, Gateway resource, TLS certificates, DNS resolution, namespace labels, and Role-Based Access Control (RBAC).
Namespace topology: Choose a topology for your deployment. This guide uses the separate agent namespace topology, which is recommended for production environments.

Prepare namespaces

Create and label the namespaces for your deployment.

Agent namespaces do not need HTTPRoute resources.
- If you use Agents.SeparateNamespace.Create=true, the Helm chart creates and labels the agents namespace automatically.
- If you create agent namespaces manually, do not label them with cloudbees.com/gateway-routes=enabled. Adding this label unnecessarily broadens the Gateway’s routing scope.
For per-team namespace topologies, label every namespace that contains operations center or managed controller services. Refer to per-team namespaces deployment for details.

Create the namespaces:
```
kubectl create namespace <cbci-namespace>
kubectl create namespace <agents-namespace>▼
```
The Gateway namespace (for example, gateway-infra) should already exist from the Gateway API prerequisites setup.
Label the CloudBees CI namespace for Gateway routing:
```
kubectl label namespace <cbci-namespace> cloudbees.com/gateway-routes=enabled▼
```
The CloudBees CI Helm chart cannot manage labels on the release namespace because the namespace must exist before helm install runs. Apply this label with kubectl before installing.

Add the CloudBees Helm chart repository

Add the CloudBees Helm chart repository as follows:

helm repo add cloudbees https://public-charts.artifacts.cloudbees.com/repository/public/
helm repo update▼

Install CloudBees CI with HTTPS

CloudBees recommends HTTPS for production environments. Install CloudBees CI using one of the following methods:

Option 1: Install using command-line flags
Option 2: Install using a values.yaml file

No OperationsCenter.Ingress block is needed. Gateway API replaces all Ingress configuration.
The Helm chart validates that Gateway API CRDs are installed in the cluster. If helm install fails with a validation error, verify that you completed the prerequisites.
Additional Helm values for specific scenarios:
- For CloudBees High Availability (HA) controllers, add replication configuration per Get ready for HA (active/active).
- For multi-namespace or multi-cluster setups, refer to Deploy CloudBees CI across multiple Kubernetes namespaces and clusters.
- NetworkPolicy: the chart automatically allows ingress from the Gateway namespace. If you manage NetworkPolicy manually or use NetworkPolicy.ingressControllerSelector, ensure Gateway traffic is permitted.

Protocol: https tells CloudBees CI to generate HTTPS URLs for browser redirects and API callbacks. TLS termination happens at the Gateway; the CloudBees CI pods serve HTTP internally.

Option 1: Install using command-line flags

To install using command-line flags, run the following command, and replace the placeholders with your values:

helm install <release> cloudbees/cloudbees-core \(1)
  --namespace <cbci-namespace> \(2)
  --set OperationsCenter.HostName='<hostname>' \(3)
  --set OperationsCenter.Protocol=https \(4)
  --set Gateway.Enabled=true \(5)
  --set Gateway.Name='<gateway-name>' \(6)
  --set Gateway.Namespace='<gateway-namespace>' \(7)
  --set Agents.SeparateNamespace.Enabled=true \
  --set Agents.SeparateNamespace.Create=true▼

1	`<release>` is the Helm release name.
2	`<cbci-namespace>` is the namespace you created for CloudBees CI.
3	`<hostname>` is the fully qualified domain name for the operations center (for example, `ci.example.com`).
4	`Protocol=https` tells CloudBees CI to generate HTTPS external URLs. Set to `http` for development environments without TLS.
5	`Gateway.Enabled=true` enables Gateway API support. The chart creates `HTTPRoute` resources instead of `Ingress`.
6	`<gateway-name>` is the name of the `Gateway` resource to reference in `HTTPRoute` resources.
7	`<gateway-namespace>` is the namespace where the `Gateway` resource is deployed.

Option 2: Install using a values.yaml file

Create a values.yaml file with the following content:

OperationsCenter:
  HostName: ci.example.com
  Protocol: https

Gateway:
  Enabled: true
  Name: "cloudbees-gateway"
  Namespace: "gateway-infra"
  # SectionName: "https"(1)

Agents:
  SeparateNamespace:
    Enabled: true
    Create: true▼

1	Optional. Specify when the `Gateway` has multiple listeners, and you need to target a specific one by name. Refer to gateway-api-namespace-topologies.adoc#sectionName.

Run the following command to install:

helm install <release> cloudbees/cloudbees-core \
  --namespace <cbci-namespace> \
  -f values.yaml▼

Verify your CloudBees CI installation

The helm status command displays the status of the CloudBees CI release. This command is also executed after helm install and helm upgrade commands are executed.

The helm status command displays two areas of information:

Current CloudBees CI release
Installation notes

helm status cloudbees-core▼

NAME:   cloudbees-core
LAST DEPLOYED: Tue Apr 16 17:44:12 2019
NAMESPACE: cloudbees-core
STATUS: DEPLOYED
REVISION: 1
TEST SUITE: None
NOTES:
1. Once operations center is up and running, get your initial admin user password by running:
  kubectl rollout status sts cjoc --namespace cloudbees-core
  kubectl exec cjoc-0 --namespace cloudbees-core -- cat /var/jenkins_home/secrets/initialAdminPassword
2. Visit https://cloudbees-core.example.com/cjoc/

3. Sign in with the password from step 1.▼

Verify HTTPRoutes

After installation, the Helm chart creates HTTPRoute resources for infrastructure services.

Run the following command to verify the HTTPRoute resources created during installation:
```
kubectl get httproutes -n <cbci-namespace>▼
```
The expected output includes HTTPRoute resources for cjoc and infrastructure services (casc-bundle-service, hibernation-monitor, ssorelay, casc-retriever, depending on which services are enabled).

Verify each HTTPRoute is accepted by the Gateway:

kubectl get httproute <name> -n <cbci-namespace> \
  -o jsonpath='{.status.parents[0].conditions[?(@.type=="Accepted")].status}'▼

The expected output is True.

Verify Gateway attachment

Run the following command to check the status of the Gateway resource:

kubectl get gateway <gateway-name> -n <gateway-namespace>▼

The ATTACHED ROUTES count must include the HTTPRoute resources created by CloudBees CI. If other applications share this Gateway, the total count is higher.

Sign in to your CloudBees CI installation

Now that you’ve installed CloudBees CI and operations center, you’ll want to see your system in action.

Type the following command to retrieve your administrative user password:

kubectl exec cjoc-0 -- cat /var/jenkins_home/secrets/initialAdminPassword▼

Open a browser to http://cloudbees-core.example.com/cjoc/.
Sign in with the username admin and the password you retrieved.

For more information on running CloudBees CI on Kubernetes, refer to the CloudBees CI on modern cloud platforms administration guide.

Verify managed controller HTTPRoutes

When Gateway.Enabled is true, CloudBees CI automatically creates HTTPRoute resources for new managed controllers during provisioning. No per-controller configuration is needed.

For HA controllers, CloudBees CI adds sessionPersistence (GEP-1619) to the HTTPRoute to enable cookie-based sticky sessions. This is a Extended conformance feature. Gateway implementations that do not support it silently ignore the field, which may affect HA behavior. Refer to gateway-api-prerequisites.adoc#verify-experimental-channel-crds for details.

To verify a managed controller’s HTTPRoute after provisioning:

kubectl get httproute -n <cbci-namespace> -l app.kubernetes.io/component=managed-controller▼

To override the default for a specific controller (for example, to use Ingress instead), configure the serviceExposure setting via Configuration as Code (CasC) or the managed controller’s endpoint configuration in the operations center UI.

Next steps

Configure HTTP-to-HTTPS redirect at the Gateway level (recommended for production).
Verify Kubernetes Gateway API prerequisites, including a quick reference table for ongoing verification and troubleshooting.
For HA controllers, verify session persistence requirements: gateway-api-prerequisites.adoc#verify-experimental-channel-crds.
Troubleshoot Gateway API issues