Introduction
IntroductionPre-installation requirementsInstallUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirements for KubernetesKubernetes Gateway API for CloudBees CI on modern cloud platformsKubernetes Gateway API supported implementationsGateway API features required by CloudBees CIVerify Kubernetes Gateway API prerequisitesDeploy a Kubernetes Gateway API namespace topologyInstall CloudBees CI with Kubernetes Gateway APIMigrate from Ingress to Gateway APIClean up Helm values for Gateway API migrationVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionSystem requirementsVerify Docker imagesInstall operations centerInstall client controllersVerify build componentsVerify WAR files
IntroductionHA fundamentalsGet ready for HAInstall HA on modern cloud platformsInstall HA on traditional platformsHA considerationsNon-CAP plugin compatibilityHigh Availability (active/passive) installation for CloudBees CI on traditional platforms
Introduction
IntroductionCommon Pipeline termsPipeline project typesCloudBees proprietary features for Pipelines
IntroductionPipeline development utilitiesDetermine plugin compatibilityPipeline best practices
IntroductionUse Declarative Pipeline syntaxUse Scripted Pipeline syntax
IntroductionPipeline prerequisitesCreate your first PipelineSelect an agent for your Pipeline jobCreate a Pipeline from SCMCreate a Pipeline in the UIUnderstand and implement Pipeline as Code
IntroductionConfigure advanced Scripted PipelineConfigure the build stageConfigure the deploy stageConfigure optional step argumentsConfigure the test stageCreate a JenkinsfileCustomize parametersHandle failuresString interpolationUse multiple agentsWork with the environmentReuse configuration files
IntroductionEnable artifact traceability with fingerprintingTrigger jobs with a simple webhookRestore filesVisualize the PipelineInsert checkpointsSecure PipelinesConfigure Pipelines with user-scoped credentialsEnforce standards with Pipeline PoliciesSpecify a matrix of one or more dimensionsConvert a Freestyle project to a Declarative PipelinePipeline builds and High Availability (active/active)
IntroductionRestart aborted buildsSkip next buildConsolidated Build View pluginCloudBees Quiet Start pluginCloudBees Template 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
IntroductionSet up a Pipeline Template CatalogDefine Pipeline Template CatalogsSet up a Pipeline TemplateParameter types in the template.yaml fileManage Multibranch Pipeline options in the template.yaml fileManage Pipeline Template Catalogs in bulkExample full Maven/Java app Jenkinsfile
IntroductionBranch SourceBitbucketGitHubGitBranch Property StrategyExamples
CloudBees Docker Traceability
Introduction
Introduction
Introduction
IntroductionGet startedNavigate the operations center interfaceProvision agents in a separate Kubernetes cluster from a managed controllerProvision a controller in a different OpenShift project than the operations centerManage controllersManage controllers in specific Kubernetes namespacesMigrate an existing managed controller to High Availability (HA)Manage agentsOpt in to the Git LFS agent imageManage SSH credentialsShared agentsShared configurationsShared cloud configurationTrigger restrictionsChange NFS storage locationQuiet startMove/Copy/PromoteCluster operationsInbound agentsUse Kaniko with CloudBees CIUse Buildkit with CloudBees CIUsing self-signed certificates in CloudBees CI on KubernetesSidecar injector for self-signed certificates on OpenShiftAuto-scale nodes on EKSEnable auto-scaling nodes on GKECloud Foundry CLI PluginCloudBees CI ServiceNow integrationCreate projects based on a GitHub repository structureUse GitHub App authenticationCreate Multibranch Projects and Organization Folders with large repositoriesController Lifecycle Notifications plugin
IntroductionGet startedNavigate the operations center interfaceManage client controllersMigrate from High Availability (active/passive) to High Availability (active/active) on CloudBees CI on traditional platformsManaging agentsManage SSH credentialsShared agentsShared configurationsShared cloud configurationTrigger restrictionsQuiet startMove/Copy/PromoteCluster operationsInbound agentsCloudBees CI ServiceNow integrationCreate projects based on a GitHub repository structureUse GitHub App authenticationCreate Multibranch Projects and Organization Folders with large repositories
Introduction
Trust modelCentrally manage securityPod Security Admission
Use single sign-on (SSO) in the operations centerConfigure SAMLIntegrate Microsoft Entra IDSet up SSO Relay for CloudBees CI single sign-on
Role-based access control (RBAC)Example RBAC configurationsRBAC auto-configurer pluginRestrict job triggersAccess controls on the operations centerAccess controls on controllersOperations center specific permissionsAuthentication mappingDelegate administrationFoldersFolders Plus
Authenticate automated processes with CloudBees CI service accountsService account scope and visibilityGet started with CloudBees CI service accountsService accounts CLIService account API endpointsCreate and use service accounts with Configuration as CodeService account security considerations
OAuth client credential bindingRestricted credentialsInjecting secretsMask ephemeral secrets in Pipeline build logsEnhanced credentials maskingExternal secrets managementCyberArk credential providerManage secrets with HashiCorp VaultShared credentials administrative monitor
Cross-controller triggersTest the SSH connection to an agentManage build agents with Nodes PlusExtended security settings
Beekeeper security warningsCloudBees administrative monitorsSecurity recommendationsData collection
Replace an expired certificateList of URLs that need accessBlock access to URL patternsServe resources from JenkinsVerify Helm charts with a signature
Introduction
Introduction$JENKINS_HOME directoryBest practices for backup and restoreBack up $JENKINS_HOME manuallyBackup a Role-Based Access Control configurationRestore backup files manuallyRestore credentialsConfigure backups using the CloudBees Backup pluginSchedule backups in the CloudBees Backup pluginRestore backups created with the CloudBees Backup pluginBackup and restore on KubernetesBackup and restore on AWSBackup and restore Kubernetes cluster resources using VeleroRun backups using cluster operations
IntroductionConfigure multiple client controllers with the Jenkins CLI toolConfigure an alias for the Jenkins CLI toolConfigure Jenkins CLI tool with non-TrustStore TLS certificates
CloudBees Inactive Items Plugin
Jenkins Health Advisor by CloudBees
Count and monitor user licenses with the CloudBees User Activity Monitoring plugin
Count and monitor user licenses with the CloudBees User License Counting (ULC) system
Introduction
IntroductionCasC requirementsCasC permissionsRecommended workflow
IntroductionExport a CasC configurationTransform an exported bundleAdvanced CasC bundle configurationValidate a CasC bundle
IntroductionGet started with Configuration as Code for the operations centerConfigure the operations center on modern platforms using CasCConfigure the operations center on traditional platforms using CasCRetrieve bundles using an SCMTroubleshoot CasC
IntroductionGet started with Configuration as Code for controllersDistribute CasC bundles to controllers from your operations centerAdd controller CasC bundles to the operations centerConfigure bundle availability for controllersSet up a client controller using CasCSet up a managed controller using CasCSet up a managed controller using the CasC Controller Bundle ServiceAdvanced topicsTroubleshoot CasC for controllers
IntroductionUpdate a CasC bundleBundle update timingReview the CasC update log
IntroductionPlugin management with CasCDetermine plugin compatibility using CasCCreate an alternate plugin download site
Create items using CasC
Configure RBAC with CasC
CasC CLI commands
CasC HTTP API
Introductionbundle.yaml file referencejenkins.yaml file referenceplugins.yaml file referenceplugin-catalog.yaml file referenceitems.yaml file referencerbac.yaml file referencevariables.yaml file reference
HA on EKS Performance Test
Support policies

