IntroductionPre-installation requirementsInstallingVerifying Docker imagesUninstalling
IntroductionPre-installation requirementsInstallingVerifying Docker imagesUninstalling
IntroductionPre-installation requirementsInstallingVerifying Docker imagesUninstalling
IntroductionPre-installation requirementsInstallingVerifying Docker imagesUninstalling
IntroductionPre-installation requirementsInstallingVerifying Docker imagesUninstalling
IntroductionPre-installation requirementsInstallingVerifying Docker imagesUninstalling
IntroductionSystem requirementsVerifying Docker imagesInstalling operations centerInstalling client controllersInstalling build agentsVerifying build componentsVerifying WAR files
IntroductionHA (active/active) fundamentalsInstallation on modern cloud platforms (active/active)Installation on traditional platforms (active/active)HA (active/active) considerationsSpecific High Availability (active/passive) installation for CloudBees CI on traditional platforms
IntroductionPipeline termsPipeline project typesCloudBees Pipeline benefits
IntroductionUsing Pipeline development utilitiesDetermining plugin compatibilityPipeline best practices
IntroductionPrerequisitesCreating your first PipelineCreating Pipelines in SCMCreating Pipelines in Web UIUsing Pipeline as Code
IntroductionConfig Adv ScriptedConfig Build StageConfig Deploy StageConfig Optional Step ArgsConfig Test StageCreating JenkinsfileCustomizing ParametersHandling FailuresString InterpolationUsing Multiple AgentsWorking With The Env
IntroductionManaging artifactsTracing artifactsTriggering jobs with a simple webhookRestoring filesVisualizing PipelineInserting checkpointsSecuring PipelinesConfiguring Pipelines with user-scoped credentialsUsing Pipeline PoliciesSpecifying a matrix of one or more dimensionsConverting a Freestyle project to a Declarative PipelinePipeline builds and HA (active/active)
IntroductionRestarting aborted buildsLong-running buildsSkip next buildConsolidated Build View pluginCloudBees Quiet Start pluginCloudBees Template pluginCloudBees Git Validated Merge pluginCloudBees Workspace Caching
IntroductionTrigger a job with a notification event using Cross Team CollaborationEnable external notification events with external HTTP endpointsCluster-wide copy artifactsCluster-wide job triggers
IntroductionSetting up a Pipeline Template CatalogDefining Pipeline Template CatalogsSetting Up A Pipeline TemplateUsing parameters in template.yamlManaging multibranch Pipeline options in template.yamlManaging Pipeline Template Catalogs in bulkExample full Maven/Java app Jenkinsfile
IntroductionUsing Declarative Pipeline syntaxUsing Scripted Pipeline syntax
IntroductionBranch SourceBitbucketGitBranch Property StrategyExamples
CloudBees Docker Build and Publish pluginCloudBees Docker TraceabilityDocker Pipeline pluginCloudBees Docker Hub/Registry Notification plugin
Introduction
IntroductionGetting startedNavigating the operations centerProvisioning managed controllers in multiple Kubernetes clustersProvisioning agents in a separate Kubernetes cluster from a managed controllerProvisioning a controller in a different namespace than the operations centerProvisioning a controller in a different OpenShift project than the operations centerManaging controllersManaging controllers in specific Kubernetes namespacesMigrating an existing managed controller to High Availability (HA)Managing agentsShared agentsShared configurationShared cloud configurationTrigger restrictionsChanging NFS storage locationQuiet startMove/Copy/PromoteCluster operationsInbound agentsUsing KanikoUsing Buildkit (docker buildx)Sidecar injector for self-signed certificates on KubernetesSidecar injector for self-signed certificates on OpenShiftUsing auto-scaling nodes on EKSUsing auto-scaling nodes on GKECloudBees Amazon Web Services Deploy EngineAmazon Web Services CLI PluginCloud Foundry CLI PluginIntegrate OpenShift CLIServiceNow integrationCreating projects based on GitHub repository structureUsing GitHub App authenticationWikiText plugin
IntroductionGetting startedNavigating the Operations CenterManaging client controllersMigrating from High Availability (active/passive) to High Availability (active/active) on CloudBees CI on traditional platformsManaging agentsShared agentsShared configurationShared cloud configurationTrigger restrictionsQuiet startMove/Copy/PromoteCluster operationsJava web start agentsServiceNow integrationCreating projects based on GitHub repository structureUsing GitHub App authenticationWikiText plugin
IntroductionTrust modelPod Security AdmissionCentrally managing security for controllersCyberark Credential Provider PluginHashiCorp Vault PluginEnabling advanced use cases: cross controller triggers and bulk operationsRestricting access and delegating administration with Role-Based Access ControlCreating secure folders with Role-Based Access Control Auto ConfigurerRestricting job triggersSetting up operations center access controlsSetting up access controls on connected controllersTesting the SSH connection to an agentConfiguring restricted credentials with the CloudBees Restricted Credentials pluginFoldersFolders PlusInjecting secrets into buildsManaging build agents with Nodes Plus pluginExtended security settingsEnhanced credentials maskingUnderstanding Beekeeper security warningsPreventing unauthorized interaction between buildsSecurity recommendationsUsing single sign-on (SSO)CloudBees CI integration with Microsoft Entra IDoperations center specific permissionsAuthentication mappingExample configurationsDelegating administrationData collection for the CloudBees Analytics PluginExternal secrets managementReplacing an expired certificateList of URLs that need accessBlocking access to URL patterns using the CloudBees Request Filter PluginServing resources from JenkinsVerifying Helm Charts Published with a Signature
IntroductionConfiguring network requirementsCentrally managing security for controllersCyberark Credential Provider PluginHashiCorp Vault PluginEnabling advanced use cases: cross-controller triggers and bulk operationsRestricting access and delegating administration with Role-Based Access ControlCreating secure folders with Role-Based Access Control Auto ConfigurerRestricting job triggersTesting the SSH connection to an agentConfiguring restricted credentials with the CloudBees Restricted Credentials pluginFoldersFolders PlusInjecting secrets into buildsManaging build agents with Nodes Plus pluginUnderstanding Beekeeper security warningsPreventing unauthorized interaction between buildsSecurity recommendationsExtended security settingsUsing single sign-on (SSO)CloudBees CI integration with Microsoft Entra IDOperations Center specific permissionsAuthentication mappingExample configurationsDelegating administrationData collection for the CloudBees Analytics PluginExternal secrets managementList of URLs that need accessBlocking access to URL patterns using the CloudBees Request Filter PluginServing resources from Jenkins
IntroductionExplaining $JENKINS_HOMEBest practices for backup and restoreBacking up manuallyRestoring manuallyRestoring credentialsUsing the CloudBees Backup PluginScheduling your backups in the CloudBees Backup PluginRestoring from CloudBees Backup PluginBackup and restore on KubernetesBackup and restore on AWSUsing Velero for backup and restore of Kubernetes clustersUsing cluster operations to run backups
IntroductionGetting the CLI toolUsing the CLI toolExamples of usageConfiguring multiple client controllersConfiguring an alias for the Jenkins CLI toolConfiguring the Jenkins CLI tool to work with non-TrustStore SSL certificatesCasC bundle management on operations center
CloudBees Inactive Items Plugin
Jenkins Health Advisor by CloudBees
CloudBees Pull Request Builder for GitHub plugin
Count and monitor user licenses with the CloudBees User Activity Monitoring plugin
Introduction
CasC fundamentals
CasC requirements
IntroductionGetting startedCreating a bundleConfiguring the operations center on modern platformsConfiguring the operations center on traditional platformsRetrieving bundles using SCMUpdating a bundleBundle update timing for the operations centerViewing the operations center update logCreating itemsConfiguring RBACDetermining plugin compatibilityTroubleshooting
IntroductionGetting startedCreating a bundleAdding controller bundles to the operations centerUpdating a bundleBundle update timing for controllersViewing the controller update logConfiguring bundle availabilitySetting up a managed controllerSetting up a client controllerCreating itemsConfiguring RBACDetermining plugin compatibilityAdvanced topicsTroubleshooting
Plugin management with CasC
CasC CLI commands
CasC HTTP API
Support policies

