Install CloudBees CD/RO within Kubernetes

Getting started

The following items are important prerequisites for installing CloudBees CD/RO:

These instructions assume you are familiar with Kubernetes concepts and the tooling required for establishing a Kubernetes cluster. If you are not, review the Kubernetes documentation.
The Kubernetes version you are using must be supported. For supported versions, refer to Supported platforms for CloudBees CD/RO on Kubernetes.
Ensure you are able to satisfy the Kubernetes cluster and storage requirements.
If all of your Kubernetes nodes are tainted, you must have at least one untainted node to run the flow-server-init-job pod. If you create a new node or remove the taint from an existing one, you can delete or taint this node after installation is complete.

If you plan to use a lightweight Kubernetes implementation, such as minikube or kind, to install the CloudBees CD/RO demo locally in a non-production environment for testing purposes, it is possible. However, this type of integration may have serious security risks that could result in exposing your private data. If you accept these risks, and decide this type of integration meets your testing needs, CloudBees strongly advises:

Only to do so on a local machine in a non-production environment.
Not to publicly expose any service URLs.
Not to populate this environment with your private data.

Additionally, these types of integrations are not supported by CloudBees, and you must migrate to a Supported platforms for CloudBees CD/RO on Kubernetes to obtain a license for your production environment.

The following items are product details for installing CloudBees CD/RO:

For production environments, Helm charts are released for each CloudBees CD/RO version in SonaType Nexus. These charts contain the configurations for all components in a values.yaml at the top level of the package and a separate values.yaml for each component in the charts/<component-subdirectory>.
The values.yaml files released for a CloudBees CD/RO version include all available settings and their default values for each component. You may use these charts in project-specific values files by either replacing default values with your own or extracting only the subsets of configurations you need.
When configuring the default values.yaml for your project, CloudBees strongly suggests you save it in a project-specific myvalues.yaml under version control. This is to help avoid confusion with the default values.yaml, track updates, and compare changes between releases.
In production installations, you must configure an external database, which requires a CloudBees CD/RO enterprise license.

You can integrate CloudBees CD/RO with various Kubernetes platform-specific providers. Some platform-specific integrations, such as OpenShift, have requirements and prerequisites that must be met to correctly install, operate, and upgrade CloudBees CD/RO.

Some requirements must be made in CloudBees CD/RO server and agent values files, while others are made within the platform configuration prior to installing CloudBees CD/RO. For more information on platform-specific integrations, refer to Kubernetes platform-specific configurations.

Additionally, CloudBees CD/RO documentation includes numerous how-tos for Kubernetes project-specific configurations. For help with CloudBees CD/RO on Kubernetes project-specific configurations, refer to Kubernetes configuration options.

Install CloudBees CD/RO demo server

Before starting, ensure you have met the applicable requirements in Getting started.

The CloudBees CD/RO demo server is installed using cloudbees-flow Helm charts from YAML files available in the CloudBees examples repository. There are several platform versions of the demo available, each with demo included in the YAML file name.

The following CloudBees CD/RO components are included with the demo installation:

The CloudBees CD/RO server (flow-server)
The CloudBees CD/RO web server (flow-web)
The CloudBees Analytics server (flow-analytics)
The repository server (flow-repository)

A bound agent that is the local agent for the CloudBees CD/RO and repository servers (flow-bound-agent)

Bound agents are internal CloudBees CD/RO components

The CloudBees CD/RO bound agent (flow-bound-agent) is an internal component used specifically by CloudBees CD/RO for internal operations. While it is possible to schedule user jobs on bound agents, they are not intended for this purpose, and CloudBees CD/RO agents should be used instead.

If operations other than CloudBees CD/RO internal operations run bound agents, CloudBees CD/RO performance may become unpredictable. Additionally, system requirements for CloudBees CD/RO instances assume that bound agents are used exclusively by CloudBees CD/RO, and are not reliable for instances where user jobs are also running.

A NGINX Ingress Controller
A MariaDB database
- For production environments, you must configure your project-specific database. For more information, refer to Database migration requirement for production environment.

These components are installed as a single node CloudBees CD/RO cloudbees-flow server and allow you to experiment with many of CloudBees CD/RO’s features.

As described in Getting started, CloudBees does not support lightweight Kubernetes implementations. However, if you have decided this type of integration meets your testing needs, and want to install the demo for testing purposes in a non-production local environment, the following information may be helpful:

