CloudBees CoreCloudBees DevOpticsCloudBees FlowCloudBees AcceleratorCloudBees RolloutCloudBees Jenkins DistributionCloudBees Jenkins X DistributionCloudBees SDMCloudBees Jenkins PlatformCloudBees Jenkins EnterpriseCloudBees LexiconRelease notes
Introduction
What’s new
GKE Installation guide
EKS Installation guide
Upgrading CloudBees Jenkins X Distribution
Introduction
Creating quickstarts
Working with build packs
Creating a Spring Boot application
Importing projects
Using preview environments
Introduction
User Interface
Using Jenkins X Pipelines
Managing secrets
Software components
Jenkins X license report
Support policies
Want to learn more?
Sign up for the Jenkins X newsletter.

Upgrading CloudBees Jenkins X Distribution

One of the various benefits of deploying CloudBees Jenkins X Distribution in your cloud-based kubernetes development environments is the frequency of new releases, which contain new features, stability and usability improvements as well as bug fixes and security patches. CloudBees Jenkins X Distribution supports upgrades from v3 to the most current version.

Running the jx upgrade program

To upgrade CloudBees Jenkins X Distribution in your development environment:

  1. Download the most recent release of the jx binary and follow the same instructions for installing the current version on your operating system:

  2. Run the jx upgrade command at the terminal shell prompt:

    jx upgrade boot

  3. The upgrade program performs the following tasks:

    • The program clones the cloudbees-jenkins-x-versions repository to your local installation in ~/.jx/jenkins-x-versions overwriting the previous version.

    • Updates pipeline agent golang builder images from gcr.io.

    • A pull request is created in the remote development environment repository containing the changes to cloudbees-jenkins-x-boot-config, which upgrades your CloudBees Jenkins X Distribution configuration to support the latest version. The upgrade program displays the URL to the pull request.

      Your development environment repository was configured during the cluster installation process. For example, if you named your cluster acmecluster the dev environment repository would be called environment-acmecluster-dev in your remote Git host.

Editing the jx-requirements.yml file

The GitHub page showing the pull request allows you to see what files are changed during the upgrade process in the Files changed tab. Here is where you can preserve your custom cluster configuration fields to the changes when upgrading CloudBees Jenkins X Distribution.

  1. Find the jx-requirements.yml file. You can filter for it by clicking the File filter…​ dropdown and typing the filename.

  2. Under the cluster: configuration section, there are two particular lines that are in red, meaning they will be overwritten by the upgraded file lines in green. Copy the lines for each of the following into a temporary text file to preserve your cluster configuration:

    • clusterName: [NAME] (where [NAME] is your CloudBees Jenkins X Distribution cluster, for example clusterName: acmecluster). Highlight the line, copy and paste the text into your temporary text file (such as Notes or TextEdit on macOS or gedit on Linux) for later use.

    • environmentGitOwner: [ORGANIZATION_NAME] (where [ORGANIZATION_NAME] is the Git username of the organization you specified when you created your CloudBees Jenkins X Distribution cluster, for example environmentGitOwner: acmeorg). Highlight the line, copy and paste the text into your temporary text file (such as Notes or TextEdit on macOS or gedit on Linux) for later use.

    • The upgraded files may overwrite your storage buckets configured for your cluster as well, so ensure their status by checking the storage: section to see if any of your storage buckets links are in red, which would mean they will be overwritten in the PR merge. If they are, highlight the line(s), copy and paste the text into your temporary text file (such as Notes or TextEdit on macOS or gedit on Linux) for later use.

  3. Once you’ve copied all your custom cluster configuration, you can now open and edit the upgraded jx-requirements.yml file by clicking …​ on the top right of the header for that file in Github and choosing Edit File in the drop-down menu.

  4. Find the two lines clusterName: and environmentGitOwner: that you copied earlier in your temporary text file and paste them under the cluster: section.

  5. Find the storage bucket links that you copied earlier in your temporary text file and paste them under the storage: section.

  6. When you’re done click Save.

Editing the jenkins-x.yml file

The GitHub page showing the pull request allows you to see what files are changed during the upgrade process in the Files changed tab. Here is where you can preserve your custom cluster configuration fields to the changes when upgrading CloudBees Jenkins X Distribution.

  1. Find the jenkins-x.yml file. You can filter for it by clicking the File filter…​ dropdown and typing the filename.

    Under the environment: configuration section, there are two particular entries that are in red, meaning they will be overwritten by the upgraded file lines in green.

    To preserve your cluster configuration, highlight the line, copy and paste the text into a temporary text file (such as TextEdit on macOS or gedit on Linux) for later use.

    • The lines relating to GIT_AUTHOR_NAME, and the subsequent value: is the Git username of your your CloudBees Jenkins X Distribution development bot, for example:

      - name: GIT_AUTHOR_NAME
  value: acmebot

    • The lines relating to GIT_AUTHOR_EMAIL, and the subsequent value: is the Git email address for CloudBees Jenkins X Distribution related build information, for example:

      - name: GIT_AUTHOR_EMAIL
  value: devbot@acme.com

  2. Once you’ve copied all your custom cluster configuration, you can now open and edit the upgraded jenkins-x.yml file by clicking …​ on the top right of the header for that file in Github and choosing Edit File in the drop-down menu.

  3. Find the entries for GIT_AUTHOR_NAME: and GIT_AUTHOR_EMAIL: that you copied earlier in your temporary text file and paste them under the environment: section.

  4. In addition, you must add two new lines to ensure compatibility with the upgraded CloudBees Jenkins X Distribution environment: GIT_COMMITTER_NAME with the same value as GIT_AUTHOR_NAME and GIT_COMMITTER_EMAIL with the same value as GIT_AUTHOR_EMAIL. So, for example, with the additional lines, the configuration looks like:

    environment:
- name: GIT_AUTHOR_NAME
  value: acmebot
- name: GIT_AUTHOR_EMAIL
  value: devbot@acme.com
- name: GIT_COMMITTER_NAME
  value: acmebot
- name: GIT_COMMITTER_EMAIL
  value: devbot@acme.com

  5. When you’re done click Save.

Merging your CloudBees Jenkins X Distribution upgrade

When all files are saved for your cluster configuration, you can merge the changes to complete the CloudBees Jenkins X Distribution upgrade in GitHub by clicking Merge.