Migrating from Jenkins LTS to CloudBees Jenkins Distribution


On this page

This topic covers migration from Jenkins LTS to CloudBees Jenkins Distribution.

CloudBees Jenkins Distribution, similar to Jenkins, can run as a stand-alone Java process inside a Java servlet container engine (like Jetty) or as a Docker container.

Regardless of the configuration, please ensure that the machine running CloudBees Jenkins Distribution meets the system requirements before continuing.

Note
These instructions assume that the version of your Jenkins instance matches that of a recent LTS. CloudBees Jenkins Distribution is based upon the Jenkins LTS: for example, CloudBees Jenkins Distribution <version> is based on Jenkins <version> (and is therefore considered a relatively straightforward upgrade).

If your Jenkins version is one of the "weekly" releases, or a Jenkins LTS version older than 2.150.2, please contact CloudBees Support for an Assisted Update.

An important note about users

Important
The user that runs Jenkins is CHANGING to cloudbees-jenkins-distribution.

It is very important that:

  1. The cloudbees-jenkins-distribution user exists on your system.

  2. The cloudbees-jenkins-distribution user has the appropriate privileges to run Jenkins.

  3. The cloudbees-jenkins-distribution user is running in a secure manner to prevent privilege-escalation exploits.

If you have questions about setting up the cloudbees-jenkins-distribution user, please contact CloudBees Support

Linux

When upgrading from Jenkins on Linux, this guide assumes that the current Jenkins instance is using the Jenkins project’s official Linux (rpm or deb) packages, and that the CloudBees Jenkins Distribution instance that is being upgraded also uses Linux packages.

These instructions also assume that the home directory (commonly referred to as JENKINS_HOME in configuration scripts and documentation) is /var/lib/jenkins.

Red Hat Enterprise Linux / CentOS

To migrate from Jenkins to CloudBees Jenkins Distribution on Red Hat Enterprise Linux or CentOS systems, follow these instructions.

Remove the previously installed jenkins package

Replace the previously installed jenkins package with the cloudbees-jenkins-distribution package:

shell% yum remove jenkins (1)
shell% ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed jenkins package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for Red Hat Enterprise Linux / CentOS

Administrators running Red Hat-based distributions, such as Red Hat Enterprise Linux, Fedora, Oracle Linux, and CentOS, first need to set up the RPM repository for CloudBees Jenkins Distribution and import the key.

  1. Set up the RPM repository:

    sudo wget -O /etc/yum.repos.d/cloudbees-jenkins-distribution.repo https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees-jenkins-distribution.repo
  2. Import the CloudBees key:

    sudo rpm --import https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/rpm/cloudbees.com.key
    Note
    If the CloudBees key has already been imported on the machine, the rpm --import command will fail. This error can be safely ignored.
  3. Once the repository and key have been set up, CloudBees Jenkins Distribution can be installed with yum via:

    sudo yum install cloudbees-jenkins-distribution
  4. Set the cloudbees-jenkins-distribution service to automatically start on boot:

    sudo chkconfig --add cloudbees-jenkins-distribution
    sudo /etc/init.d/cloudbees-jenkins-distribution start

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

shell% chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins

Confirm settings

Any changes you made to /etc/sysconfig/jenkins are saved to /etc/sysconfig/jenkins.rpmsave when the jenkins package is removed.

If necessary, manually review this file, and copy the appropriate settings into /etc/sysconfig/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, start CloudBees Jenkins Distribution with the command

shell% service cloudbees-jenkins-distribution start

and move on to the post-migration tasks.

Debian / Ubuntu

To migrate from Jenkins to CloudBees Jenkins Distribution on Debian or Ubuntu systems, follow these instructions.

Remove the previously installed jenkins package

Replace the previously installed jenkins package with the cloudbees-jenkins-distribution package:

shell% apt-get remove jenkins (1)
shell% ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed jenkins package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for Debian / Ubuntu

Administrators running Debian-based distributions such as Debian or Ubuntu will need to add an APT repository and key in order to install CloudBees Jenkins Distribution.

  1. To use the Debian package repository of CloudBees Jenkins Distribution to automate installation and upgrade, first add the key to your system:

    wget -q -O - https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian/cloudbees.com.key | sudo apt-key add -
  2. Edit /etc/apt/sources.list and add the entry for CloudBees Jenkins Distribution:

    deb https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/debian binary/
  3. Update your local package index:

    sudo apt-get update
  4. Install CloudBees Jenkins Distribution:

    sudo apt-get install cloudbees-jenkins-distribution
    Caution
    Older versions of Debian and Ubuntu do not provide a Java 8 package and CloudBees Jenkins Distribution may fail to install as a result. Using newer versions of these distributions which provide Java 8 is strongly recommended.
  5. Start the cloudbees-jenkins-distribution service:

    service cloudbees-jenkins-distribution start

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

