Preparing for a migration from CloudBees CI on traditional platforms to CloudBees CI on modern cloud platforms

10 minute readKnowledge base

Issue

  • You are planning a migration from CloudBees CI on traditional platforms (VM-based operations center and client controllers) to CloudBees CI on modern cloud platforms (Kubernetes-based).

  • You want to enable High Availability and Horizontal Scalability after migration

  • You need to understand the pre-migration assessment work, architectural decisions, and version/plugin compatibility constraints to complete before scheduling the cutover.

Environment

Resolution

This article describes how to prepare for the migration from CloudBees CI on traditional platforms to CloudBees CI on modern cloud platforms. The actual cutover steps are covered in the official migration documentation; this guide focuses on the assessments, decisions, and remediation work to complete before beginning the cutover.

For the official migration runbook, refer to Migrate from CloudBees CI on traditional platforms to CloudBees CI on modern cloud platforms.

Pre-migration assessment checklist

Complete every item in this section before scheduling a cutover.

Inventory and cleanup

  • Install the CloudBees Inactive Items Plugin on the source environment. Identify and remove jobs, folders, agents, and items that have been inactive long enough to be considered unnecessary. Doing so reduces risk as well as runtime cost.

  • Install Jenkins Health Advisor by CloudBees on the source environment. Triage all reported issues; resolve priority findings before migration.

  • Install the CloudBees Quiet Start plugin so the target controller does not start running jobs automatically the first time it boots after restore.

  • Generate a support bundle from each source controller. Archive it; it may be needed for diagnostic comparison after cutover.

Version alignment

  • The source (traditional) and target (modern) CloudBees CI versions must align on the V.R.M fields of the version string. Plan to either upgrade the source first, or pick a target version that matches.

  • Confirm the Java version on the source. If still on Java 11, upgrade to Java 17 or Java 21 before migrating, especially if static agents are retained.

  • Confirm the Kubernetes cluster version meets the minimum required by the target CloudBees CI version.

For more information, refer to:

Plugin compatibility audit

For every plugin in the source inventory:

  1. Confirm the plugin is listed in the target CloudBees CI release notes, or is available from the Update Center for the target version.

  2. If HA will be enabled, identify plugins or Pipeline steps with known HA limitations (see HA-specific limitations to catalog).

  3. Replace deprecated plugins with their supported equivalents now, not during the cutover.

  4. Remove plugins with no current usage.

If there are any open CloudBees support tickets related to plugin compatibility, ensure they are resolved or have a documented workaround before scheduling the cutover.

Job type audit (critical if enabling HA)

If HA mode is part of the target architecture, audit every job:

  • Pipeline jobs (Declarative or Scripted): Fully supported in HA.

  • Freestyle and Maven jobs: Not HA-compatible. Builds running on a replica that is restarted or removed are aborted; no other replica adopts them.

CloudBees provides a Declarative Pipeline Migration Assistant to help convert Freestyle jobs. Plan this conversion as a parallel workstream; it is often the longest pole of the entire migration.

For more information, refer to:

Architectural decisions to lock down

Decide the following before building the target platform:

Decision Considerations

controller topology

One controller per team/product vs. shared. Modern platforms favor a per-controller-namespace model.

Operations Center vs. controller separation

Both run as separate pods/Deployments on Kubernetes; size each independently.

HA on/off per controller

Not all controllers need HA. Enable it where uptime SLA justifies it.

Storage class

Must support dynamic provisioning. HA requires ReadWriteMany (RWX); see [storage-strategy].

Ingress strategy

Ingress-NGINX or Kubernetes Gateway API; see Ingress options.

Agent strategy

Static (SSH/WebSocket) vs. dynamic Kubernetes pod-template agents.

Backup strategy

CloudBees Backup plugin (application scope) and/or Velero (cluster scope); see Two complementary layers.

Identity and RBAC

Validate that the authentication provider (Active Directory, OIDC, SAML) is reachable from the cluster.

Observability

Decide log shipping, metrics scraping, and tracing pipelines before workloads land.

Split monolithic controllers