When installing the demo in a Docker container, ensure the Docker Container Resources are set high enough to support both your cluster running CloudBees CD/RO and Docker’s core functions.
The default cluster CPU and memory values for the Kubernetes implementation may not be sufficient to run all CloudBees CD/RO components. To test the demo with a minimal workload, the suggested minimum values are 4 CPUs and 12GB of memory.
Ensure you start your cluster using a Kubernetes version supported by CloudBees CD/RO. For supported versions, refer to Supported platforms for CloudBees CD/RO on Kubernetes.

To install the CloudBees CD/RO demo server in your Kubernetes cluster:

Download a copy of the cloudbees-cd-demo.yaml from the CloudBees examples repository.

There are several platform versions of the demo available, each with demo included in the YAML file name. If you use one other than cloudbees-cd-demo.yaml, use its file name as the helm install -f values file. If you make changes to the file, CloudBees recommends you save it as a project-specific myvalues.yaml to avoid confusion with the default chart.

Add the public CloudBees repository:

helm repo add cloudbees https://public-charts.artifacts.cloudbees.com/repository/public/
helm repo update▼

If you have not already done so, create a namespace in your cluster:
```
kubectl create ns <demoserver-namespace>▼
```
In v2024.06.0 or later values files, the dois and analytics workloads are both enabled by default. However, only the analytics workload is required by new installations.

To avoid unnecessary resource consumption caused by the dois workload, refer to Disable legacy CloudBees Analytics in Helm charts before installing CloudBees CD/RO.

Run the following Helm commands to install CloudBees CD/RO:

helm install <demoserver-releasename> cloudbees/cloudbees-flow \
      -f <path/to/cloudbees-cd-demo.yaml> \
      --namespace <demoserver-namespace> \
      --timeout 10000s▼

The installation may take several minutes. Once the pods are all running, you can track the progress of the CloudBees CD/RO server initialization, via the flow-server-init-job log in the Kubernetes dashboard. Once all pods are initialized, you can expose the CloudBees CD/RO server flow-web service URL and use your browser to experiment with CloudBees CD/RO.

Migrating from a non-production to production environment requires a CloudBees CD/RO enterprise license and separate database configuration.

Before you install CloudBees CD/RO production server

A cloudbees-flow Helm chart is released with each CloudBees CD/RO version. This chart includes the installation instructions and configurations for the following components:

The CloudBees CD/RO server (flow-server)
The CloudBees CD/RO web server (flow-web)
The CloudBees Analytics server (flow-analytics)
The repository server (flow-repository)

A bound agent that is the local agent for the CloudBees CD/RO and repository servers (flow-bound-agent)

Bound agents are internal CloudBees CD/RO components

The CloudBees CD/RO bound agent (flow-bound-agent) is an internal component used specifically by CloudBees CD/RO for internal operations. While it is possible to schedule user jobs on bound agents, they are not intended for this purpose, and CloudBees CD/RO agents should be used instead.

If operations other than CloudBees CD/RO internal operations run bound agents, CloudBees CD/RO performance may become unpredictable. Additionally, system requirements for CloudBees CD/RO instances assume that bound agents are used exclusively by CloudBees CD/RO, and are not reliable for instances where user jobs are also running.

A NGINX Ingress Controller
A Zookeeper ensemble
A MariaDB database
- For production environments, you must configure your project-specific database. For more information, refer to Database migration requirement for production environment.

Configure CloudBees CD/RO server values

A default values file (values.yaml) is released for each CloudBees CD/RO version that contains all default values for the CloudBees CD/RO server installation as part of the cloudbees-flow Helm chart. However, for production environments, there are many project-specific values that must be set in the cloudbees-flow Helm chart according to your project’s implementation.

Your project-specific values, which are only a subset of the default values, are normally set in a separate myvalues.yaml. This has the major advantage of reducing the amount of overall configuration you must track and maintain.

During installation, you can specify your project-specific myvalues.yaml when running helm install. Doing so, overwrites the default values in the values.yaml with the project-specific values in your myvalues.yaml, while still using the default values for items you did not customize.

CloudBees provides two ways to get started with your myvalues.yaml:

You can start with the values.yaml and extract only the project-specific parts you need. To get started, refer to Use the default values file to create your project-specific values file.
You can start with an example production values file and adapt it to fit your needs.To get started, refer to Use an example production values file to create your project-specific values file.

You can integrate CloudBees CD/RO with various Kubernetes platform-specific providers. Some platform-specific integrations, such as OpenShift, have requirements and prerequisites that must be met to correctly install, operate, and upgrade CloudBees CD/RO.