shell% chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins

Confirm settings

If you made changes to /etc/default/jenkins, review this file, and copy the appropriate settings into /etc/default/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, start CloudBees Jenkins Distribution with the command:

shell% service cloudbees-jenkins-distribution start

and move on to the post-migration tasks.

openSUSE / SUSE Linux

To migrate from Jenkins to CloudBees Jenkins Distribution on openSUSE- or SUSE Linux-based systems, follow these instructions:

Remove the previously installed jenkins package

Replace the previously installed jenkins package with the cloudbees-jenkins-distribution package:

shell% zypper remove jenkins (1)
shell% ln -s /var/lib/jenkins /var/lib/cloudbees-jenkins-distribution (2)
  1. This command removes the previously installed jenkins package from the system.

  2. This command creates a symbolic link to the old JENKINS_HOME so that CloudBees Jenkins Distribution can re-use the same home directory and its contents.

Install CloudBees Jenkins Distribution for openSUSE / SUSE Linux

Use the zypper command to install CloudBees Jenkins Distribution on openSUSE-based distributions.

  1. First, add the CloudBees RPM repository:

    sudo zypper addrepo -f https://downloads.cloudbees.com/cloudbees-jenkins-distribution/rolling/opensuse/ cloudbees-jenkins-distribution
  2. Next, run:

    sudo zypper install cloudbees-jenkins-distribution

Change ownership

Once installation is complete, change the ownership of the previous JENKINS_HOME to the cloudbees-jenkins-distribution user:

shell% chown -R cloudbees-jenkins-distribution:cloudbees-jenkins-distribution /var/lib/jenkins

Confirm settings

Any changes you made to /etc/sysconfig/jenkins are saved to /etc/sysconfig/jenkins.rpmsave when the jenkins package is removed.

If necessary, manually review this file, and copy the appropriate settings into /etc/sysconfig/cloudbees-jenkins-distribution.

Start CloudBees Jenkins Distribution

After completing these steps, start CloudBees Jenkins Distribution with the command

shell% service cloudbees-jenkins-distribution start

and move on to the post-migration tasks.

Microsoft Windows

To migrate from Jenkins to CloudBees Jenkins Distribution on Microsoft Windows systems, follow these instructions.

Remove the previously installed jenkins package and rename folders

Remove the previously installed jenkins package:

  1. Stop the jenkins service and delete it.

  2. Rename the folder where the jenkins service was running from Program Files (x86)/Jenkins to Program Files (x86)/CloudBeesJenkinsDistribution

    Note
    Folder names may vary depending on where the Jenkins LTS was installed.

Download, install, and run CloudBees Jenkins Distribution for Windows

To run CloudBees Jenkins Distribution on Microsoft Windows, use the MSI file from the CloudBees Jenkins Distribution download site.

  1. Download the cloudbees-jenkins-distribution.zip file, and the SHA256 checksum file.

  2. The checksum file can be used to verify that the cloudbees-jenkins-distribution.zip is correct. Compare the contents of cloudbees-jenkins-distribution.zip.sha256 with the output of the following PowerShell command:

    $(CertUtil -hashfile D:\Users\USER\Downloads\cloudbees-jenkins-distribution.zip SHA256)[1] -replace " ",""
  3. Unpack the archive and execute the CloudBees Jenkins Distribution installer, cloudbees-jenkins-distribution.msi.

    Note
    The CloudBees Jenkins Distribution installer for Microsoft Windows requires a 64-bit operating system and a compatible .NET framework (2.0, 3.5.1, 4.0) in order to be installed as a service. Most Microsoft Windows versions install a compatible framework by default.

After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default.

Docker

To migrate from Jenkins to CloudBees Jenkins Distribution on Docker-based systems, follow these instructions:

Stop and delete the previously installed container service

Stop and delete the previously installed container service and update it with an appropriate Docker image.

