Notes

How to integrate the following "Üsing Plugin Manager Tool" material into Manage Plugins section?

Option 1: Since, cloud native deployments are in vogue and configuration as code is useful, it is good to have a separate section in the book as"Üsing Plugin Install Manager Tool" after "Managing Plugins" section to give it visibility.

Option 2: Is it possible to include this page as a sub-section independent page. Plug a reference to this page into Manage Plugins section page as a third type of plugin installation method ?

Option 3: Integrate this content into "Managing Plugins" section as a 3rd type of plugin installation method and update "Ädvanced Installation subsection".

Option 4: Any other better option that fits better into the jenkins doc environment

Using Plugin Install Manager Tool

Jenkins Plugin Install Manager is a command line tool used to manage the installation, upgrade and plugin dependency management of Jenkins plugins on a Jenkins controller. Using this tool installed on Jenkins controller, many plugins and their dependent plugins can be installed by a single execution of this tool.

The common scenario of plugin installation preview, dependency management and upgrade will be demonstrated in the reminder of the section. The plugin used in these examples is Kubernetes Plugin for Jenkins. Note plugin is specified in the form <plugin name>:<version>

Installing the Plugin Install Manager tool

The tool has to be installed on Jenkins controller, It is a JAR file and is downloaded from here into the current working directory on a Jenkins controller. An example command to invoke the tool is given below

java -jar ./jenkins-plugin-manager-2.9.2.jar --war /usr/share/jenkins/jenkins.war --available-updates  --plugin-download-directory . --output txt --plugins <plugin-need to be installed>

 --plugin-filei (-f)             : (optional) Path to the plugins.txt, or
                                   plugins.yaml files, which contains a list
                                   of plugins to install.
 --plugin-download-directory (-d): (optional) Directory in which to install
                                   plugins. This option can be configured
                                   using the PLUGIN_DIR environment variable.
                                   The defaults are
                                   C:\ProgramData\Jenkins\Reference\Plugins
                                   on Microsoft Windows OS and
                                   /usr/share/jenkins/ref/plugins on Cent OS.
 --plugins (-p)                  : (optional) List of plugins to install (
                                   plugin version format is specified below),
                                   separated by a space.
--jenkins-version                : (optional) Version of Jenkins to be used.
                                   This option can be set using the
                                   JENKINS_VERSION environment variable.
--war (-w)                       : (optional) Path to Jenkins war file.
                                   Default location used is
                                   /usr/share/jenkins/jenkins.war in Unix OS
                                   and C:\ProgramData\Jenkins\jenkins.war in
                                   Microsoft WIndows OS.
--list (-l)                      : (optional) Lists plugin names and versions
                                   of: installed plugins (plugins that already
                                   exist in the plugin directory), bundled
                                   plugins (non-detached plugins that exist in
                                   the war file), plugins that will be
                                   downloaded (highest required versions of
                                   the requested plugins and dependencies that
                                   are not already installed), and the
                                   effective plugin set (the highest versions
                                   of all plugins that are already installed
                                   or will be installed)
--verbose                        : (optional) Allows output of  additional
                                   information about plugin dependencies and
                                   the download process
--view-security-warnings         : (optional) Set to true to show if any of
                                   the user specified plugins have security
                                   warnings
--view-all-security-warnings     : (optional) Set to true to show all plugins
                                   that have security warnings.
--available-updates              : (optional) Indicates if the specified
                                   plugins have newer versions available. This
                                   information is based on the specific
                                   Jenkins Update Center being used.
--output {json,text,yaml}        : (optional) Format of output about plugin
                                   updates to file or stdout. stdout is the
                                   default.
--latest false                   : (optional) Set to false to download the
                                   minimum required version of all
                                   dependencies.
--jenkins-update-center          : (optional) Sets the Jenkins update center
                                   filename.This information can be set in
                                   JENKINS_UC environment variable. CLI option
                                   overrides the environment variable. The
                                   default value is
                                   https://updates.jenkins.io/update-center.ac
                                   tual.json

IMPORTANT:

  • The location of the jenkins.war file is dependent on the flavor of operating system the Jenkins controller is using.

  • Run the commands listed in this section as Jenkins Administrator user.

  • After install or upgrade of plugin(s) on UNIX/Linux systems, make sure the Jenkins user id and group id own respective plugin *.jpi files.

  • Restart Jenkins controller after install or upgrade of plugin(s)

Listing plugin dependencies

The following command outputs the plugin and complete list of dependent plugins' with version information. This information can be redirected to a output file. This file can be used as input to the tool to install or upgrade this plugin and the dependent plugin(s). Example plugin used in plugin installation preview is Kubernetes plugin version 1.29.2

java -jar ./jenkins-plugin-manager-2.9.2.jar --war /usr/share/jenkins/jenkins.war --available-updates --plugin-download-directory . --output txt --plugins kubernetes-plugin:1.29.2

Previewing installation of Plugin

The following command outputs the plugin and it’s dependent plugins' with version information. These are the plugins that need to be installed on this Jenkins controller installation. Example plugin used in plugin installation preview is Kubernetes plugin version 1.29.2

java -jar ./jenkins-plugin-manager-2.9.2.jar --war /usr/share/jenkins/jenkins.war --available-updates  --plugin-download-directory /var/lib/jenkins/plugins --output txt --plugins kubernetes-plugin:1.29.2

Installing Plugin

The following command installs version 1.29.2 of Kubernetes plugin & it’s dependent plugins. It outputs the list of plugins installed.

java -jar ./jenkins-plugin-manager-2.9.2.jar --war /usr/share/jenkins/jenkins.war --output txt --plugins kubernetes-plugin:1.29.2 deployit-plugin

Upgrading plugin

The following command upgrades Kubernetes plugin from release 1.29.2 to 1.29.4.

java -jar ./jenkins-plugin-manager-2.9.2.jar --war /usr/share/jenkins/jenkins.war --output yaml --plugins kubernetes-plugin:1.29.4 deployit-plugin

Using with Docker

If you use a Jenkins docker image, the plugin manager can be invoked inside the container via the bundled jenkins-plugin-cli shell script (specified in Dockerfile) as follows.

FROM jenkins/jenkins:lts-jdk11
jenkins-plugin-cli --plugin-file /your/path/to/plugins.txt --plugins delivery-pipeline-plugin:1.3.2 deployit-plugin

Using Update Center location

Plugins are downloaded from the update center specified by the appropriate environment variable or command line parameter specified here.

Using plugin version format

Plugin version format to be used is described here and examples are here. A notable feature of this tool is that a plugin compatible with a Jenkins release by using Jenkins version in the plugin identifier as shown below

github-branch-source::https://updates.jenkins.io/2.121/latest/github-branch-source.hpi

A text file can be used to install the latest versions of the specified plugins and a YAML file can be used to install specific versions of plugins. Multiple plugins to be installed can be listed in these files These files are provided as a command line parameter to --plugin-file command line option of this tool.

Using Reverse Proxy

If a reverse proxy is used in the Jenkins installation environment, then the command line parameters for the tool are specified here.

Using command line parameters

Refer to this page for more details on the command line options to this tool.