Table of contents

CloudBees Jenkins Enterprise 1.x administration guide


Note
CloudBees will no longer be supporting CloudBees Jenkins Enterprise 1.x after July 30, 2020. This end-of-life announcement allows CloudBees to focus on driving new technology and product innovation for CloudBees Core. For information on moving to CloudBees Core, please refer to Migrating from CloudBees Jenkins Enterprise 1.x to CloudBees Core on modern cloud platforms which has been created to help you with the migration process. Existing customers can also contact their CSM to help ensure a smooth transition.

Continuous Delivery as a Service

CloudBees Jenkins Enterprise is designed to support any organization’s CI/CD needs - regardless of whether they’re a single team with simple delivery pipelines or a massive, multi-national corporation with complex A/B deployments.

CloudBees Jenkins Enterprise enables administrators to offer an internally managed CD as a Service to their teams. With CloudBees Jenkins Enterprise, administrators centrally manage their organization’s build cluster using Managed Masters and templatized build agents.

Agents are computers that handle the tasks of running builds in a CloudBees Jenkins Enterprise cluster, and within the context of a CloudBees Jenkins Enterprise cluster, they are shared resources for connected masters.

This "Continuous Delivery as a Service" section assumes that: CloudBees Jenkins Enterprise is up and running within the organization, the Administrator(s) have a functional CloudBees Jenkins Enterprise project configured, and have downloaded/installed the cje tool.

By adding capacity, administrators can support additional Managed Masters, Jenkins agents, or improve cluster performance and resiliency.

Building pipelines on CloudBees Jenkins Enterprise

CloudBees Jenkins Enterprise allows administrators to standardize their build environments and share those environments with their internal teams, significantly reducing the overhead of managing each. These standardized agents are defined as Docker images within the Operations Center dashboard, and propagated to any connected master.

CloudBees Jenkins Enterprise comes out of the box with a set of pre-configured agent images. Administrators can configure which agent images - pre-configured or their own custom ones - are available to their teams.

Creating an agent image

Most administrators will want to create and customize the pre-configured agent image to ensure their teams’ necessary tools are available on it.

To do this, administrators will need to create a new item in Operations Center and select Docker Agent Template as the item type.

new docker agent

Later on, teams will need to use the Docker Agent Template’s name as a "label" in their build configurations when they want to use a container built from this template for their projects’ build environment.

Once the name and item type are configured, administrators can customize the environment that any containers created from this template’s image will run in:

new docker agent configuration
Field Default Value Description

Use when no label is specified

  • ❏  

Leave this option checked to make the agent image available to build jobs that have not explicitly defined a certain agent as their target build environment. When several agent templates have this option selected, builds will pick the first available agent template with this configuration.

Enable this slave template

  • ✓  

Leave this option checked unless this template is not meant to be immediately available.

CPU shares

0.1

Most administrators should leave this setting in its default state, but advanced administrators may refer to the corresponding Docker option to customize this setting.

Memory

256

For most administrators, this value can be left in its default state. This value defines how much memory should be allocated for a Docker container created from this template’s image.

JVM Memory

128

For most administrators, this value can be left in its default state. This value defines the maximum heap size given to the Jenkins agent as a share of the above Memory value.

JVM Arguments

(empty)

For most administrators, this setting can be left empty. This setting allows administrators to specify additional JVM arguments to be applied to the JVM running the Jenkins agent.

JNLP Arguments

(empty)

For most administrators, this setting can be left empty. This setting allows administrators to specify JNLP arguments when launching the Jenkins agent.

Remote FS Root

/jenkins

Most administrators should leave this setting in its default state. This setting defines the working directory of the Jenkins agent inside the container.

Image

java

Most administrators will need to customize this configuration. This setting defines the Docker tag of the image to pull to serve as an agent container. The default image is the official Java Docker image, but most administrators will want to use a customized version of this image with their teams’ tooling needs installed. At a minimum, any custom containers must have a JDK installed, as this is a prerequisite to launch the Jenkins agent.

  • Additional Options

Field Default Value Description

Additional URI

(empty)

For most administrators, this advanced configuration can be left empty. This setting primarily enables administrators to make an image from their private Docker registry the agent image for their teams to run builds on by letting them specify a URI to an image in an internal Docker registry.

Environment Variable

(empty)

For most administrators, this advanced configuration can be left empty. This settings is where an administrator can add an environment variable for the Docker container created from this template’s specified image.

Force pull image

  • ❏  

For most administrators, this advanced configuration can be left unset. This setting forces an update of an image if it already exists locally. This option is useful when the specified image targets a mutable Docker tag (by convention) such as latest.

Launch in privileged mode

  • ❏  

For most administrators, this advanced configuration can be left unset. This setting launches the Docker container in privileged mode.

Parameter

(empty)

For most administrators, this advanced configuration can be left empty. This setting passes a parameter to the Docker container.

Port Mapping

(empty)

For most administrators, this advanced configuration can be left empty. This setting allows to map a port from the host to the Docker container.

Use a custom Docker shell command

/bin/sh

For most administrators, this advanced configuration can be left empty. This setting allows administrators to override the default /bin/sh shell command that is used to launch the Jenkins agent inside the container. This option can be used to execute commands before the Jenkins agent process is started.

Volume

(empty)

For most administrators, this advanced configuration can be left empty. This setting allows to map a volume inside the Docker container.

Sharing agent images between teams

Administrators can share agent images after creating them in Operations Center. Agent images created in Operations Center are then made available to connected masters located in the same folder hierarchy (same folder or a subfolder below it).

By default, agent images created during installation are located in the root of Operations Center, making them by default available to any connected master for use as a build agent.

Shared agent images can be browsed from any connected master within the special folder Operations Center Shared Templates.

operations center shared templates

Using private Docker registries

Administrators whose organizations are using a private Docker registry will need to give CloudBees Jenkins Enterprise credentials to that registry to allow CloudBees Jenkins Enterprise to leverage any agent images in it. To do this, the administrator will need to create a "credential package" and make this package accessible to all workers in the CloudBees Jenkins Enterprise cluster, such as in a shared network drive.

The administrator will need to first log into their Docker registry -

$ docker login some.docker.bar.com
  Username: foo
  Password:
  Email: foo@bar.com

Then create a tarball of the registry:

$ cd ~
$ tar czf docker.tar.gz .docker

Administrators should confirm that the .docker and .docker/config.json directors are in the tarball:

$ tar -tvf ~/docker.tar.gz

  drwx------ root/root         0 2015-07-28 02:54 .docker/
  -rw------- root/root       114 2015-07-28 01:31 .docker/config.json

Next, the administrator will need to upload this credential package to a location accessible to all workers in their cluster, such as an S3 bucket for Amazon-based installations of CloudBees Jenkins Enterprise.

Now in an agent image, administrators will need to configure the Additional URI entry with the URI to download the credential package and enable the Extract option.

additional uri