Pulling together the Managing Jenkins chapter #519

Merged
merged 12 commits into from Jan 9, 2017

Projects

None yet

3 participants

@rtyler
Member
rtyler commented Jan 3, 2017 edited
@rtyler rtyler changed the title from WIP: Pulling together the Managing Jenkins chapter to Pulling together the Managing Jenkins chapter Jan 6, 2017
@rtyler
Member
rtyler commented Jan 6, 2017

@jenkins-infra/docs and @jenkins-infra/copy-editors I've created the sections "Managing Security" and "Managing Plugins"

My intent with this pull request is only to complete those two sections plus the "Jenkins CLI" section.

My demo site has been deployed with these changes. If you have the time, I would appreciate a review.

@rtyler rtyler removed the work-in-progress label Jan 6, 2017
content/doc/book/managing/cli.adoc
+====
+
+Jenkins has a built-in command line interface that allows you to access Jenkins
+from a script or from your shell. This is convenient for automation of routine
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

This enables scripting of routine

content/doc/book/managing/cli.adoc
+`/jnlpJars/jenkins-cli.jar` on your Jenkins server, for example
+`https://example.com/jnlpJars/jenkins-cli.jar`
+
+In theory, the CLI JAR is dependent on the version of Jenkins, but in practice,
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

A new version of the CLI JAR is published with each version of Jenkins. While we attempt to retain CLI JAR compatibility between different versions of Jenkins, a CLI JAR and Jenkins with differing versions may not work together. In case of unexplained errors, try re-downloading the latest CLI JAR from your Jenkins server.

@rtyler
rtyler Jan 7, 2017 Member

This document was still a work-in-progress and this stupid paragraph has been nuked.

content/doc/book/managing/cli.adoc
+
+In theory, the CLI JAR is dependent on the version of Jenkins, but in practice,
+we expect to be able to retain compatibility between different versions of
+Jenkins. In case of problems, just re-download the latest JAR from your Jenkins
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

s/just//

content/doc/book/managing/nodes.adoc
@@ -6,7 +6,8 @@ layout: section
:author:
:email: jenkinsci-users@googlegroups.com
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

jenkinsci-docs@googlegroups.com
If you're going to do this in one file, let's do it everywhere.

content/doc/book/managing/plugins.adoc
+
+Plugins are the primary means of enhancing the functionality of a Jenkins
+environment to suit organization or user-specific needs. There are well
+link:https://plugins.jenkins.io[over a thousand different plugins]
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

move "well" inside the link text or remove.

content/doc/book/managing/plugins.adoc
+Plugins are the primary means of enhancing the functionality of a Jenkins
+environment to suit organization or user-specific needs. There are well
+link:https://plugins.jenkins.io[over a thousand different plugins]
+which can be freely installed on a Jenkins master, which integrate various
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

s/freely installed/installed for free/
or
s/freely//

I mean, yeah, freely installed, but... That sounds like "tip-toe through the Jenkins, freely installing plugins".

@bitwiseman
bitwiseman Jan 6, 2017 Contributor

integrate with

content/doc/book/managing/plugins.adoc
+
+This section will introduce the basics of managing plugins from within the
+Jenkins web UI, to making changes on the <<../glossary#master,master's>> file
+system.
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

This section will cover everything from the basics of managing plugins from within the Jenkins web UI, to making changes on the <<../glossary#master,master's>> file system.

content/doc/book/managing/plugins.adoc
+Jenkins provides a few different methods for installing plugins on the master:
+
+. Using the "Plugin Manager" in the web UI.
+. Using the <<install-with-cli,Jenkins CLI>>.
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

.Using the Jenkins CLI <<install-with-cli,install-with-cli>> command.

content/doc/book/managing/plugins.adoc
+Each approach will result in the plugin being loaded by Jenkins but may require
+different level of access and trade-offs in order to use.
+
+The first two approaches require that the Jeknins master be able to connect to
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

Jenkins