shell% docker stop <Jenkins container name> && docker rm <Jenkins container name> (1)
shell% docker pull cloudbees/cloudbees-jenkins-distribution (2)
shell% docker run --name <Jenkins container name> -p 18080:8080 -v /tmp/docker/:/var/jenkins_home [IMAGE_ID] (3)
  1. This command stops and deletes the previous container.

  2. This command pulls a new Docker image from CloudBees.

  3. This command launches a container from the new image with the same name (<Jenkins container name>) and same JENKINS_HOME volume.

After the process has completed, CloudBees Jenkins Distribution will start automatically and be available on port 8080 by default, and you can move on to the post-migration tasks.

Stand-alone WAR file

While it is strongly recommended that administrators rely on the native packages above, CloudBees Jenkins Distribution can be run as a stand-alone WAR file with an existing JENKINS_HOME.

Install and run CloudBees Jenkins Distribution for stand-alone WAR files

  1. Download the WAR file for CloudBees Jenkins Distribution; for your operating system and copy it to where you wish to run CloudBees Jenkins Distribution.

  2. Copy the file to the directory where you wish to run CloudBees Jenkins Distribution.

  3. Open a terminal and run the command:

    java -jar cloudbees-jenkins-distribution.war
  4. The process output generates a password offset by three rows of asterisks above and below the text. Copy the password. The password is also saved in a directory like /users/<username>.jenkins/secrets/initialAdminPassword, where username is replaced with your username. The exact path may vary depending upon your operating system.

    *************************************************************
    *************************************************************
    *************************************************************
    
    Jenkins initial setup is required. An admin user has been created and a password generated.
    Please use the following password to proceed to installation:
    
    d661ea28c6b94406ad627601b6f4aa877
    
    This may also be found at: /Users/<username>/.jenkins/secrets/initialAdminPassword
    
    *************************************************************
    *************************************************************
    *************************************************************
  5. The terminal portion is complete when the output reads:

    INFO: Obtained the updated data file for hudson.tools.JDKInstaller
    Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get
    INFO: Beekeeper is parsing UpdateSite cloudbees-jenkins-distribution-offline
    Jan 24, 2019 4:38:57 PM com.cloudbees.jenkins.plugins.assurance.model.UpdateSiteDataProvider$Value get
    INFO: Beekeeper is parsing UpdateSite cap-cloudbees-jenkins-distribution
    Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run
    INFO: Started telemetry collection
    Jan 24, 2019 4:42:42 PM hudson.model.AsyncPeriodicWork$1 run
    INFO: Finished telemetry collection. 1 ms

To complete the migration, set the JENKINS_HOME environment variable to the existing Jenkins home directory. For example:

shell% JENKINS_HOME=/var/lib/jenkins java -jar cloudbees-jenkins-distribution.war

Kubernetes deployment

Migrating from a Jenkins LTS instance deployed on a Kubernetes cluster to CloudBees Jenkins Distribution consists of three steps:

  1. Configuring the Persistent Volume so it can be used by the new CloudBees Jenkins Distribution instance.

  2. Changing the Jenkins home location.

  3. Upgrading the deployment.

Prerequisites

These migration instructions assume that any cluster management tools such as kubectl or helm have been properly installed and configured.

Caution
The Kubernetes cluster must be configured with either a Persistent Volume (PV) or Persistent Volume Claim (PVC). This prevents data loss when the Jenkins pod is terminated, and permits you to change the Jenkins home location. For detailed instructions and explanation, see the Kubernetes documentation for Persistent Volumes.

Configuring the Persistent Volume so it can be used by the new CloudBees Jenkins Distribution instance.

Identifying the PVC and PC

PVCs and PVs are identified by name. To retrieve the name:

  1. Identify the PVC

    shell% kubectl get pvc
    
    NAME            STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    my-ci-jenkins   Bound    pvc-66bb97bd-a475-11e9-a618-0800275062ed   8Gi        RWO            standard       13m
  2. Identify the PC

    shell% kubectl get pv
    
    NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                   STORAGECLASS   REASON   AGE
    pvc-66bb97bd-a475-11e9-a618-0800275062ed   8Gi        RWO            Delete           Bound    default/my-ci-jenkins   standard                13m

Changing the Retain Policy

If you want to re-use the same PVC and PV, you must change the value of the Retain Policy. This is to prevent the volume from being deleted if the deployment is regenerated during the migration.

  1. Issue the command kubectl get pv, and check the value of the RECLAIM POLICY column in the output.

  2. If the Reclaim Policy is set to anything other than Retain, patch the PV with the command kubectl patch, substituting the appropriate PV-NAME from the output of the kubectl get pv command:

    shell% kubectl patch pv PV-NAME -p '"spec":"persistentVolumeReclaimPolicy":"Retain"}}'
  3. To verify that the patch has been applied, run the kubectl get pv command again and confirm that the value of the Retain Policy is now Retain.