Installation for CloudBees CI on traditional platforms (active/active)

4 minute read

High Availability (active/active) on Windows controllers is not supported.

This document covers specific instructions to install and configure High Availability (active/active) for CloudBees CI on traditional platforms. Instructions and standard methods to install CloudBees CI on traditional platforms can be found in this section.

Load balancer

You need to set up a load balancer to route HTTP and, if desired, WebSocket, traffic to all the replicas.

There are a lot of different load balancers to choose from, so it’s up to you to figure out how to set up your specific one.

The load balancer needs two configurations applied:

  • The load balancer must be configured with sticky sessions.

  • You should setup a health check against /whoAmI/api/json?tree=authenticated

Storage

All replicas must point to the same $JENKINS_HOME location.

For CloudBees CI on traditional platforms, you must use a NFS compatible shared file system.

To properly configure the NFS client on your controller instances, follow the instructions from the NFS Guide knowledge base article.

Controller Service Configurations

Whether you installed CloudBees CI on traditional platforms using a package manager, that is yum, dnf, zypper or apt, there are still more changes you need to make to the service configuration files on each replica.

If you installed via yum, dnf, or zypper, that is, a RPM install, you need to update:

  • /etc/sysconfig/cloudbees-core-cm

If you installed via apt, that is, a DEB install, you need to update:

  • /etc/default/cloudbees-core-cm

The following sections document what the values should be updated in the respective service configuration files.

JENKINS_HOME

This should be changed from /var/lib/cloudbees-core-cm to whatever the NFS mount is on the replica.

For instance, if you created the NFS mount as /mnt/nfs_cc_home, then the value changes from:

  • JENKINS_HOME="/var/lib/cloudbees-core-cm"

to:

  • JENKINS_HOME="/mnt/nfs_cc_home"

JENKINS_ARGS

There is one mandatory argument to set in JENKINS_ARGS and one optional argument.

First, add an argument to a directory on local disk (not shared disk) for --pluginroot. This specifies where the plugin files should be extracted.

If you did an RPM install, the value should be:

--pluginroot=/var/cache/cloudbees-core-cm/plugins
▼

The plugins subdirectory will be automatically created when the service starts.

If you did a DEB install, the value should be:

--pluginroot=/var/cache/$NAME/plugins
▼

The optional argument to set is --prefix. You will set this argument if you are placing your controller under a domain name instead of using a subdomain.

For example, let’s assume that you want the URL to the controller to be:

https://cloudbees-ci.example.com/cc1/
▼

In this case, you would set the argument to:

--prefix=/cc1
▼

The value is the same for both RPM and DEB installs.

For a complete example that includes both arguments in addition to the default values for a DEB install looks like:

JENKINS_ARGS="--webroot=/var/cache/$NAME/war --httpPort=$HTTP_PORT --pluginroot=/var/cache/$NAME/plugins --prefix=/cc1"
▼

Java options

Java 11 is required to run CloudBees CI on traditional platforms 2.414.2.2 or higher

The Java options and system properties discussed below are only the values for configuring High Availability.

For the overall JVM recommended arguments to run CloudBees CI on traditional platforms, please review the JVM Recommended Arguments section of Prepare Jenkins for Support.

The following Java options and system properties are required for the controllers to run in HA mode:

--add-exports=java.base/jdk.internal.ref=ALL-UNNAMED
--add-modules=java.se
--add-opens=java.base/java.lang=ALL-UNNAMED
--add-opens=java.base/sun.nio.ch=ALL-UNNAMED
--add-opens=java.management/sun.management=ALL-UNNAMED
--add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED
-Djenkins.model.Jenkins.crumbIssuerProxyCompatibility=true
-DexecutableWar.jetty.disableCustomSessionIdCookieName=true
-Dcom.cloudbees.jenkins.ha=false
-Dcom.cloudbees.jenkins.replication.warhead.ReplicationServletListener.enabled=true
-Djenkins.plugins.git.AbstractGitSCMSource.cacheRootDir=/var/cache/cloudbees-core-cm/caches/git
-Dorg.jenkinsci.plugins.github_branch_source.GitHubSCMSource.cacheRootDir=/var/cache/cloudbees-core-cm/caches/github-branch-source
▼

If you did a RPM install, you can add the following after the initial JENKINS_JAVA_OPTIONS= definition:

JENKINS_JAVA_OPTIONS+=("--add-exports=java.base/jdk.internal.ref=ALL-UNNAMED")
JENKINS_JAVA_OPTIONS+=("--add-modules=java.se")
JENKINS_JAVA_OPTIONS+=("--add-opens=java.base/java.lang=ALL-UNNAMED")
JENKINS_JAVA_OPTIONS+=("--add-opens=java.base/sun.nio.ch=ALL-UNNAMED")
JENKINS_JAVA_OPTIONS+=("--add-opens=java.management/sun.management=ALL-UNNAMED")
JENKINS_JAVA_OPTIONS+=("--add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED")
JENKINS_JAVA_OPTIONS+=("-Djenkins.model.Jenkins.crumbIssuerProxyCompatibility=true")
JENKINS_JAVA_OPTIONS+=("-DexecutableWar.jetty.disableCustomSessionIdCookieName=true")
JENKINS_JAVA_OPTIONS+=("-Dcom.cloudbees.jenkins.ha=false")
JENKINS_JAVA_OPTIONS+=("-Dcom.cloudbees.jenkins.replication.warhead.ReplicationServletListener.enabled=true")
JENKINS_JAVA_OPTIONS+=("-Djenkins.plugins.git.AbstractGitSCMSource.cacheRootDir=/var/cache/cloudbees-core-cm/caches/git")
JENKINS_JAVA_OPTIONS+=("-Dorg.jenkinsci.plugins.github_branch_source.GitHubSCMSource.cacheRootDir=/var/cache/cloudbees-core-cm/caches/github-branch-source")
▼

If you did a DEB install, you will update the default JAVA_ARGS value from:

JAVA_ARGS="-Djava.awt.headless=true"
▼

to:

JAVA_ARGS="-Djava.awt.headless=true --add-exports=java.base/jdk.internal.ref=ALL-UNNAMED --add-modules=java.se --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.management/sun.management=ALL-UNNAMED --add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED -Djenkins.model.Jenkins.crumbIssuerProxyCompatibility=true -DexecutableWar.jetty.disableCustomSessionIdCookieName=true -Dcom.cloudbees.jenkins.ha=false -Dcom.cloudbees.jenkins.replication.warhead.ReplicationServletListener.enabled=true -Djenkins.plugins.git.AbstractGitSCMSource.cacheRootDir=/var/cache/$NAME/caches/git -Dorg.jenkinsci.plugins.github_branch_source.GitHubSCMSource.cacheRootDir=/var/cache/$NAME/caches/github-branch-source"
▼

Note the last two Git related items in both examples. The base directory, that is, /var/cache/cloudbees-core-cm/caches or /var/cache/$NAME/caches, should be a disk local to the replica and not on a shared disk.

However, this base directory will need to be created by you and have the correct permissions and ownership set. Here’s a basic example of how to create the directory:

sudo mkdir -p /var/cache/cloudbees-core-cm/caches
sudo chmod 700 /var/cache/cloudbees-core-cm/caches
sudo chown -R cloudbees-core-cm:cloudbees-core-cm /var/cache/cloudbees-core-cm/caches
▼

The subdirectories will be created automatically after the base directory is created.

Hazelcast

Replicas must be able to contact one another on whichever port is chosen at random for Hazelcast. Discovery is automatic based on the common $JENKINS_HOME volume.

If an explicit hazelcast.config Java system property is set, it will be recognized and applied. You can find additional information about Hazelcast configuration in the Hazelcast documentation site

Setup wizard

When customizing the list of plugins to install, be sure to add the ci-plugin:cloudbees-replication. Alternatively, use Configuration as Code to define the controller, and include the plugin cloudbees-replication.

Do not include the CloudBees High Availability (Active/Passive) Management plugin (cloudbees-ha) that is used by the older active-passive HA system.

If the cloudbees-ha plugin is installed, it should be uninstalled and the replicas should be restarted prior to installing the cloudbees-replication plugin.

Restarting controllers

If you need to restart a controller, for example, after installing a plugin, make sure that every replica is restarted.

Additional resources

Getting started with High Availability on traditional platforms

Installation on modern cloud platforms (active/active)
HA (active/active) considerations