Some requirements must be made in CloudBees CD/RO server and agent values files, while others are made within the platform configuration prior to installing CloudBees CD/RO. For more information on platform-specific integrations, refer to Kubernetes platform-specific configurations.

Additionally, CloudBees CD/RO documentation includes numerous how-tos for Kubernetes project-specific configurations. For help with CloudBees CD/RO on Kubernetes project-specific configurations, refer to Kubernetes configuration options.

Use the default values file to create your project-specific values file

To get started using the values.yaml to create your myvalues.yaml chart:

Visit SonaType Nexus, find the latest release of cloudbees-flow, and download the package.
Open the package and, in the top-level of the directory, locate the values.yaml.

In the charts directory of the package, you can find charts for individual components within their subdirectory.
Save the file as a project-specific myvalues.yaml.

Go through your myvalues.yaml and update it to meet your project-specific needs. Specifically, configure your database, storage, license information, and CloudBees CD/RO credentials before installing it. For information on available configuration options, refer to cloudbees-flow chart configuration values.

By default, the values.yaml includes a built-in database for testing. However, for production environments, you must configure CloudBees CD/RO to connect with your project-specific database. For information on supported databases, refer to Supported platforms for CloudBees CD/RO on Kubernetes.

Using a project-specific database requires a CloudBees CD/RO enterprise license. To avoid installation errors, your CloudBees CD/RO server licence and database connections should both be configured in the same installation of the cloudbees-flow values chart in your project-specific myvalues.yaml. Failing to do so generates error messages about an unsupported configuration or a license requirement, depending on which is omitted.

To install CloudBees CD/RO with an existing database, refer to How to install CloudBees CD/RO on Kubernetes using an existing database.

If CloudBees CD/RO is initially installed with the built-in database, you can reconfigure it to use a separate database at any time. For more information on configuring CloudBees CD/RO to use your external database, refer to Configure CloudBees CD/RO to use an alternate database.

If your database connection fails, ensure the license is valid for CloudBees CD/RO, and the database configuration is correct. For information on configuring an external database for use by CloudBees CD/RO, refer to Configure an external database

In v2024.06.0 or later values files, the dois and analytics workloads are both enabled by default. However, only the analytics workload is required by new installations.

To avoid unneeded resource consumption caused by the dois workload, refer to Disable legacy CloudBees Analytics in Helm charts before installing CloudBees CD/RO.
(Optional) If you are using a multi-node deployment for the CloudBees Analytics server, a common node certificate infrastructure is required. Refer to Configure CloudBees Analytics server certificates to learn how to configure common node certificate infrastructure in your project-specific values file.
(Optional) Place your myvalues.yaml under version control. CloudBees strongly suggests you do this to track updates and compare changes between releases.

(Optional) Any configurations not specified in your myvalues.yaml are automatically taken from the values.yaml during installation. This means, you can also delete any configuration options in your myvalues.yaml that are not specifically required by your project. This helps to reduce the overall configurations maintained in this file.

While deleting unneeded configuration options, ensure you maintain valid tag nesting and syntax. Failing to do so may cause your installation to fail or produce unpredictable behavior on your platform.

After you have configured your myvalues.yaml, refer to Install CloudBees CD/RO production server.

Use an example production values file to create your project-specific values file

Preconfigured production Helm chart examples are available in the CloudBees examples repository to get you started. These files include:

Values file Description

Values file	Description
`cloudbees-cd-prod.yaml`	File for use with production installations. You must configure your database, storage, and CloudBees CD/RO credentials in a local project-specific values file before it can be used. For information on available configuration options, refer to cloudbees-flow chart configuration values.
`cloudbees-cd-defaults.yaml`	File listing all Helm chart values along and their default value. Use as a reference when specifying additional configurations in your local project-specific values file. For information on available configuration options, refer to cloudbees-flow chart configuration values.

cloudbees-cd-prod.yaml

File for use with production installations. You must configure your database, storage, and CloudBees CD/RO credentials in a local project-specific values file before it can be used. For information on available configuration options, refer to cloudbees-flow chart configuration values.

cloudbees-cd-defaults.yaml

File listing all Helm chart values along and their default value. Use as a reference when specifying additional configurations in your local project-specific values file. For information on available configuration options, refer to cloudbees-flow chart configuration values.

There are several platform versions of the production example Helm charts available in the CloudBees examples repository, each with prod in the YAML file name.