Making the PVC selectable by the CloudBees Jenkins Distribution deployment

The CloudBees Jenkins Distribution deployment uses the values of two labels to select the objects that are associated with the pod:

  1. "app.kubernetes.io/instance": "{{ .Release.Name }}"

  2. "jenkins.instance": "cjd"

{{ .Release.Name }} is the name given to the release when the Jenkins deployment is installed by helm. If you’re not sure what value the label should have, issue the command helm list to display the list of releases installed on your cluster.

  1. To confirm that the PVC has set the proper labels, issue the kubectl describe pvc command, substituting the appropriate PVC-NAME from the output of the kubectl get pvc command. The kubectl describe pvc command retrieves the description of the PVC, which provides the labels (if any) for this object:

    shell% kubectl describe pvc PVC-NAME
    
    Name:          my-ci-jenkins
    Namespace:     default
    StorageClass:  standard
    Status:        Bound
    Volume:        pvc-66bb97bd-a475-11e9-a618-0800275062ed
    Labels:        app.kubernetes.io/component=jenkins-master
                   app.kubernetes.io/instance=my-ci
                   app.kubernetes.io/managed-by=Tiller
                   app.kubernetes.io/name=jenkins
                   helm.sh/chart=jenkins-1.1.18
    Annotations:   control-plane.alpha.kubernetes.io/leader:
                     {"holderIdentity":"9eee62df-a474-11e9-a5ff-0800275062ed","leaseDurationSeconds":15,"acquireTime":"2019-07-12T07:19:35Z","renewTime":"2019-...
                   pv.kubernetes.io/bind-completed: yes
                   pv.kubernetes.io/bound-by-controller: yes
    Finalizers:    [kubernetes.io/pvc-protection]
    Capacity:      8Gi
    Access Modes:  RWO
    VolumeMode:    Filesystem
    Mounted By:    my-ci-jenkins-69897b85bd-ff7bn
    Events:
      Type    Reason                 Age   From                                                           Message
      ----    ------                 ----  ----                                                           -------
      Normal  Provisioning           14m   k8s.io/minikube-hostpath 9eee62df-a474-11e9-a5ff-0800275062ed  External provisioner is provisioning volume for claim "default/my-ci-jenkins"
      Normal  ProvisioningSucceeded  14m   k8s.io/minikube-hostpath 9eee62df-a474-11e9-a5ff-0800275062ed  Successfully provisioned volume pvc-66bb97bd-a475-11e9-a618-0800275062ed
  2. If any of the labels are missing, issue the kubectl label pvc command, substituting the appropriate PVC-NAME from the output of the kubectl get pvc command. kubectl label pvc updates the PVC with the values you provide for LABEL-NAME and LABEL-VALUE:

    shell% kubectl label pvc PVC-NAME LABEL-NAME=LABEL-VALUE

Changing the Jenkins home location

The Jenkins home location must be changed because CloudBees Jenkins Distribution uses a different location than the Jenkins LTS.

To change the Jenkins home location:

  1. Create a temporary directory on your local workstation, because you can’t directly copy a directory within a cluster into another directory within the same cluster:

    shell% mkdir /tmp/jenkins_home_data
  2. Use the kubectl get pods command to retrieve the list of pods in the Kubernetes cluster:

    shell% kubectl get pods -A
    
    NAMESPACE     NAME                             READY   STATUS    RESTARTS   AGE
    default       cicd-jenkins-74b85c44cc-zsq6r    1/1     Running   0          15m
    kube-system   aws-node-4gz5w                   1/1     Running   0          19m
    kube-system   aws-node-5smgn                   1/1     Running   0          19m
    kube-system   aws-node-7cjdc                   1/1     Running   0          19m
    kube-system   coredns-7bcbfc4774-2j6lj         1/1     Running   0          31m
    kube-system   coredns-7bcbfc4774-cgxrl         1/1     Running   0          31m
    kube-system   kube-proxy-2pkw6                 1/1     Running   0          19m
    kube-system   kube-proxy-528n4                 1/1     Running   0          19m
    kube-system   kube-proxy-dt4d8                 1/1     Running   0          19m
    kube-system   tiller-deploy-54fc6d9ccc-tg7fd   1/1     Running   0          16m
  3. Use the kubectl cp command to copy the Jenkins home directory to the temporary directory, substituting the appropriate NAMESPACE and NAME from the output of the kubectl get pods command:

    shell% kubectl cp <NAMESPACE>/<NAME>:/var/jenkins_home /tmp/jenkins_home_data
  4. Finally, use the kubectl cp command to copy the old Jenkins home information into the new location, again substituting the appropriate NAMESPACE and NAME from the output of the kubectl get pods command:

    shell% kubectl cp  /tmp/jenkins_home_data/ NAMESPACE/POD-NAME:/var/cloudbees-jenkins-distribution

Migrating or upgrading Helm-installed instances

For installations that were installed with Helm, CloudBees strongly recommends delegating the upgrade to Helm as well.

Helm supports many public and private Helm Chart Repositories, and you must add the CloudBees repository to your Helm environment before you can use it:

  1. Add the CloudBees Helm Chart Repository to your Helm installation:

    shell% helm repo add cloudbees https://charts.cloudbees.com/public/cloudbees
  2. Update your local Helm Chart Repository cache, which improves the performance of commands like helm search. To update the cache:

    shell% helm repo update
  3. After you’ve added the CloudBees repository and updated the Chart Repository Cache, you can upgrade the instance.

  4. Upgrade the instance with the helm upgrade command, substituting the appropriate PV-NAME from the output of the kubectl get pv command, and providing a value for RELEASE-NAME (if you are uncertain about the instance’s name, use the helm list command to retrieve it):

    Caution
    The administrative user and password are changed during the migration, because the migration process deletes the former pod and creates a new one. To retain the old values, add --set master.adminUser=PREVIOUS-USER --set master.adminPassword=PREVIOUS-PASSWD to the helm upgrade command.
    shell% helm upgrade --set persistence.existingClaim=PVC-NAME RELEASE-NAME cloudbees/cloudbees-jenkins-distribution

Migrating or upgrading instances not installed with Helm

CloudBees strongly recommends using Helm to install or upgrade installations. However, if you are using an installation not installed with Helm, there are two options:

  1. Migrate to Helm

  2. Update the deployment and change the docker image

Migrating to Helm

To migrate your installation to Helm:

  1. Remove all deployment information except the PVC.

  2. Change the Jenkins home location as shown in Changing the Jenkins home location.

  3. Install the chart using the helm install command, substituting the appropriate PV-NAME from the output of the kubectl get pv command, and providing a value for RELEASE-NAME:

    shell% helm install --set persistence.existingClaim=PVC-NAME RELEASE-NAME cloudbees/cloudbees-jenkins-distribution

Updating the deployment and changing the docker image

There are two ways to edit and update the Docker image used in the Kubernetes cluster.

Caution
When you edit or update a Docker image, the Kubernetes cluster discards the current active pod and creates a new one with the new Docker image.
Edit the deployment online

The first method of changing the Docker image is to directly edit the Kubernetes cluster configuration:

  1. Change the Jenkins home location as shown in Changing the Jenkins home location.

  2. Use the kubectl get deployments command to retrieve the list of pods in the cluster:

    shell% kubectl get deployments
    
    NAME           DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
    cicd-jenkins   1         1         1            1           20m
  3. Use the kubectl edit deployment command to open your pre-defined CLI editor (such as vi or vim) and edit the deployment’s configuration. Substitute the appropriate NAME from the output of the kubectl get deployments command:

    shell% kubectl edit deployment/NAME
  4. In the editor, locate the line that reads

    image: jenkins/jenkins:lts

    and change it to read

    image: cloudbees/cloudbees-jenkins-distribution:latest
  5. Next, locate the line that reads

    mountPath: /var/jenkins_home

    + and change it to read

    mountPath: /var/cloudbees-jenkins-distribution
  6. Save the file. The resulting configuration should resemble:

    spec:
      template:
        spec:
          containers:
          - image: cloudbees/cloudbees-jenkins-distribution:latest
              [...]
              volumeMounts:
              - mountPath: /var/cloudbees-jenkins-distribution
  7. Use the kubectl get pods --watch command to display any changes to the pod status. Because Kubernetes creates a new pod for the new Docker image, the deployment is not actually ready until the status is Running.

    shell% kubectl get pods --watch
    
    NAME                            READY   STATUS            RESTARTS   AGE
    cicd-jenkins-7c69dbcbb4-wkcz7   0/1     Init:0/1          0          52s
    cicd-jenkins-7c69dbcbb4-wkcz7   0/1     PodInitializing   0          53s
    cicd-jenkins-7c69dbcbb4-wkcz7   0/1     Running           0          72s
Patching the deployment directly

The second method involves directly patching the deployment instead of using a CLI editor:

  1. Use the kubectl get deployments command to retrieve the list of pods in the cluster:

    shell% kubectl get deployments
    
    NAME           DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
    cicd-jenkins   1         1         1            1           20m
  2. Create a patch.yaml file in your local file directory.

  3. Populate patch.yaml with the configuration fields you want to change. Substitute the name of the deployment as appropriate, using the output of the kubectl get deployments command. You can change any configuration field in the deployment, but the recommended minimum patch is:

    spec:
      template:
        spec:
          containers:
            - name: <NAME>
              image: "cloudbees/cloudbees-jenkins-distribution:latest"
    
              volumeMounts:
                - mountPath: /var/cloudbees-jenkins-distribution
                  name: jenkins-home
                  readOnly: false
  4. Use the kubectl patch deployment command to patch the deployment:

    shell% kubectl patch deployment DEPLOYMENT-NAME --patch "$(cat patch.yaml)"
  5. Use the kubectl get pods --watch command to display the pod status changes. Because Kubernetes creates a new pod for the updated Docker image, the deployment is not actually ready until the status is Running.

    shell% kubectl get pods --watch
    
    NAME                            READY   STATUS            RESTARTS   AGE
    cicd-jenkins-7c69dbcbb4-wkcz7   0/1     Init:0/1          0          52s
    cicd-jenkins-7c69dbcbb4-wkcz7   0/1     PodInitializing   0          53s
    cicd-jenkins-7c69dbcbb4-wkcz7   0/1     Running           0          72s

Post-migration tasks

Completing post-install configuration

After installation, the Getting Started wizard will walk you through installing a curated set of plugins and creating the first admin account.

Security and unlocking the distribution

CloudBees Jenkins Distribution is initially configured to be secure on first launch. During installation, a password is generated and saved in a local file called initialAdminPassword. The file location depends upon the operating system you are using.

This password is required to unlock the instance on the Unlock Jenkins page.

To locate the password:

  1. Open a browser to http://localhost:8080.

  2. Open the initialAdminPassword file using the location displayed on the Unlock Jenkins page.

  3. Copy the password from the file.

Alternatively, the password may be displayed during installation. For example, the output below was from installing on macOS using a WAR file:

*************************************************************
*************************************************************
*************************************************************

Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:

d661ea28c6b94406ad627601b6f4aa877

This may also be found at: /Users/<username>/.jenkins/secrets/initialAdminPassword

*************************************************************
*************************************************************
*************************************************************

Registration

During setup, you will be prompted to choose a registration type. You can register with a free product key online or contact CloudBees at support@cloudbees.com to obtain registration activation.

Using the Getting Started wizard

  1. Open a browser to http://localhost:8080.

  2. On the Unlock Jenkins page, paste in the Administrator password retrieved in the previous section in the field. Press Continue.

  3. Select the appropriate registration option on the License page.

    • Activate CloudBees Jenkins Distribution (requires online activation): Complete the form on Register CloudBees Jenkins Distribution page. Enter your name, email and company, check the box to accept the license agreement and click Submit. The Setup Wizard will contact CloudBees to create a license and apply the license to the product.

    • Use a license key (Apply a valid license key; useful for offline installations): Click Activate CloudBees Jenkins Distribution to obtain a free license (requires internet access). Email sales@cloudbees.com to obtain a register your product. Once you have the free license from CloudBees, select license key and paste the License Key and License Certificate from your registration in to their fields. Review the license and then accept the license by clicking the check box and click Submit.

  4. Select Install suggested plugins on the Customize Jenkins page to install the curated set of plugins recommended by CloudBees.

  5. The Getting Started page displays the setup progress. If any updates are available, you will also be given the option to upgrade. These upgrades may also be performed at a later time using the Beekeeper Upgrade Assistant.

  6. On the Create First Admin User page, enter a username, password (twice), full name, and email address for the first admin user. Press Save and Continue.

  7. Enter a new value for the Jenkins URL on the Instance Configuration page. You may choose to use the default value or to enter a new URL. Press Save and Finish.

    Important
    The Jenkins URL provides the root URL for absolute links to various Jenkins resources, including email notifications, PR status updates, and the BUILD_URL environment variable provided to build steps.
  8. You may be asked to reboot your system.