Non-CAP plugin compatibility for High Availability (active/active) controllers

5 minute read

CloudBees Assurance Program (CAP) plugins (open source or proprietary) are generally compatible with High Availability (HA) controllers.

Non-CAP plugin compatibility falls into the following categories:

  • What has been observed or reported to work or to break.

  • What partially works, with limitations or caveats.

  • What has been inferred from code inspection but not directly observed.

  • What remains untested.

For each plugin below, HA compatibility is indicated as follows:

  • No known issues: No HA-related problems observed or reported.

  • Known limitations: Works with HA-related caveats described in Comments.

  • Known blocking issues: Core functionality does not work with HA.

CloudBees does not support non-CAP plugins and cannot guarantee any particular level of functionality. Not all non-CAP plugins are listed below, and even for a listed plugin, noted compatibility may not cover all use cases or configurations. If you are using any of these plugins, please reach out to CloudBees Support or the CloudBees Professional Services team for advice on alternatives or best practices.

CloudBees recommends that you update all non-CAP plugins to the most recent available version before enabling HA. The compatibility status listed for each plugin applies only to the most recent release of that plugin, and in some cases, a No known issues status reflects changes made specifically to support HA in the past. Plugin functionality can evolve over time and potentially affect HA compatibility.
Table 1. Non-CAP plugin compatibility status
Plugin Compatibility status Comments Recommendation

Artifactory plugin

Known limitations

The Artifactory plugin runs several steps for nontrivial durations that are not durable or resumable like Pipeline sh steps. If a replica exits while one of these steps is running, the build is aborted when adopted by another replica.

Use sh steps (plus withCredentials) and the JFrog CLI instead of this plugin.

If you cannot migrate, mitigate by configuring retry with nonresumable. For more information, refer to Restart pipeline node blocks using the retry option.

Blue Ocean plugin

Known limitations

The Blue Ocean plugin may not accurately display running builds that are owned by other replicas. This plugin was removed from the CAP in the CloudBees CI 2.568.1.37445 release. It may still work if already installed, but is no longer supported by CloudBees.

For Pipeline visualization, use CloudBees Pipeline Explorer instead.

Crowd2 plugin

Known blocking issues

The Crowd2 plugin's cross-replica web sessions do not work due to a non-serialized field. This plugin is also blocked from the Jenkins update center for legal reasons, preventing distribution of any fix.

Use a supported security realm such as LDAP.

Dashboard View plugin

Known limitations

The Dashboard View plugin does not accurately display running builds across replicas.

Limit usage to completed builds.

Docker plugin

Known limitations

The Docker plugin defaults to deleting containers that were provisioned on demand using a label reference or the dockerNode step, and are not connected to the current instance. These containers are considered orphans.

In an HA controller with multiple replicas, replicas other than the one that launched the container might consider the container orphaned and remove it. Orphan container checks occur every 5 minutes, so builds that take longer than 5 minutes and use agents (containers) provided by this plugin always fail.

Disable this behavior by setting the system property -Dcom.nirima.jenkins.plugins.docker.DockerContainerWatchdog.enabled=false.

EC2 Fleet plugin

Known blocking issues

Replicas using the EC2 Fleet plugin can send conflicting scaling commands to the same Auto Scaling Group, and do not share state about pending instances or scale-in protection. Replicas may also orphan instances or prematurely terminate instances in use by other replicas.

Use the supported Amazon EC2 plugin instead. For more information, refer to Provision EC2 agents in HA.

Docker Swarm plugin

Known blocking issues

The Docker Swarm plugin does not support resuming Pipeline builds and is officially deprecated, with no further releases expected.

  • The Swarm Agents Cloud plugin is the replacement recommended by the plugin maintainer, but it is unknown whether it works in HA controllers.

  • The Kubernetes plugin is supported and works correctly in HA controllers.

File Parameter plugin

No known issues

The File Parameter plugin supports file uploads as Pipeline parameters, using two parameter types:

  • stashedFile: For larger files. Builds using a stashedFile parameter run on the replica that processed the trigger. For more information, refer to Workload distribution in HA.

  • base64File: For small files only.

Use the File Parameter plugin rather than Jenkins core’s built-in File Parameter type, which has been observed to fail in HA controllers for Freestyle builds.

Gerrit Trigger plugin

Known blocking issues

Each replica using the Gerrit Trigger plugin makes independent outbound SSH connections to Gerrit, resulting in duplicated events. Build cancellation logic is also broken across replicas.

Contact CloudBees Professional Services.

JiraTestResultReporter plugin

Known blocking issues

The JiraTestResultReporter plugin stores the mapping between Jira issues and test failures idiosyncratically in $JENKINS_HOME, which does not work across replicas.

Use the sh step (plus withCredentials) and the Atlassian CLI instead of this plugin.

JUnit Attachments plugin

No known issues

N/A

N/A

Lockable Resources plugin

Known blocking issues

Replicas using the Lockable Resources plugin do not consistently share information about lock state, and are unable to resume builds running on other replicas after releasing a lock.

The most commonly used functionality of this plugin can be emulated in HA mode. For more information, refer to Emulate the lock step in HA controllers.

Log CLI plugin

No known issues

N/A

N/A

Logstash plugin

Known blocking issues

HA controllers use a different build log streaming mode for scalability that the Logstash plugin does not support. For more information, refer to JENKINS-76374.

Use CloudBees Pluggable Storage instead.

Orka by MacStadium plugin

No known issues

The Orka by MacStadium plugin is reported to work well in HA. The instance cap configuration functions as a per-replica limit rather than a per-controller limit, the same limitation described in Provision GCE agents in HA.

N/A

Parallel Test Executor plugin

No known issues

N/A

N/A

Parameterized Remote Trigger plugin

No known issues

N/A

N/A

Parameterized Scheduler plugin

No known issues

The Parameterized Scheduler plugin is specifically supported by the HA system. Just as with built-in timer triggers, only one replica considers the crontab in a given time slot.

N/A

Pipeline Utility Steps plugin

No known issues

The Pipeline Utility Steps plugin's nodesByLabel step specifically skips HA executor clones of permanent agents.

N/A

SonarQube Scanner plugin

No known issues

The SonarQube Scanner plugin is specifically supported by the HA system. When a webhook is received from SonarQube, it is broadcast to all controller replicas; only one actually processes the payload.

N/A

Swarm plugin

No known issues

The Swarm plugin is supported as a special case of inbound permanent agents. The default Swarm agent behavior is customized to create a persisted agent, rather than an ephemeral one, with executor clones created on demand so that different replicas can use them concurrently. controller replicas track whether the agent has been connected recently, rather than deleting it immediately upon the main agent’s disconnection, and only delete it to clean up after a configurable delay (the default is 15 minutes).

Use the plugin normally, including -executors and -webSocket. You do not need, and should not use, lifecycle-related options such as:

  • -keepDisconnectedClients

  • -deleteExistingClients

  • -disableClientsUniqueId

Webhook Step plugin

No known issues

The Webhook Step plugin is specifically supported by the HA system. When a webhook is received, it is broadcast to all controller replicas; only one actually processes the payload.

N/A
HA considerations
High Availability (active/passive) installation for CloudBees CI on traditional platforms