content/doc/book/managing/plugins.adoc
+an Update Center, whether the primary Update Center operated by the Jenkins
+project
+footnoteref:[uc, https://updates.jenkins.io],
+or a custom Update Center, in order to download meta-data.
@bitwiseman
bitwiseman Jan 6, 2017 Contributor
The first two approaches require that the Jenkins master be able to download meta-data from
an Update Center, whether the primary Update Center operated by the Jenkins
project
footnoteref:[uc, https://updates.jenkins.io],
or a custom Update Center.
content/doc/book/managing/plugins.adoc
+
+=== From the web UI
+
+The simplest, and most common, way for installing plugins is through the
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

No commas needed.

content/doc/book/managing/plugins.adoc
+Jenkins environment.
+
+Under the *Available* tab, plugins available for download from the configured
+Update Center, can be searched and considered:
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

s/,//

+
+=== Advanced installation
+
+The Update Center only allows the installation of the most recently released
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

You list three ways above, but this shows four ways - two basic, two "advanced". List them as four different ways above and drop the "Advanced" or reorganize the list above.

content/doc/book/managing/plugins.adoc
+
+==== From the web UI
+
+Assuming a `.hpi` file has been downloaded from the Update Site footnoteref:[uc], a
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

s/Update Site/Update Center/

@bitwiseman
bitwiseman Jan 6, 2017 Contributor

Also, does it matter where the hpi came from? If not, change text.

content/doc/book/managing/plugins.adoc
+
+==== On the master
+
+Assuming a `.hpi` file has been downloaded from the Update Site footnoteref:[uc], a systems
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

s/Update Site/Update Center/

+
+A plugin may also be uninstalled by removing the corresponding `.hpi`
+file from the `JENKINS_HOME/plugins` directory on the master. The plugin will
+continue to function until the master has been restarted.
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

This needs a WARNING block about how this can cause plugins that depend on a removed plugin to stop working.

+uninstalled plugins. Navigate to *Manage Jenkins* and then click on *Manage
+Old Data* to review and remove old data.
+
+=== Disabling a plugin
@bitwiseman
bitwiseman Jan 6, 2017 Contributor

This is softer, so put it before the uninstall section.

@rtyler
rtyler Jan 7, 2017 Member

I actually put it after intentionally, assuming the common case would be "Uninstall" and "Disabling" would be the less common case

@rtyler
Member
rtyler commented Jan 7, 2017

I've put together about as much of the CLI section as I have the motivation to do this week 🤣

@rtyler
Member
rtyler commented Jan 9, 2017

@bitwiseman will you please take another look at this when you get a chance?

content/doc/book/managing/cli.adoc
+Whether using the CLI via SSH, or with the CLI client, both rely primarily on
+SSH-based public/private key authentication. In order to add an SSH public key
+for the appropriate user, navigate to
+`https://JENKINS_URL/user/USERNAME/cnofigure` and paste an SSH public key
@omehegan
omehegan Jan 9, 2017

s/cnofigure/configure/

content/doc/book/managing/cli.adoc
+
+Jenkins has a number of built-in CLI commands which can be found in every
+Jenkins environment, such as `build` or `list-jobs`. Plugins may also provide
+CLI commands however; in order to determine the full list of commands available
@omehegan
omehegan Jan 9, 2017

I would strike 'however.' Also, we already talk about using the 'help' command above, in the Using the CLI section. Maybe we should strike that copy and keep this one, since this progresses into a further explanation of the common commands.

content/doc/book/managing/cli.adoc
+% ssh -l kohsuke -p 53801 localhost help
+----
+
+The following list of commands is not comprehensive, but are useful for basic
@omehegan
omehegan Jan 9, 2017

I would say, 'but it is a useful starting point for Jenkins CLI usage.'

content/doc/book/managing/cli.adoc
+
+==== build
+
+One of the most common, and useful, CLI commands is `build` which allows the
@omehegan
omehegan Jan 9, 2017

I would strike the commas around 'and useful,' and add a single one after 'build', as 'build,'

content/doc/book/managing/cli.adoc
+One of the most common, and useful, CLI commands is `build` which allows the
+user to trigger any job or Pipeline for which they have permission.
+
+The most basic invocation will simply trigger the job or Pipeline an exit, but
@omehegan
omehegan Jan 9, 2017

I assume it should be 'and exit.' Also I would strike 'the' before 'additional options.'

content/doc/book/managing/cli.adoc
+
+==== console
+
+Similarly useful is the `console` command which retrieves the console output
@omehegan
omehegan Jan 9, 2017

'command, which ...'

content/doc/book/managing/cli.adoc
+
+The `who-am-i` command is helpful for listing the current user's credentials
+and permissions available to the user. This can be useful when debugging the
+absence of CLI commands based on the lack of certain permissions.
@omehegan
omehegan Jan 9, 2017

s/based on/due to/

content/doc/book/managing/cli.adoc
+
+While the SSH-based CLI is preferred, there may be situations where the CLI
+client is a better fit. For example, the default transport for the CLI client
+is HTTP which means no additional ports must be opened in a firewall for its
@omehegan
omehegan Jan 9, 2017

s/must be/need to be/

+=== Downloading the client
+
+The CLI client can be downloaded directly from a Jenkins master at the URL
+`/jnlpJars/jenkins-cli.jar`, in effect `https://JENKINS_URL/jnlpJars/jenkins-cli.jar`
@omehegan
omehegan Jan 9, 2017

Should we perhaps assume that their JENKINS_URL is not protected by SSL? Or is that now enabled by default or something?

@rtyler
rtyler Jan 9, 2017 Member

It's not enabled by default, but I have been using it more as a subtle nod that their JENKINS_URL should use HTTPs.

content/doc/book/managing/cli.adoc
+The CLI client can be downloaded directly from a Jenkins master at the URL
+`/jnlpJars/jenkins-cli.jar`, in effect `https://JENKINS_URL/jnlpJars/jenkins-cli.jar`
+
+While a CLI `.jar` can be used against different versions of Jenkins, should an
@omehegan
omehegan Jan 9, 2017

s/an/any/

content/doc/book/managing/plugins.adoc
+////
+
+Plugins are the primary means of enhancing the functionality of a Jenkins
+environment to suit organization or user-specific needs. There are
@omehegan
omehegan Jan 9, 2017

'organization- or user-specific'

content/doc/book/managing/plugins.adoc
+Plugins are the primary means of enhancing the functionality of a Jenkins
+environment to suit organization or user-specific needs. There are
+link:https://plugins.jenkins.io[over a thousand different plugins]
+which can be installed on a Jenkins master and integrate various
@omehegan
omehegan Jan 9, 2017

'to integrate'
'and much more.' [more grammatically correct, even if it sounds like an infomercial]

content/doc/book/managing/plugins.adoc
+
+Plugins can be automaticaly downloaded, with their dependencies, from the
+<<../glossary#update-center,Update Center>>. The Update Center is a service
+operated by the Jenkins project and provides an inventory of open source
@omehegan
omehegan Jan 9, 2017

s/and provides/which provides/

rtyler added some commits Dec 21, 2016
@rtyler rtyler Add a Managing Users section to the Managing Jenkins chapter 1bc0f15
@rtyler rtyler Re-order the chapter sections to capture the ordering under "Configur…
…e System"
da5b611
@rtyler
Member
rtyler commented Jan 9, 2017

@omehegan Thanks for the review, I've addressed the comments.

content/doc/book/managing/plugins.adoc
+
+== Installing a plugin
+
+Jenkins provides a couple different methods for installing plugins on the master:
@omehegan
omehegan Jan 9, 2017

'couple of different'

content/doc/book/managing/plugins.adoc
+. Using the <<install-with-cli,Jenkins CLI>> `install-plugin` command.
+
+Each approach will result in the plugin being loaded by Jenkins but may require
+different level of access and trade-offs in order to use.
@omehegan
omehegan Jan 9, 2017

'levels of'

content/doc/book/managing/plugins.adoc
+
+=== From the web UI
+
+The simplest and most common way for installing plugins is through the
@omehegan
omehegan Jan 9, 2017

'way of'

+[[install-with-cli]]
+=== Using the Jenkins CLI
+
+Administrators may also use the <<cli#,Jenkins CLI>> which provides a command
@omehegan
omehegan Jan 9, 2017

Consider combining these three sentences into one paragraph?

+
+==== From the web UI
+
+Assuming a `.hpi` file has been downloaded, a logged-in Jenkins administrator
@omehegan
omehegan Jan 9, 2017

Depending on whether you read this as 'dot hpi' or just 'hpi,' you may want to s/a/an/

content/doc/book/managing/plugins.adoc
+== Updating a plugin
+
+Updates are listed in the *Updates* tab of the *Manage Plugins* page and can be
+selected by checking the checkboxes of the desired plugin updates and clicking
@omehegan
omehegan Jan 9, 2017

s/selected by/installed by/

content/doc/book/managing/plugins.adoc
+
+When a plugin is no longer used in a Jenkins environment, it is prudent to
+remove the plugin from the Jenkins master. This provides a number of benefits
+such as: reducing memory overhead at boot or runtime, reducing configuration
@omehegan
omehegan Jan 9, 2017

I would strike the colon.

content/doc/book/managing/plugins.adoc
+some configurations could not be fully loaded and ignore the unrecognized data.
+
+Since the configuration(s) will be preserved until they are overwritten,
+re-installing the plugin will result in those configuration values reappearing..
@omehegan
omehegan Jan 9, 2017

Extra period.

@omehegan
omehegan Jan 9, 2017

You might also spell out that this means that if you reinstall the plugin its full configuration is restored.

+Jenkins master, such as: `JENKINS_HOME/plugins/PLUGIN_NAME.hpi.disabled`.
+
+The configuration(s) created by the disabled plugin behave as if the plugin
+were uninstalled, insofar that they result in warnings on boot but are
@omehegan
omehegan Jan 9, 2017

I think 'insofar' almost has to be followed by 'as.'

content/doc/book/managing/plugins.adoc
+link:https://plugins.jenkins.io/matrix-auth[*Matrix Authorization plugin*].
+
+By default, whenever Jenkins is upgraded, its bundled plugins overwrite the
+versions of the plugins are currently installed in `JENKINS_HOME`.
@omehegan
omehegan Jan 9, 2017

s/are/that are/

content/doc/book/managing/plugins.adoc
+versions of the plugins are currently installed in `JENKINS_HOME`.
+
+However, when a bundled plugin has been manually updated, Jenkins will mark
+that plugin as pinned to the particular version. On the file system, Jenkins
@rtyler
rtyler Jan 9, 2017 Member

"filesystem" isn't a word AFAICT, everywhere else I have been using "file system" (such as in the glossary

content/doc/book/managing/plugins.adoc
+`JENKINS_HOME/plugins/PLUGIN_NAME.hpi.pinned` file can also be manually
+created/deleted to control the pinning behavior. If the `pinned` file is
+present, Jenkins will use whatever plugin version the user has specified. use
+whatever version the user has specified. If the file is absent, Jenkins will
@omehegan
omehegan Jan 9, 2017

Repetition.

rtyler added some commits Dec 21, 2016
@rtyler rtyler Author a basic Managing Plugins section with content imported from th…
…e wiki
68a8fc2
@rtyler rtyler Add a section for the Jenkins CLI 8b2ca1e
@rtyler rtyler Add a Script Console section 8ce70a3
@rtyler rtyler Add a Fingerprints section to the Using chapter before I forget 4f79ee3
@rtyler rtyler Dump some Tools outline into the document e8c55ca
@rtyler rtyler Making a note of what needs to go into the Nodes section 1fe61f2
@rtyler rtyler Document basic usage of the Jenkins CLI over SSH and with the client f5e74f6
@rtyler rtyler Document "Configure Global Security" and its various options 56bed49
@rtyler rtyler Add some "work-in-progress" notes for the sections I don't plan on co…
…vering yet
f62c3ad
@rtyler rtyler Add a place-holder document for discussing the Jenkins Remote API 8b68829

Address all @bitwiseman's comments and he's got the plague this week.

@rtyler rtyler merged commit 3bc4bb9 into jenkins-infra:master Jan 9, 2017

1 check passed

continuous-integration/jenkins/pr-merge This commit looks good
Details
@rtyler rtyler deleted the rtyler:managing-jenkins-chapter branch Jan 9, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment