Blog post & documentation updates about WebSocket

content/_data/changelogs/weekly.yml

@@ -5925,6 +5925,8 @@
     references:
       - url: https://github.com/jenkinsci/jep/blob/master/jep/222/README.adoc
         title: JEP-222
+      - url: /blog/2020/02/02/web-socket/
+        title: blog post
     message: |-
       Add experimental WebSocket support.
   - type: rfe

content/blog/2020/02/2020-02-02-web-socket.adoc

@@ -0,0 +1,48 @@
+---
+layout: post
+title: 'WebSocket'
+tags:
+- core
+- remoting
+- agents
+- cli
+author: jglick
+---
+
+I am happy to report that jep:222[] has landed in Jenkins weeklies,
+starting in link:/changelog/#v2.217[2.217].
+This improvement brings experimental WebSocket support to Jenkins,
+available when connecting inbound agents or when running the CLI.
+The WebSocket protocol allows bidirectional, streaming communication over an HTTP(S) port.
+
+While many users of Jenkins could benefit,
+implementing this system was particularly important for CloudBees
+because of how link:https://docs.cloudbees.com/docs/cloudbees-core/latest/[CloudBees Core on modern cloud platforms]
+(i.e., running on Kubernetes) configures networking.
+When an administrator wishes to connect an inbound (formerly known as “JNLP”) external agent to a Jenkins master,
+such as a Windows virtual machine running outside the cluster and using the agent service wrapper,
+until now the only option was to use a special TCP port.
+This port needed to be opened to external traffic using low-level network configuration.
+For example, users of the nginx ingress controller
+would need to proxy a separate external port for each Jenkins service in the cluster.
+The instructions to do this are complex and hard to troubleshoot.
+
+Using WebSocket, inbound agents can now be connected much more simply when a reverse proxy is present:
+if the HTTP(S) port is already serving traffic,
+most proxies will allow WebSocket connections with no additional configuration.
+The WebSocket mode can be enabled in agent configuration,
+and support for pod-based agents in the plugin:kubernetes[Kubernetes plugin] is coming soon.
+You will need an agent link:https://github.com/jenkinsci/remoting/releases/tag/remoting-4.0[version 4.0] or later,
+which is bundled with Jenkins in the usual way (Docker images with this version are coming soon).
+
+Another part of Jenkins that was troublesome for reverse proxy users was the CLI.
+Besides the SSH protocol on port 22, which again was a hassle to open from the outside,
+the CLI already had the ability to link:/blog/2017/04/11/new-cli/[use HTTP(S) transport].
+Unfortunately the trick used to implement that confused some proxies and was not very portable.
+Jenkins 2.217 offers a new `-webSocket` CLI mode which should avoid these issues;
+again you will need to download a new version of `jenkins-cli.jar` to use this mode.
+
+The WebSocket code has been tested against a sample of Kubernetes implementations (including OpenShift),
+but it is likely that some bugs and limitations remain,
+and scalability of agents under heavy build loads has not yet been tested.
+Treat this feature as beta quality for now and let us know how it works!

content/doc/book/architecting-for-scale.adoc

@@ -120,6 +120,7 @@ with the actual Jenkins interface terminology
 ////
 TODO: This whole bullet point/section needs to be rewritten to be more
 clearly structured
+also terminology here is old (s/JNLP/inbound/g), and WebSocket should be mentioned
 ////
 * *The JNLP-TCP connector*: In this case the communication is established
   starting the agent through Java Web Start (JNLP). With this connector

content/doc/book/installing/_docker.adoc

@@ -154,6 +154,7 @@ value to 51000 (for example), then you would need to re-run Jenkins (via this
 Jenkins master and the first value is the port number on the Jenkins master's
 host machine through which the JNLP-based Jenkins agents communicate (to the
 Jenkins master) - i.e. 52000.
+Note that WebSocket agents in Jenkins 2.217 do not need this configuration.
 <8> Maps the `/var/jenkins_home` directory in the container to the Docker
 link:https://docs.docker.com/engine/admin/volumes/volumes/[volume] with the name
 `jenkins-data`. Instead of mapping the `/var/jenkins_home` directory to a Docker

content/doc/book/managing/cli.adoc

@@ -216,8 +216,8 @@ Summaries of other general options can be displayed by running the client with n
 
 === Client connection modes
 
-There are two basic modes in which the client may be used, selectable by global option:
-`-http` and `-ssh`.
+There are three basic modes in which the client may be used, selectable by global option:
+`-http`, `-webSocket`, and `-ssh`.
 
 ==== HTTP connection mode
 
@@ -275,6 +275,12 @@ mode where possible. See
 link:https://issues.jenkins-ci.org/browse/JENKINS-47279[JENKINS-47279].
 ====
 
+==== WebSocket connection mode
+
+In Jenkins 2.217 and above, the `-webSocket` mode may be used as an alternative to `-http`.
+The advantage is that a more standard transport is used,
+avoiding problems with many reverse proxies or the need for special proxy configuration.
+
 ==== SSH connection mode
 
 Authentication is via SSH keypair.

content/doc/book/managing/security.adoc

@@ -54,23 +54,23 @@ Jenkins environment.
 
 image::managing/configure-global-security-enable-security.png["Configure Global Security - Enable Security", role=center]
 
-=== JNLP TCP Port
+=== TCP Port
 
-Jenkins uses a TCP port to communicate with agents launched via the JNLP
-protocol, such as Windows-based agents. As of Jenkins 2.0, by default this port
-is disabled.
+Jenkins can use a TCP port to communicate with inbound (formerly known as “JNLP”) agents,
+such as Windows-based agents.
+As of Jenkins 2.0, by default this port is disabled.
 
-For administrators wishing to use JNLP-based agents, the two port options are:
+For administrators wishing to use inbound TCP agents, the two port options are:
 
 
-. *Random*: The JNLP port is chosen random to avoid collisions on the Jenkins
-  <<../glossary#master,master>>. The downside to randomized JNLP ports is that
-  they're chosen during the boot of the Jenkins master, making it difficult to
-  manage firewall rules allowing JNLP traffic.
-. *Fixed*: The JNLP port is chosen by the Jenkins administrator and is
-  consistent across reboots of the Jenkins master. This makes it easier to manage
-  firewall rules allowing JNLP-based agents to connect to the master.
+. *Random*: The TCP port is chosen at random to avoid collisions on the Jenkins <<../glossary#master,master>>.
+  The downside to randomized ports is that they are chosen during the boot of the Jenkins master,
+  making it difficult to manage firewall rules allowing TCP traffic.
+. *Fixed*: The port is chosen by the Jenkins administrator and is consistent across reboots of the Jenkins master.
+  This makes it easier to manage firewall rules allowing TCP-based agents to connect to the master.
 
+As of Jenkins 2.217, inbound agents may instead be configured to use WebSocket transport to connect to Jenkins.
+In this case no extra TCP port need be enabled and no special security configuration is needed.
 
 === Access Control