Introduction
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
Introduction
IntroductionPipeline termsPipeline project typesCloudBees Pipeline benefits
IntroductionUsing Pipeline development utilitiesDetermining plugin compatibilityPipeline best practices
IntroductionPrerequisitesCreating your first PipelineSelecting agentsCreating 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
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 controllersManage 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 pluginController Lifecycle Notifications 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
Introduction
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
Introduction
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
CasC permissions
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

Planning for CloudBees CI on modern cloud platforms

5 minute read

The CloudBees CI on modern cloud platforms planning guide provides guidance on the requirements for installing and using CloudBees CI on modern cloud platforms.

CloudBees recommends that you review this guide and ensure all the recommendations are met before you attempt to install CloudBees CI on modern cloud platforms. If you ensure that your environment is configured correctly, it will facilitate a successful installation.

System requirements

When planning for installation, you should understand the system requirements and infrastructure.

Kubernetes cluster prerequisites per cloud provider

Be sure that your Kubernetes cluster is set up correctly. Select your provider from the list below for details:

Kubernetes and containerization knowledge prerequisites

CloudBees CI on modern cloud platforms is a stateful containerized application that is composed of multiple Kubernetes resources, such as Ingress, persistent volumes, and service accounts. Because of this, it is necessary to have a solid understanding of these resources.

CloudBees CI managed controllers deploy container-based ephemeral agents on demand to complete jobs, which means a strong knowledge of containerization is vital to create, use, and maintain such containers.

CloudBees recommends that your team becomes proficient with Kubernetes. The Cloud Native Computing Foundation (CNCF) offers training that can help you understand the architecture and concepts of Kubernetes.

Kubernetes in production

Running Kubernetes in production at a large scale goes beyond CloudBees CI and your team needs to account for considerations, such as cluster monitoring, governance, logging, security and resiliency. We recommend that you follow the recommendations of your Kubernetes provider. For more information from public cloud providers, refer to Cluster operator and developer best practices to build and manage applications on Azure Kubernetes Service (AKS).

Planning recommendations

Review the following information to ensure your environment is configured correctly prior to installing CloudBees CI on modern cloud platforms.

Table 1. Planning recommendations
Recommendation More information

Have a Kubernetes cluster in place.

A Kubernetes cluster is required. If you do not have a cluster in place, consider the time needed to set up a cluster and factor that into your installation timeline.

Verify you are using a supported version of Kubernetes.

Refer to Supported platforms for CloudBees CI on modern cloud platforms.

Ensure you have support from your Kubernetes vendor.

CloudBees cannot provide Kubernetes support.

Decide whether the team that is responsible for maintaining CloudBees CI on modern cloud platforms will be the same team that is responsible for maintaining the Kubernetes cluster.

The team should be knowledgeable in Kubernetes. If you use a different team, make sure both teams are available to work with CloudBees.

Determine if CloudBees CI on modern cloud platforms will run on a dedicated Kubernetes cluster or with other applications.

A dedicated Kubernetes cluster is preferred. If you cannot have a dedicated Kubernetes cluster, CloudBees CI on modern cloud platforms must have its own namespace.

Determine what physical or virtual resources comprise your cluster and if auto-scaling is enabled. If auto-scaling is not enabled, determine the number and size of the servers that comprise the cluster.

Note that each pod and each service needs an IP, so operations centers and controllers will consume 2 IPs each; each kube-system service and pod need an IP. Each build agent needs an IP. Each Kubernetes node needs an IP.

Auto-scaling is highly recommended to help with CPU and memory consumption. VMware Tanzu Kubernetes Grid Integrated Edition and OpenShift do not offer auto-scaling if running on-premises, so a larger infrastructure is required in the beginning or more nodes/capacity need to be added manually. For more information, refer to Cluster sizing and scaling.

Verify that the servers in the CloudBees CI on modern cloud platforms cluster have direct external Internet access, or that an HTTP proxy is available.

Internet access is needed for plugin management, the CloudBees Advisor plugin, and the CloudBees Assurance Program.

If you use a private Docker registry, ensure you have the address and credentials for the registry.

Access to the registry is needed so images can be downloaded and added to it.

Verify you have an NGINX Ingress Controller or that you can set one up.

An NGINX Ingress Controller is required, unless you use either EKS or OpenShift.

If you have a load balancer installed, verify that it points to worker nodes on the port of the Ingress service and that it has health checks.

CloudBees recommends terminating on the load balancer so that the load balancer performance is affected and not the operations center or the controller host.

The DNS entry should point to the Ingress Controller that was created. The external load balancer needs to drive traffic to the Ingress Controller.

The load balancer should have one of the following: a Kubernetes component, F5 and HA proxy, or worker nodes in a round-robin arrangement. For more information, refer to the Kubernetes documentation.

Determine if SSL certificates are required for your environment and if so, where they will be obtained from.

CloudBees recommends using publicly signed certificates.

Find out if you have a default storage class defined for your cluster.

If you are installing CloudBees CI on modern cloud platforms on premises, CloudBees strongly recommends using NFS for your storage class. CloudBees currently defaults to special classes on both GKE and AKS.

If you are using EKS, ensure that the storage class that is intended to be used by CloudBees CI on modern cloud platforms can dynamically create persistent volumes. If it does not, make sure you have a process for creating volumes as needed.

A storage class and a storage claim are required. SSD is recommended. For more information, refer to Configuring persistent storage.

Verify that you have at least one authenticated user in your cluster with permissions to create Role and RoleBinding objects during installation.

This is required only during installation.

Determine the number of teams and the total number of users that will be using CloudBees CI on modern cloud platforms.

The CloudBees Professional Services team uses this information for sizing purposes.

Determine if you will connect any external client controllers to the cluster.

CloudBees suggests that you have external controllers only to aid in the migration from Jenkins to CloudBees CI on modern cloud platforms.

Determine if you need to connect any external agents, such as agents for Microsoft Windows or Mac, to CloudBees CI on modern cloud platforms.

If you have existing external agents, you can switch over and point them to the cluster. Ephemeral agents are recommended.

Decide which authentication provider you will use.

Active Directory and SAML work well.

For Active Directory or LDAP, you need to have the server, port, and bind information on hand during CloudBees CI on modern cloud platforms installation. In addition, you should ensure that the firewall is open to allow traffic to the authentication server. It is recommended to have your networking team available during installation.

The SAML plugin can be used with Okta. It is recommended to have to the person who uses the Okta management console available during the CloudBees CI on modern cloud platforms installation.

Ensure that CloudBees CI on modern cloud platforms will have network and authentication access to the necessary build tool services.

For example, Subversion, Clearcase, Git, or Nexus.

If you are currently running Jenkins installations that you plan to migrate to CloudBees CI on modern cloud platforms, determine the number of controllers and agents.

CloudBees needs this information for sizing.

Review the trust model to plan your installation.

Trust model for CloudBees CI on modern cloud platforms

Review potential setup topics before installing, such as Deploy CloudBees CI across multiple Kubernetes clusters.

Setting up CloudBees CI on modern cloud platforms
Traditional platforms