Appendix: Configuration reference

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 CI. For information on moving to CloudBees CI, please refer to Migrating from CloudBees Jenkins Enterprise 1.x to CloudBees CI 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.

CloudBees Jenkins Enterprise} Cluster configuration is achieved by customizing two text files: cluster-init.config and cluster-init.secrets. These are text files where customization values are stored in section-based name-value pairs. For example,

cluster-init.config
[tiger]
cluster_name = pse
controller_count = 3
...

Most of the attributes are common to all supported environments (AWS, OpenStack, etc…​). However, a small percentage of some of the attributes are environment-specific. While many of these attributes have reasonable default values, some need explicit initialization. There are use cases such as upgrading, managing workers, etc., which may require further customization of these files. Please refer to the following sections for more details.

Common configuration attributes

Table 1. [tiger] section
[tiger] Attribute Description

cluster_name

Name of the cluster (Required, default "pse")

This value is used to prefix resource names and tags when setting up servers and other infrastructure.

This value must contain only alphanumeric, dots, dashes and underscore values.

controller_count

Number of controllers (default 3)

Controllers manage coordination of the CloudBees Jenkins Enterprise resources. Include multiple controllers to ensure availability of the CloudBees Jenkins Enterprise cluster. When using multiple controllers always use an odd number of controllers.

master_worker_count

Number 'master' of workers (default 2)

CloudBees Jenkins Enterprise workload, for masters, Operations Center and CloudBees Jenkins Enterprise components, is handled by 'master' workers. To increase the initial capacity of your CloudBees Jenkins Enterprise cluster, increase this number. You can add more workers later with the worker-add operation. We recommend a minimum of two 'master' workers.

build_worker_count

Number of 'build' workers (default 1)

CloudBees Jenkins Enterprise workload for builds is handled by 'build' workers. To increase the initial build capacity of your CloudBees Jenkins Enterprise cluster, increase this number. You can add more workers later with the 'worker-add' operation.

register_script

Operating System Registration Script

If the operating system requires a registration (e.g. RHEL), provide here the path to script handling the registration. This script will be copied to machines and executed on init and upgrades and must succeed even if the machine is already registered.

Example of script content for RHEL:

#!/bin/bash
subscription-manager register --username <rhel_username> --password <rhel_password> --auto-attach --force

unregister_script

Operating System Unregistration Script

The unregister script is run on machine shutdown. It allows to free the registration if it part of a pool. Provide here the path to a script handling machine unregistration.

Example of script content for RHEL:

#!/bin/bash
subscription-manager unregister

docker_registry

Docker registry (default public)

Specify the registry used to obtain CloudBees Jenkins Enterprise images. To use the public Docker registry, use 'public'.

http_proxy

HTTP Proxy (optional)

If servers in the CloudBees Jenkins Enterprise cluster require a web proxy to access the Internet using the HTTP protocol, specify the full URL to the proxy server including the applicable port.

http_proxy=http://webproxy.example.com:8080

https_proxy

HTTPS Proxy (optional)

If servers in the CloudBees Jenkins Enterprise cluster require a web proxy to access the Internet using the HTTP protocol over SSL/TLS, specify the full URL to the proxy server including the applicable port.

https_proxy=https://webproxy.example.com:8443

no_proxy

No Proxy (optional)

This variable should contain a comma-separated list of domain extensions for which http_proxy and https_proxy should not be used.

no_proxy=.internal.example.com,.lab.example.com

If servers in the CloudBees Jenkins Enterprise cluster don’t have any public IP, they must be accessed through a SSH proxy. The following optional section allows to configure access to a SSH proxy.

Table 2. [sshproxy] section
[sshproxy] Attribute Description

user

SSH Proxy user name (optional)

Username to log in as on the ssh proxy.

host

SSH Proxy host name (optional)

Host of the ssh proxy.

port

SSH Proxy port (optional)

Port of the ssh proxy. Defaults to 22.

identity_file

SSH Proxy identity file (optional)

Path to a private key to be used to connect to the SSH proxy.

netcat_cmd

SSH Proxy Netcat command (optional)

GNU Netcat must be installed on the machine used as SSH proxy. This allows to provide a custom path to the netcat executable. Defaults to 'nc'.