To create your myvalues.yaml based on the example production chart:

Go to the CloudBees examples repository and save a copy of the example production chart you want to use as your project-specific myvalues.yaml.

Go through your myvalues.yaml and update it to meet your project-specific needs. Specifically, configure your database, storage, license information, and CloudBees CD/RO credentials before installing it. For information on available configuration options, refer to cloudbees-flow chart configuration values.

By default, the values.yaml includes a built-in database for testing. However, for production environments, you must configure CloudBees CD/RO to connect with your project-specific database. For information on supported databases, refer to Supported platforms for CloudBees CD/RO on Kubernetes.

Using a project-specific database requires a CloudBees CD/RO enterprise license. To avoid installation errors, your CloudBees CD/RO server licence and database connections should both be configured in the same installation of the cloudbees-flow values chart in your project-specific myvalues.yaml. Failing to do so generates error messages about an unsupported configuration or a license requirement, depending on which is omitted.

To install CloudBees CD/RO with an existing database, refer to How to install CloudBees CD/RO on Kubernetes using an existing database.

If CloudBees CD/RO is initially installed with the built-in database, you can reconfigure it to use a separate database at any time. For more information on configuring CloudBees CD/RO to use your external database, refer to Configure CloudBees CD/RO to use an alternate database.

If your database connection fails, ensure the license is valid for CloudBees CD/RO, and the database configuration is correct. For information on configuring an external database for use by CloudBees CD/RO, refer to Configure an external database

In v2024.06.0 or later values files, the dois and analytics workloads are both enabled by default. However, only the analytics workload is required by new installations.

To avoid unneeded resource consumption caused by the dois workload, refer to Disable legacy CloudBees Analytics in Helm charts before installing CloudBees CD/RO.
(Optional) If you are using a multi-node deployment for the CloudBees Analytics server, a common node certificate infrastructure is required. Refer to Configure CloudBees Analytics server certificates to learn how to configure common node certificate infrastructure in your project-specific values file.
(Optional) Place your myvalues.yaml under version control. CloudBees strongly suggests you do this to track updates and compare changes between releases.

After you have configured your myvalues.yaml, refer to Install CloudBees CD/RO production server.

For more information on options to configure your project-specific Helm chart, refer to Configure Helm charts.

Install CloudBees CD/RO production server

Before starting, ensure you have met the applicable requirements in Getting started.

To install a CloudBees CD/RO production server:

Configure your myvalues.yaml file for your CloudBees CD/RO production server. For more information on configuring your myvalues.yaml, refer to Configure CloudBees CD/RO server values.

Add the public CloudBees repository:

helm repo add cloudbees https://public-charts.artifacts.cloudbees.com/repository/public/
helm repo update▼

If you have not already done so, create a namespace in your cluster:
```
kubectl create ns <production-server-namespace>▼
```
Run the following Helm command to install CloudBees CD/RO:
```
helm install <production-server-releasename> cloudbees/cloudbees-flow \
      -f <production-server-myvalues.yaml> \
      --namespace <production-server-namespace> \
      --timeout 10000s▼
```
If you are installing a CloudBees CD/RO instance with an external database, do not use the --wait option. The flow-server-init-job cannot be started if --wait is used.

The installation may take several minutes. Once the pods are all running, you can track the progress of the CloudBees CD/RO server initialization, via the flow-server-init-job log in the Kubernetes dashboard. Once all pods are initialized, you can expose the CloudBees CD/RO services URLs in your environment and begin working with CloudBees CD/RO.

Update CloudBees CD/RO production servers

If you want to make changes to the project-specific server:

Make any changes and save them in your project-specific myvalues.yaml.

Run:

helm upgrade <production-server-releasename> cloudbees/cloudbees-flow \
      -f <production-server-myvalues.yaml> \
      --namespace <production-server-namespace> \
      --timeout 10000s▼

The installation may take several minutes. Once the pods are all running, you can track the progress of the CloudBees CD/RO server initialization, via the flow-server-init-job log in the Kubernetes dashboard. Once all pods are initialized, you can expose the CloudBees CD/RO services URLs in your environment and begin working with CloudBees CD/RO.

Configure CloudBees Analytics server certificates

CloudBees CD/RO uses transport layer security (TLS) encryption and certificates to protect data between nodes on the CloudBees Analytics server. Required certificates are generated automatically for single node deployments. You must specify the common node certificate infrastructure for multi-node deployments by defining pre-generated certificates before installation.

