CloudBees Core on modern cloud platforms upgrade guide


This guide describes the upgrade process for CloudBees Core on Kubernetes installations.

Caution
Helm is the preferred method of managing CloudBees Core. CloudBees provides a Helm Chart for CloudBees Core, and recommends migrating existing installations to use the Helm Chart. For instructions on how to migrate your non-Helm installation to Helm, see Migrating existing Kubernetes CloudBees Core installations to Helm.

Upgrading using Helm

Note
You can only use Helm to upgrade your CloudBees Core instance if you’re already using Helm to manage the instance. If you need to migrate a CloudBees Core instance that wasn’t installed using Helm, we provide instructions in Migrating existing Core installations to Helm.

One of the most useful features of Helm is a streamlined upgrade and update process for your CloudBees Core installation.

The helm upgrade command allows you to upgrade your CloudBees Core release. This can be new setting, such as an updated OperationCenter.HostName value or a new version of CloudBees Core.

Helm Issue 2948 and NGINX Ingress controller support

If you are using the NGINX installation option, you MUST set the nginx-ingress.Enabled=true value or the NGINX Controller will be deleted. CloudBees strongly recommends you use a Custom Values file.

For more details around Helm Issue 2948, see Helm Issue 2948 on GitHub.

Using a custom values file to upgrade CloudBees Core

CloudBees recommends using a Custom Values File to upgrade CloudBees Core using Helm. For more information on custom values files, see GitOps and custom values files.

To upgrade your installation using a custom values file:

$ helm upgrade -f example-values.yaml --dry-run --debug (1) (2)
  1. Run the helm upgrade command with the -f argument to use the examples-value.yaml file. Replace the examples-value.yaml filename with the name of your values file.

  2. Adding the --dry-run --debug runs a dry run of the installation without making changes.

The following example upgrade custom values file is based on examples in the cloudbees-examples GitHub repository.

# A helm example values file for standard Kubernetes install.
# An nginx-ingress controller is not installed and ssl isn't installed.
# Install an nginx-ingress controller
nginx-ingress:
  Enabled: false <1>

OperationsCenter:
  # Set the HostName for the Operation Center
  HostName: 'cloudbees-core.example.com' <2>
  Ingress:
    tls:
    ## Set this to true in order to enable TLS on the ingress record
      Enable: false <3>
      SecretName: core-example-com-tls
      Host: jenkins.cluster.local
  1. If you want NGINX Ingress controller installed, change this value to true.

  2. Replace cloudbees-core.example.com with your domain name.

  3. If you want to enable TLS, set this value to true. See Performing an install with HTTPS support.

Upgrading without Helm

Before you upgrade

  1. The CloudBees Core YAML has changed, because it is now generated from the CloudBees Core Helm Chart. Both the format and the order of the file have changed. If you intend to use the YAML file as your basis for the upgrade (instead of Helm), you must manually update the field values in cloudbees-core.yml to match the values in your previous installation.

  2. As a best practice, CloudBees recommends backing up your Operations Center and JENKINS_HOME prior to upgrading. For more information, see the Backup and Restore guide.

Performing the upgrade

Note
If you previously attempted to upgrade CloudBees Core and got an error message reading The StatefulSet "cjoc" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', and 'updateStrategy' are forbidden, follow this upgrade process to resolve the issue.

To upgrade CloudBees Core:

  1. Download the installer from the Downloads site.

  2. In a local directory on your workstation, unpack the installer:

    $ tar xvf name-of-installer.tgz
  3. Modify the extracted cloudbees-core.yml to match the values of your previous installation. There are two options for this step:

    1. Use Helm to create a custom YAML file for your installation, or

    2. Manually edit cloudbees-core.yml values to match the values from the previous installation (IMPORTANT: the YAML file format has changed).

  4. Delete the cjoc statefulset (this does not remove the associated volume or data):

    $ kubectl delete sts cjoc
  5. Confirm that the CJOC statefulset has been deleted:

    $ kubectl get sts cjoc
    Error from server (NotFound): statefulsets.apps "cjoc" not found (1)
    1. This error confirms that the cjoc statefulset has been deleted.

  6. Run the installer:

    $ kubectl apply -f cloudbees-core.yml
  7. Check the status of the Operations Center roll-out:

    $ kubectl rollout status sts cjoc
  8. Once the new Operations Center version has been rolled out, log into Operations Center and upgrade your Managed Masters.