Operations Center Configuration Attributes

Table 3. [cjoc] section
[cjoc] Attribute Description

memory

The container memory limit (default 1.5GB)

This value specifies the amount of memory allocated to the Operations Center container

jvm_options

The Operations Center application JVM options (default '-Xmx1024m')

This value specifies the options used by the Java Virtual Machine.

Note that if this value specifies the max heap usage of the JVM, it should be lower than the container memory limit

Docker Configuration Attributes

Table 4. [docker] section
[docker] Attribute Description

options

The Docker daemon options (default --log-driver=syslog)

This value sets the Docker daemon options. --log-driver=syslog should always be included to ensure logs are collected.

Common troubleshooting attributes

The following debug settings are for internal use only.
Table 5. [debug] section
[debug] Attribute Description

disable_castle

Disable castle (storage agent) (default no)

disable_elasticsearch

Disable elasticsearch (default no)

disable_cjoc = no

Disable Operations Center (default no)

enable_logstash

Enable logstash (default no)

Logstash may optionally be used to capture syslog events within the CloudBees Jenkins Enterprise cluster.

force_pull_image = false

Force docker image pulls for Marathon apps (default false)

Use this value to set forcePullImage for docker containers in the Marathon applications that support this setting.

enable_hello_app

Enable the hello app (default no)

The hello app is a trivial application that tests basic app deployment to CloudBees Jenkins Enterprise. When testing support for applications, you can set this to to yes, which will generate the hello and start it as a part of the Marathon application init. You can also manually start and stop the hello application from dna.

AWS-Specific Configuration Attributes

Table 6. [aws] section
[aws] Attribute Description

region

AWS region (required)

The region in which CloudBees Jenkins Enterprise will run. This must correspond to the AWS credentials specified above.

Use one of these values:

us-east-1
us-west-1
us-west-2
eu-west-1
eu-central-1
sa-east-1
ap-south-1
ap-southeast-1
ap-southeast-2
ap-northeast-1
ap-northeast-2

resource_tags

AWS resource tags

The tags will be added to all AWS created resources that support tags resource_tags is a comma delimited list of tags. The parameter format is: TAG1=VALUE1,TAG2=VALUE2,…​.

availability_zone

AWS availability zone.

The availability zone(s) where CloudBees Jenkins Enterprise will run, separated by comma.

The number of availability zones must be either 1, or 3 for fault tolerance. If not set it will pick a random one.

image_distribution

Operating system image distribution

CloudBees Jenkins Enterprise supports several operation system distribution: rhel, centos and ubuntu.

controller_instance_type

EC2 Instance type to use for controller servers (defaults to m4.large)

controller_volume_size

EC2 controller root volume size in GB (defaults to 200)

controller_volume_type

EC2 volume type to use for the controller server volume (defaults to gp2)

controller_ebs_optimized

Whether the instance is EBS-optimized (defaults to yes on all compatible instance types)

worker_instance_type

EC2 Instance type to use for worker servers (defaults to m4.xlarge)

worker_volume_size

EC2 worker root volume size in GB (defaults to 50)

worker_volume_type

EC2 volume type to use for the worker server volume (defaults to gp2)

worker_ebs_optimized

Whether the instance is EBS-optimized (defaults to yes on all compatible instance types)

worker_instance_profile

Instance profile of the worker (optional)

If set, launches the worker instance(s) with an IAM profile which will be used to grab the AWS credentials for worker operations.

storage_instance_type

EC2 Instance type to use for the storage server (defaults to m3.medium)

storage_volume_size

EC2 storage root volume size in GB (defaults to 50)

storage_volume_type

EC2 volume type to use for the storage server volume (defaults to gp2)

storage_ebs_optimized

Whether the instance is EBS-optimized (defaults to yes on all compatible instance types)

Cluster access restrictions

tiger_admin_port_access

Admin access from selected IPs (required)

Administrative ports are not accessible by default, but access can be granted to specific IPs and networks by using tiger_admin_port_access.

Ensure this property includes the installation machine IP, failing to do so will result in a failed installation.

In AWS or public clouds that would be your public facing IP. You can use Google by typing "what is my ip" to find public-facing IP.