CloudBees recommends that you specify certificates by generating a key store containing a root certificate authority (CA) certificate, an intermediate CA signing certificate, and its private key. With this method, all additional required certificates are automatically generated.

CloudBees CD/RO v2023.12.0 certificate requirements

In v2023.12.0, CloudBees CD/RO transitioned to using OpenSSL 3. If you upgrade to v2023.12.0 and previously used either:

Custom certificates generated with OpenSSL 2 or earlier.

or:
Certificates generated using v2023.10.0 or earlier cbflow-tools.

You must regenerate your certificates using OpenSSL 3 or later, or v2023.12.0 cbflow-tools, to successfully upgrade to v2023.12.0.

Use the cbflow-tools image and the following command to create the key store:

docker run --rm cloudbees/cbflow-tools:<docker tag> generate-certificates▼

This command returns the key store in base64 format. You must set this string as the value of the analytics.certificates.bundle property in your local values file.

You can also create a secret key with the corresponding data. Use the following command to create a cbcd-analytics-certificates secret key:

kubectl create secret generic cbcd-analytics-certificates \
      --from-literal=CBF_ANALYTICS_CRT_BUNDLE=$(docker run \
      --rm cloudbees/cbflow-tools:<docker tag> generate-certificates)▼

You can specify this secret key in the value of the analytics.certificates.existingSecret property in your local values file, or as a parameter for the installation command.

--set analytics.certificates.existingSecret=cbcd-analytics-certificates▼

If the recommended configuration is not suitable for your environment, CloudBees CD/RO also supports the following alternative certificate sets:

A root CA certificate and its private key
A root CA certificate, an intermediate CA signing certificate, and its private key
A root CA certificate, an intermediate CA signing certificate, and node and administrative certificates with their private keys

You must check the corresponding comments in the values file for the corresponding properties.

Disable legacy CloudBees Analytics in Helm charts

In CloudBees CD/RO v2024.06.0, CloudBees updated the CloudBees Analytics server from using Elasticsearch to OpenSearch. To prevent unintentional data loss for existing users updating to v2024.06.0 or later, both the legacy CloudBees Analytics using Elasticsearch (dois in Helm charts) and CloudBees Analytics using OpenSearch (analytics in Helm charts) are enabled by default.

If you are upgrading from a previous version of CloudBees CD/RO to v2024.06.0 or later, do not follow the steps in this section. Following these steps for an upgrade could result in permanent data loss.

Instead, refer to Upgrade Kubernetes CloudBees Analytics environments to OpenSearch.

However, if this is your initial installation of CloudBees CD/RO, CloudBees strongly recommends disabling the dois Helm chart in your values file before installation. Disabling it will not cause adverse impacts on your environment and avoids unneeded resource consumption in your environment.

If you do not disable the dois Helm chart, this unused parallel service is automatically created when you install CloudBees CD/RO, and consumes resources in your environment.

If you do not disable it on the initial installation, CloudBees strongly recommends to update your values file to disable the dois Helm chart and updating your environment. To update your environment in such cases, refer to Update CloudBees CD/RO production servers.

To disable dois in your values file:

Open your values file, and search for:

Analytics server / Flow DevOps Insight (DOIS/dois) configuration section▼

Once you have located the section, configure dois.enabled: false.

Example to disable dois

### --------------------------------------------
### (LEGACY) Flow DevOps Insight (DOIS/dois) configuration section
### ---------------------------------------------

dois:

  ## Flag that dictates the cbflow-dois workload and its accompanying services are installed.
  enabled: false▼

It is critical to set dois.enabled: false instead of removing the entire dois chart. This ensures this value is not overwritten by default values in the CloudBees CD/RO values file.

(OPTIONAL) To avoid maintaining unnecessary configurations in your values file, delete the remaining dois values after dois.enbabled: false.
1. If you delete the remaining dois values, ensure your values file is valid with proper indentation and no unnested values.
Save your values file.

The dois workload is not created in your deployment, and you can now continue with your CloudBees CD/RO installation.

Install and update CloudBees CD/RO agents

The following instructions describe how to install CloudBees CD/RO agent(s) only. Before you start, you must already have the CloudBees CD/RO server installed in your cluster. If you need to install the CloudBees CD/RO server, refer to CloudBees CD/RO server installation and upgrade before proceeding with the agent installation. Once you have the CloudBees CD/RO server installed, you may install multiple agents and configure them to fit your needs.