If the traditional environment has one large monolithic client controller hosting many teams, split it before migration. Reorganizing on Kubernetes (per-controller namespace, distinct RBAC, isolated resources) is much harder if the monolith is carried forward.

For more information, refer to Split a controller in CloudBees CI on traditional platforms

Key compatibility considerations

What changes on Kubernetes

  • controllers run as Deployments (not StatefulSets) when HA is enabled.

  • Built-in executors on controllers must be set to 0 when HA is enabled.

  • JVM heap is sized as a percentage of pod memory, not via -Xmx/-Xms.

  • Ingress and TLS are handled by Kubernetes Ingress/Gateway resources, not by the controller itself.

HA-specific limitations to catalog

If HA is in scope, document these limitations and verify each affected job:

  • Freestyle and Maven projects: Not supported (see Job type audit (critical if enabling HA)).

  • build step (Pipeline: Build Step plugin): Emulated in HA as of CloudBees CI 2.516.3.29358 and later, with parameter type limitations (string, booleanParam, text).

  • lock step (Lockable Resources plugin): Emulated for ephemeral resource locks as of CloudBees CI 2.516.3.29358 and later.

  • Agents: Each agent must have a single executor. Permanent multi-executor agents need the HA agent with multiple executors property to auto-generate single-executor clones. Inbound agents with Manually Trusted Key Verification cannot be used with HA multi-executor clones.

  • Built-in executors: Set to 0 on HA controllers.

  • Windows controllers: HA is not supported.

  • Blue Ocean: May not accurately display builds owned by another replica. CloudBees recommends using CloudBees Pipeline Explorer instead. Blue Ocean and team controllers reached end-of-life in July 2026.

  • Pipeline durability: Set the default Speed/Durability Level to Maximum survivability/durability but slowest. This is required for build adoption across replicas.

For more information, refer to Install HA (active/active) on CloudBees CI on modern cloud platforms.

Storage strategy

HA on Kubernetes requires shared storage with ReadWriteMany (RWX) access so all replicas of a controller see the same $JENKINS_HOME.

  • Recommended: Hosted network filesystem (Amazon EFS on AWS, Azure Files on AKS, Filestore on GKE).

  • Non-production fallback: NFS server provisioner inside the cluster backed by the default RWO disk class.

  • Latency matters: Storage must be accessible simultaneously by all replicas with consistent low-latency I/O. Plan capacity, throughput, and connection limits to scale with the controller count.

  • For large-scale deployments, validate filesystem-level throughput, IOPS, and concurrent-connection limits before rollout. Pilot at expected scale.

For more information, refer to Pre-installation requirements for Kubernetes.

Networking and ingress

Ingress options

Two ingress options are supported:

Option Status Notes

Ingress-NGINX

Currently supported

Default historical option with a mature feature set. The Ingress-NGINX upstream project is reaching end-of-life; plan migration to Gateway API.

Kubernetes Gateway API

Generally Available since CloudBees CI 2.555.2.36753

Long-term direction. Recommended for new deployments.

Session affinity is mandatory for HA

Without sticky sessions, users will be logged out randomly as requests bounce between replicas.

  • NGINX: nginx.ingress.kubernetes.io/affinity: cookie

  • Gateway API: sessionPersistence field on HTTPRoute (type: Cookie, appropriate ttl). Implementation support varies:

    • Istio silently ignores the field; use a DestinationRule with consistentHash.httpCookie as a workaround.

    • Envoy Gateway (v1.2.0+) and NGINX Gateway Fabric (v2.4.0+) fully support session persistence.

    • Traefik does not support session persistence and is not recommended for HA controllers.

Inter-replica communication

When designing network policies and security groups for HA controllers, allow:

  • TCP 5701 (Hazelcast): Default port used by replicas to maintain cluster state.

  • Reverse-proxy HTTP/HTTPS between replicas: Required so one replica can serve resources owned by another (log views during active builds, WebSocket agents, inbound TCP agents).

Network policies that block intra-namespace controller-to-controller traffic are a common cause of log viewing failures during active builds in HA deployments. Validate connectivity end-to-end before declaring HA healthy.

Migration path from Ingress-NGINX to Gateway API

Two methods are supported:

  1. New cluster: Deploy with gatewayApi.enabled=true and ingress.enabled=false.

  2. Existing cluster: Run both simultaneously (coexistence mode), use weighted DNS to shift traffic gradually (for example, 10% to 100% Gateway), then disable Ingress.

For more information, refer to:

Backup, restore, and credentials

Two complementary layers

Layer Tool Use

Application

CloudBees Backup plugin

Per-controller backup/restore, migration between controllers, cluster-operation backups across multiple controllers.

Infrastructure

Velero

Cluster-level disaster recovery, cross-region failover, full-state restore into an empty cluster.

CloudBees recommends running both in production: the Backup plugin for routine controller-level recovery, and Velero for cluster-level disaster recovery.

Credentials

  • Folder-scoped credentials: Automatically handled by Move/Copy/Promote operations.

  • Top-level (system-scoped) credentials: Must be migrated manually. Options include:

    1. Pre-create them in the target controller before restoring backups.

    2. Recreate via the credentials API as a scripted step.

    3. Move them into folders on the source so they migrate naturally.

  • For enterprise environments, evaluate external secrets managers (HashiCorp Vault, CyberArk, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) as part of the migration rather than after.

For more information, refer to:

JVM and resource sizing

Container JVM tuning differs from bare-metal/VM tuning. The most common mistake is carrying -Xmx/-Xms forward; do not do this on Kubernetes.

Heap

  • Use -XX:InitialRAMPercentage=50.0 -XX:MaxRAMPercentage=50.0.

  • Set container memory requests and limits equal.

  • Do not set -Xmx/-Xms directly; they override the RAMPercentage flags.

  • Do not enable Enable heap ratio in the UI (deprecated; injects -Xmx/-Xms).

  • Do not exceed 50.0; higher ratios are unstable due to off-heap JVM usage.

  • Minimum heap: 2 GB for Operations Center, 4 GB for managed controllers in production.

  • Maximum heap: 16 GB; beyond that, scale horizontally.

Garbage collection

Use G1GC with the recommended argument set:

-XX:+UseG1GC
-XX:+UseStringDeduplication
-XX:+ParallelRefProcEnabled
-XX:+AlwaysPreTouch
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=${LOGDIR}
-XX:+DisableExplicitGC
-Xlog:gc*=info,gc+heap=debug,gc+ref*=debug,gc+ergo*=trace,gc+age*=trace:file=${LOGDIR}/gc.log:utctime,pid,level,tags:filecount=2,filesize=100M
▼

Avoid ParallelGC and CMS.

Java version selection

  • CloudBees CI 2.479.3.1 through 2.541.3.36069 support both Java 17 and Java 21.

  • CloudBees CI 2.555.1.36485 and later require Java 21 (Java 17 is no longer supported).

  • Java 11 support ended in late October 2024.

Linux kernel 6.12.0+ workaround

For CloudBees CI versions 2.528.1.29783 through 2.541.1.35570, running on hosts with Linux kernel 6.12.0 and later can cause OOMKilled events. Add -XX:MaxRAM=Xg (where X is the container memory limit in GB) until upgrading to CloudBees CI 2.555.1.36485 or later, which bundles the fix.

For more information, refer to:

Agent strategy

Plan agent topology early; it affects pipeline portability.

  • Kubernetes pod-template agents (via the Kubernetes plugin) are the cloud-native default: ephemeral, scalable, declarative. Recommended for new pipelines.

  • Static agents (SSH outbound or WebSocket inbound) are supported and often used during early phases of migration so existing pipelines continue to work unchanged.

  • For HA controllers: Each agent must have a single executor. Prefer outbound SSH agents with the CloudBees High Availability retention strategy.

  • Agent labels: Preserve label naming from the source so pipelines using agent { label '…​' } continue to schedule correctly. Treat label preservation as a non-negotiable migration invariant.

Observability

Whatever the observability stack (cloud-native metrics, vendor APM, log aggregation), implement before workloads land. Recommended baseline:

  • Cluster/infrastructure: Pod CPU/memory, persistent volume IOPS and saturation, network policy denials.

  • CloudBees CI-specific: JVM heap, GC pauses, thread count (under 700), GC throughput (above 98%), build queue depth, agent provisioning latency.

  • Logs: controller logs, GC logs, audit logs.

  • CloudBees tooling: Health Advisor and Beekeeper for plugin and configuration health.

Migration readiness gate

Before scheduling the cutover, the following items should all be confirmed:

  • Migration path selected and documented.

  • Source and target CloudBees CI versions aligned on V.R.M.

  • Source running on Java 17 or Java 21.

  • Plugin inventory audited; incompatible or deprecated plugins remediated.

  • Freestyle/Maven jobs catalogued; HA-incompatible jobs have a conversion plan.

  • Top-level credentials inventoried with a migration approach.

  • Shared storage class with RWX provisioned and load-tested (for HA).

  • Ingress/Gateway API path selected; session affinity validated.

  • Inter-replica networking (Hazelcast 5701, HTTP/HTTPS) validated.

  • Backup strategy implemented (CloudBees Backup plugin and Velero).

  • JVM tuning standardized (RAMPercentage, G1GC, logging).

  • Operations Center and controller sizing documented.

  • Agent strategy decided; labels preserved.

  • Observability pipelines live and tested.

  • Authentication provider reachable and tested from the cluster.

  • Health Advisor findings on source resolved or accepted.

  • CloudBees Quiet Start plugin in place on target.

  • Rollback plan documented.

When every item is confirmed, the migration is ready to execute following the official CloudBees migration runbook.

Appendix A: AWS EKS-specific considerations

This appendix supplements the preceding sections for teams targeting Amazon EKS.

Cluster foundations

  • Validate that the EKS Kubernetes version meets CloudBees CI minimums. Refer to the Supported Platforms documentation.

  • Use EKS managed node groups with auto-scaling (Cluster Autoscaler or Karpenter). Right-size minimum/maximum capacity to absorb build bursts.

  • Reserve nodes for controllers separately from agents using taints and tolerations plus node selectors. A common pattern: a dedicated tainted node group for controllers, and one or more node groups for agents.

Storage: Amazon EFS

  • Use Amazon EFS with the EFS CSI driver for the ReadWriteMany $JENKINS_HOME.

  • Provision EFS access points per controller to avoid permissions collisions and simplify backup scoping.

  • Validate EFS throughput mode (Elastic vs. Provisioned) at expected fleet size. Burst throughput can be exhausted at scale; pilot at production-equivalent controller counts before cutover.

  • Be aware of EFS connection and throughput limits per filesystem; design the controller-to-filesystem mapping accordingly.

Ingress: NGINX or ALB with Gateway API

  • A common pattern is AWS ALB to NGINX Ingress controller in-cluster to Services.

  • For Gateway API on EKS, choose a conformant controller. Envoy Gateway and NGINX Gateway Fabric have the most complete CloudBees-tested session-persistence support.

  • TLS can terminate at the ALB (using ACM certificates) or at the in-cluster Ingress/Gateway. Pick one and document it.

DNS

  • Hybrid public/private DNS is common: internal users reach controllers via private Route 53 zones; external integrations use public zones with appropriate WAF rules.

  • Use ExternalDNS to automate record creation from Ingress/Gateway resources.

Backups on AWS

  • Configure the CloudBees Backup plugin to write to Amazon S3 with bucket lifecycle policies for retention.

  • For Velero, use S3 for object storage and EBS snapshots for volume snapshots. Velero v1.5 restore must occur in the same region/availability zone as the backup; later versions relax this.

Observability on AWS

  • CloudWatch Container Insights for cluster-level metrics.

  • Choose a logging destination early (CloudWatch Logs, an APM vendor, or a SIEM). Multi-pipeline log shipping is expensive at scale; consolidate where possible.

Security and egress

  • Use IAM Roles for Service Accounts (IRSA) for any pod that needs AWS API access, for example the EFS CSI driver, the CloudBees Backup plugin writing to S3, and ExternalDNS.

  • If the organization restricts external SCM access, enforce it at the egress firewall or via VPC endpoints. CloudBees CI does not natively restrict which SCM organizations agents can clone from; place that control at the network or identity layer.

Additional information

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.