In OpenStack or private clouds it would be the IP of the machine running the installation as seen by the VMs started in the cloud.

The property can contain one or more IP address ranges in CIDR notation separated by commas that are granted access to the administrative ports (for example: 192.0.2.0/24,198.51.100.1/32).

Use 0.0.0.0/0 to allow administrative connections from any IP, or 198.51.100.1/32 to allow access from only one IP (198.51.100.1).

Ports open for admin access include the ones for user access plus:

  • 22 SSH access to controllers and workers

tiger_user_port_access

User access from selected IPs (optional)

By default, applications are opened only to administrators.

By providing a value, you can restrict access to a particular set of IPs.

The property can contain one or more IP address ranges in CIDR notation separated by commas that are granted access to the administrative ports (for example: 192.0.2.0/24,198.51.100.1/32).

Ports open for user access include: * 80 http access * 443 https access (if enabled) * 2222 Jenkins SSH

VPC options

vpc_id

User-provided VPC ID (optional)

If set, CloudBees Jenkins Enterprise will create all resources within the given VPC. It is assumed that the given VPC ID is valid within the given account and region.

If unset, CloudBees Jenkins Enterprise will create a new VPC and create all resources inside it.

vpc_subnet_id

User-provided subnet ID (required if vpc_id is set)

If vpc_id above is set, it is mandatory to provide also the ID of a subnet defined inside the user-provided VPC and the availability zone it corresponds to, using the availability_zone parameter

The number of subnets must be either 1, or 3 (separated by comma) for fault tolerance.

Instances created by CloudBees Jenkins Enterprise will be launched on the provided subnet.

additional_security_group_id

User-provided security group ID

Only used if vpc_id above is defined. Adds an additional security group to all instances created in the cluster and to load balancers.

vpc_subnet

VPC subnet (default 10.16.0.0/16). Unused if vpc_id is set.

VPC and subnet CIDR block.

internal

Whether the cluster is internal only (defaults to no)

Allows to set up a CloudBees Jenkins Enterprise cluster with no public access (no public elb, no public ips) This can be enabled only if the vpc is user-provided (vpc_id and vpc_subnet_id provided above)

Table 7. [storage] section
[storage] Attribute Description

type

Storage type (default ebs if permissions allow, otherwise builtin-rsync)

CloudBees Jenkins Enterprise requires a means of backing up and restoring workspace state. The storage system can be configured with various back-end types.

Types supported:

builtin-rsync

Creates a storage server within the CloudBees Jenkins Enterprise cluster that is used to backup and restore workspace files using rsync.

nfs

Uses a mounted NFS volume to store workspace files

ebs

Uses AWS elastic block store (EBS) to store and snapshot workspace files

nfs_server

NFS server (only if type = nfs)

If using the nfs storage type, you must specify a server to use.

Specify the hostname or IP address of an NFS server that is accessible to the CloudBees Jenkins Enterprise cluster.

nfs_export_dir

NFS export directory

If using the nfs storage type, specify the exported directory on the NFS server (see nfs_server above) to use for storage.

Ensure that the directory is specified exactly as defined on the NFS server. The directory should start with a forward-slash (e.g. /var/myexport).

volume_user

Volume user (default jenkins)

Specify the user that will own the backed-up workspace files on the volume.

volume_group

Volume group (default jenkins)

Specify group that will own the backed-up workspace files on the volume.

Table 8. cluster-init.secrets.in template for AWS
Attribute Description

aws_access_key_id

AWS access key ID (required)

This is the access key ID from your AWS credentials. It must correspond to the value for secret_access_key below.

aws_secret_access_key

AWS secret access key (required)

This is the secret access key from your AWS credentials. It must correspond to the value for access_key_id (above).

aws_session_token

AWS session token (optional)

If using ephemeral credentials from Amazon STS, the session token can be supplied via this configuration option.

docker_registry_auth

Docker authorization (optional)

If using a Docker registry that requires authentication, specify the base 64 encoded auth string used by Docker here.

cjoc_username

CJOC username (optional - defaults to admin)

cjoc_password

CJOC password (optional - defaults to a generated random string)

OpenStack-Specific Attributes

Table 9. openstack section
[openstack] Attribute Description

tenant_name

OpenStack tenant name (required)

Example: tiger

auth_url

OpenStack identity service endpoint (required)

Example: http://CONTROLLER_HOST:5000/v2

image_name

Default image name for CloudBees Jenkins Enterprise servers (required)

Example: image_name = cloudbees-tiger-ubuntu-1.0

storage_image_name

Image name override for Storage node (optional)

If not specified, then the value specified in the attribute "openstack.image_name" is used

storage_instance_type

Flavor of the storage instance (default m1.small)

If intending to use builtin-rsync, then change this value to something appropriately larger.

controller_image_name

Image name override for Controller nodes (optional)

If not specified, then the value specified in the attribute "openstack.image_name" is used

controller_instance_type

Flavor of the controller instances (default m1.large)

worker_image_name

Image name override for Worker nodes (optional)

If not specified, then the value specified in the attribute "openstack.image_name" is used

worker_instance_type

Flavor of the worker instances (default m1.large)

network_name

Network name within which Tiger servers are created (required)

floatip_network_name

Name of network that houses floating IPs to be assigned to the controller instances so they are accessible from an external network, e.g., the Internet (optional)

This network name will be used to generate one or more floating IPs to expose VMs to the outside world. If not set, only private ips from "network_name" will be assigned and CloudBees Jenkins Enterprise may not be accessible from outside the cluster, depending on your network topology.

floatip_workers

Whether to give a floating ip to workers. (default no)

By default, workers are not exposed to the outside world. Set this to 'yes' to attach workers to the floating IPs network, just like controllers. It will allow to connect external jnlp agents to the masters within the cluster.

tiger_admin_port_access

Admin access from selected IPs (required)

Administrative ports are not accessible by default, but access can be granted to specific IPs and networks by using tiger_admin_port_access.

Ensure this property includes the installation machine IP, failing to do so will result in a failed installation.

In AWS or public clouds that would be your public facing IP. You can use Google by typing "what is my ip" to find public-facing IP.

In OpenStack or private clouds it would be the IP of the machine running the installation as seen by the VMs started in the cloud.

The property can contain one or more IP address ranges in CIDR notation separated by commas that are granted access to the administrative ports (for example, 192.0.2.0/24,198.51.100.1/32).

Use 0.0.0.0/0 to allow administrative connections from any IP, or 198.51.100.1/32 to allow access from only one IP (198.51.100.1).

Table 10. storage section
[storage] Attribute Description

type count

Storage type (default builtin-rsync) Number of storage servers (default 1)

CloudBees Jenkins Enterprise requires a means of backing up and restoring workspace state. The storage system can be configured with various back-end types.

Types supported:

Types supported:

builtin-rsync

Creates a storage server within the CloudBees Jenkins Enterprise cluster that is used to backup and restore workspace files using rsync.

nfs

Uses a mounted NFS volume to store workspace files

When using rsync with a built-in storage server, set count=1. When using another backend or a provided storage server, set count=0

nfs_server

NFS server (only if type = nfs)

If using the nfs storage type, you must specify a server to use.

Specify the hostname or IP address of an NFS server that is accessible to the CloudBees Jenkins Enterprise cluster.

nfs_export_dir

NFS export directory (only if type = nfs)

If using the nfs storage type, specify the exported directory on the NFS server (see nfs_server above) to use for storage.

Ensure that the directory is specified exactly as defined on the NFS server. The directory should start with a forward-slash (e.g. /var/myexport).

volume_user

Volume user (default jenkins)

Specify the user that will own the backed-up workspace files on the volume.

volume_group

Volume group (default jenkins)

Specify group that will own the backed-up workspace files on the volume.

Table 11. cluster-init.secrets.in template for OpenStack
Attribute Description

openstack_user_name

OpenStack username (required)

openstack_password

OpenStack password (required)

docker_registry_auth

Docker authorization (optional)

If using a Docker registry that requires authentication, specify the base 64 encoded auth string used by Docker here.

cjoc_username

CJOC username (optional - defaults to admin)

cjoc_password

CJOC password (optional - defaults to a generated random string)