You can integrate CloudBees CD/RO with various Kubernetes platform-specific providers. Some platform-specific integrations, such as OpenShift, have requirements and prerequisites that must be met to correctly install, operate, and upgrade CloudBees CD/RO.

Some requirements must be made in CloudBees CD/RO server and agent values files, while others are made within the platform configuration prior to installing CloudBees CD/RO. For more information on platform-specific integrations, refer to Kubernetes platform-specific configurations.

Additionally, CloudBees CD/RO documentation includes numerous how-tos for Kubernetes project-specific configurations. For help with CloudBees CD/RO on Kubernetes project-specific configurations, refer to Kubernetes configuration options.

Configure CloudBees CD/RO agent values

A cloudbees-flow-agent Helm chart is released for each CloudBees CD/RO version and may be used as a starting point for installation. For production environments, there are many project-specific values that may need to be changed in the cloudbees-flow-agent Helm chart to meet the needs of your project’s implementation. You can specify your own project-specific myvalues.yaml for your agent when running helm install.

If you are installing your CloudBees CD/RO agents in a different namespace than your CloudBees CD/RO server, refer to Install CloudBees CD/RO agents in different namespaces.

To create your custom myvalues.yaml chart:

Go to SonaType Nexus, find the latest release cloudbees-flow, and download the package.
Open the package, navigate to charts/cloudbees-flow-agent, and locate the values.yaml.

In the charts directory of the package, you can find individual charts for other components.
Save the file as a project-specific myvalues.yaml

Go through your myvalues.yaml and update it to meet your project-specific needs.

If you are configuring multiple replicas in your values file using the replicas value, ensure your resourceName template is correctly defined so all replicas are registered properly. For more information, refer to How to configure agent resource name templates.

(Optional) Place your myvalues.yaml under version control. This is strongly suggested to track updates and compare changes between releases.

Configure agent third-party tools

CloudBees CD/RO agents often need, use, or access third-party tools to accomplish tasks. In traditional deployments, these tools are installed directly on the agent machine. However, for agents running in a Kubernetes cluster, third-party tools can be deployed in agent containers, so they are immediately accessible by the agent.

For CloudBees CD/RO v2023.03.0 and later, CloudBees supplies cbflow-agent images with specific third-party tools preinstalled. The following tools are currently included with cbflow-agent images:

Helm v3.15.0 (Apache 2.0 license)
kubectl v1.30.1 (Apache 2.0 license)
kubectl-argo-rollout plugin v1.7.0-rc1 for Argo Rollouts (Apache 2.0 license)

Once you have the cbflow-agent image installed, these tools can be found in /opt/cbflow/third-party/bin and are available via the PATH variable.

Configuring additional agent third-party tools is typically done by one of the following options:

Install a project-specific agent image
Install third-party tools from scripts
Install third-party tools using PVCs
Install third-party tools using NFS server mounts

Install a project-specific agent image

For installations with third-party tools that are well-defined and static, you may choose to use the CloudBees CD/RO agent image as the base image and create your own container with the desired third-party tools added.

CloudBees CD/RO agent images come with microdnf package manager preinstalled.

Below is an example Dockerfile configuring the custom container using microdnf:

FROM cloudbees/cbflow-agent:<agent-image-tag>

USER root
RUN microdnf --assumeyes install vim iproute net-tools iputils && microdnf clean all
RUN curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl && \
    chmod +x ./kubectl && \
    mv ./kubectl /usr/local/bin
USER cbflow▼

Install third-party tools from scripts

CloudBees CD/RO agents are not installed as a root user. Not all Kubernetes installations allow you to change the agent’s access to root. This may prevent your project-specific installation from using this option to install third-party tools.

For installations needing a more flexible method where the set of tools may vary, you may use the helm command option --set-file to load your installation script into the container using the customScript key.

CloudBees CD/RO agent images come with microdnf package manager preinstalled.

For instance, the example below contains commands to install multiple tools in the pod using the microdnf package manager.

#!/bin/sh
microdnf --assumeyes install vim iproute net-tools iputils && \
microdnf clean all && curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl && \
chmod +x ./kubectl && \
mv ./kubectl /usr/local/bin▼

To reference your script’s file when running helm install or helm upgrade, use set-file with the customScript directive:

--set-file customScript=<customScript-file>▼

By default, agents do not run as root. To allow your agent to run custom scripts that require root access, such as package installers, you must set the Helm security context:

--set securityContext.enabled=true --set securityContext.runAsUser="0"▼

Install third-party tools using PVCs

You can install CloudBees CD/RO agent third-party tools by installing tool binaries in a PVC and adding the PVC mount to your agent values file. To do so:

Create a PVC using a NFS or standard storage class:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: <your-pvc-name>
spec:
  accessModes:
    - <accessMode either ReadWriteMany or ReadWriteOnce>
  resources:
    requests:
      storage: <your-storage-size>
  storageClassName: <your-storage-class>▼

Example PersistentVolumeClaim

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: flow-agent-external-tools
spec:
  accessModes:
    - "ReadWriteOnce"
  resources:
    requests:
      storage: 1Gi
  storageClassName: standard▼

Install your third-party tools into the PVC.

Example PVC tools install

apiVersion: v1
kind: ConfigMap
metadata:
  name: install-tools-script
data:
  # file-like keys
  install-tools.sh: |
    #!/bin/bash
    mkdir -p /opt/tools/
    apt update && apt install wget curl -y && curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 && \
     chmod 700 get_helm.sh && ./get_helm.sh
    mv /usr/local/bin/helm /opt/tools/helm
    curl -LO https://dl.k8s.io/release/v1.23.0/bin/linux/amd64/kubectl && mv ./kubectl /opt/tools/ && chmod a+x /opt/tools/kubectl
    apt install git -y
    mv /usr/bin/git /opt/tools/git
    wget https://mirrors.estointernet.in/apache/maven/maven-3/3.6.3/binaries/apache-maven-3.6.3-bin.tar.gz
    tar -xvf apache-maven-3.6.3-bin.tar.gz
    mv apache-maven-3.6.3 /opt/tools/

---
apiVersion: batch/v1
kind: Job
metadata:
  name: agent-tools
spec:
  template:
    spec:
      restartPolicy: Never
      volumes:
      - name: agent-tools
        persistentVolumeClaim:
          claimName: flow-agent-external-tools
      - name: install-tools-script
        configMap:
          name: install-tools-script
          defaultMode: 0744
      containers:
      - name: tools-installed
        image: "debian:latest"
        command: ["/bin/bash", "-c", "/opt/install-tools.sh"]
        volumeMounts:
        - name: agent-tools
          mountPath: /opt/tools
        - name: install-tools-script
          mountPath: /opt/install-tools.sh
          subPath: install-tools.sh▼

Apply the PVC to your namespace:

kubectl apply -f pvc.yaml -n $NAMESPACE▼

Add the PVC in your agent values file.

Example agent values file

additionalVolumes:
  - name: agent-tools
    persistentVolumeClaim:
      claimName: flow-agent-external-tools

additionalVolumeMounts:
  - name: agent-tools
    mountPath: /opt/tools▼

Install or upgrade your agent values file. Refer to Install CloudBees CD/RO agent or Update CloudBees CD/RO agent as needed.

After you install or upgrade your agent values file, you can access the tools on your agent using /opt/tools/ (or path you specified) or by adding the path as an environmental variable.

Install third-party tools using NFS server mounts

You can install CloudBees CD/RO agent third-party tools by installing tool binaries on a NFS server and adding the NFS server mount to your agent values file. To do so:

If you haven’t already done so, install any required tools on your NFS server.

Add the NFS server mount in your agent values file.

Example agent values file with NFS server mount

additionalVolumes:
  - name: agent-tools-nfs-vol
    nfs:
      server: <your-nfs-server-host>
      path: <your-tools-nfs-path>
additionalVolumeMounts:
  - name: agent-tools-nfs-vol
    mountPath: /opt/tools▼

Ensure your tools are installed on <your-nfs-server-host> in <your-tools-nfs-path> you add to the values file.

Install or upgrade your agent values file. Refer to Install CloudBees CD/RO agent or Update CloudBees CD/RO agent as needed.

After you install or upgrade your agent values file, you can access the tools on your agent using /opt/tools/ (or path you specified) or by adding the path as an environmental variable.

Install CloudBees CD/RO agents in different namespaces

By default, CloudBees CD/RO agents are configured to use the flow-server and flow-repository services in the same Kubernetes namespace. However, CloudBees CD/RO agents can also be installed in different namespaces and configured to communicate with these services across namespaces using their DNS name.

You must have the flow-server and flow-repository installed in your cluster to complete the following steps. If you do not already have them installed, refer to Install CloudBees CD/RO production server.

To configure the DNS name of your flow-server:

From the CloudBees CD/RO main menu, select Administration Server Settings System Settings.

In the Server IP address field, provide the DNS name for your flow-server service in the format flow-server.server-namespace. The server-namespace must match the namespace where your CloudBees CD/RO server is installed.

If you change the flow-server namespace in a future deployment, ensure you update the Server IP address field to reflect the new namespace. Failing to do so will cause unexpected communication issues between your server and agent(s).

To configure the DNS name of your flow-repository:

From the CloudBees CD/RO main menu, select DevOps Essentials Artifact Management Repositories.

Select the desired repository. In the URL field and provide the DNS name for your flow-repository in the format flow-repository.repository-namespace. The repository-namespace must match the namespace where your CloudBees CD/RO repository is installed.

If you change the flow-repository namespace in a future deployment, ensure you update the URL field to reflect the new namespace. Failing to do so will cause unexpected communication issues between your repository and agent(s).

Once you have configured the server and repository DSN names:

Configure the serverEndpoint in your agent’s values file with the server DSN name. For more information on configuring an agent server endpoint, refer to cloudbees-flow-agent chart configuration values.

After configuring your agent’s values file, to register it as a resource with the CloudBees CD/RO server, install or update your agent’s values file in your cluster. Refer to Install CloudBees CD/RO agent or Update CloudBees CD/RO agent.

For agents that are already installed, changes are not applied until you run helm upgrade to update your cloudbees-flow-agent Helm chart. Once the server is able to communicate with the agent, a resource is automatically created for the agent.

If you attempted to manually create a resource for your agent that was previously unable to connect to the server:

If the agent’s name in your values file is the same as the name used for the manually created resource, after you run helm upgrade, the manually created resource is automatically updated based on the new values.
If you do not use the same name in your values file as you did when manually creating the resource, after you run helm upgrade, a new resource is created, and you can remove your manually created resource.

Install CloudBees CD/RO agent

Before you start:

Your agent(s) are installed in the same namespace as the CloudBees CD/RO server, so you must already have the CloudBees CD/RO server installed in your cluster before proceeding. If you need to install the CloudBees CD/RO server, refer to Install CloudBees CD/RO production server. The following commands refer to this namespace file as <production-server-namespace>.
Agents may need project-specific values set in the cloudbees-flow-agent Helm chart before installation. If you have not already done so, refer to Configure CloudBees CD/RO agent values. The following commands refer to this values file as <production-agent-myvalues.yaml>.
Agents may need project-specific third-party tools to accomplish the intended tasks they are installed to do, refer to Configure agent third-party tools. These tools may be included as a container in your cluster or dynamically loaded when you install the agent (--set-file customScript). The following command examples include the [--set-file customScript=<customScript>] option, but you can omit it if it doesn’t apply to your installation.

To get started installing the agent:

Ensure the CloudBees repo is up-to-date:
```
helm repo update▼
```

Ensure you have the correct namespace for the CloudBees CD/RO server. You can get the current namespaces by running:

kubectl get namespace▼

In the following command, the namespace is referenced as <production-server-namespace>. You must install the agent in the same namespace as the CloudBees CD/RO server instance where you want to connect.

Once you have your project-specific values file and have confirmed the CloudBees CD/RO server namespace, to install the agent run:

helm install <agentReleaseName> cloudbees/cloudbees-flow-agent \
      -f <production-agent-myvalues.yaml> \
      --namespace <production-server-namespace> \
      --timeout 10000s \
# Optional if you need to add or update third-party tools:
      --set-file customScript=<customScript-file>▼

The installation takes several minutes. Once the pods are all running, you can track the progress of the CloudBees CD/RO agent initialization, via the Kubernetes dashboard. Once all pods have been initialized, you can begin working with the CloudBees CD/RO agent.

Update CloudBees CD/RO agent

If you want to make changes to the project-specific agent:

Make any changes and save them in your project-specific myvalues.yaml.

Run:

helm upgrade <agentReleaseName> cloudbees/cloudbees-flow-agent \
      -f <production-agent-myvalues.yaml> \
      --namespace <production-server-namespace> \
      --timeout 10000s \
# Optional if you need to add or update third-party tools:
      --set-file customScript=<customScript-file>▼

The installation takes several minutes. Once the pods are all running, you can track the progress of the CloudBees CD/RO agent initialization, via the Kubernetes dashboard. Once all pods have been initialization, you can begin working with the CloudBees CD/RO agent.