Skip to content

Commit df0b970

Browse files
rolfedhrolfedh
committed
RHDEVDOCS-3570 Docs: Use sidecar pattern for Jenkins pod templates
1 parent 126dcc9 commit df0b970

File tree

5 files changed

+157
-23
lines changed

5 files changed

+157
-23
lines changed

‎modules/images-other-jenkins-config-kubernetes.adoc

Lines changed: 66 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
The {product-title} Jenkins image includes the pre-installed link:https://wiki.jenkins-ci.org/display/JENKINS/Kubernetes+Plugin[Kubernetes plug-in] that allows Jenkins agents to be dynamically provisioned on multiple container hosts using Kubernetes and {product-title}.
99

10-
To use the Kubernetes plug-in, {product-title} provides images that are suitable for use as Jenkins agents including the Base, Maven, and Node.js images.
10+
To use the Kubernetes plug-in, {product-title} provides images that are suitable for use as Jenkins agents, including the Base, Maven, and Node.js images.
1111

1212
Both the Maven and Node.js agent images are automatically configured as Kubernetes pod template images within the {product-title} Jenkins image configuration for the Kubernetes plug-in. That configuration includes labels for each of the images that can be applied to any of your Jenkins jobs under their Restrict where this project can be run setting. If the label is applied, jobs run under an {product-title} pod running the respective agent image.
1313

@@ -25,12 +25,12 @@ The name and image references of the image stream or image stream tag are mapped
2525

2626
[NOTE]
2727
====
28-
Do not log in to the Jenkins console and modify the pod template configuration. If you do so after the pod template is created, and the {product-title} Sync plug-in detects that the image associated with the image stream or image stream tag has changed, it replaces the pod template and overwrites those configuration changes. You cannot merge a new configuration with the existing configuration.
28+
Do not log in to the Jenkins console and change the pod template configuration. If you do so after the pod template is created, and the {product-title} Sync plug-in detects that the image associated with the image stream or image stream tag has changed, it replaces the pod template and overwrites those configuration changes. You cannot merge a new configuration with the existing configuration.
2929
3030
Consider the config map approach if you have more complex configuration needs.
3131
====
3232

33-
When it finds a config map with the appropriate label, it assumes that any values in the key-value data payload of the config map contains Extensible Markup Language (XML) that is consistent with the configuration format for Jenkins and the Kubernetes plug-in pod templates. A key differentiator to note when using config maps, instead of image streams or image stream tags, is that you can control all the parameters of the Kubernetes plug-in pod template.
33+
When it finds a config map with the appropriate label, it assumes that any values in the key-value data payload of the config map contain Extensible Markup Language (XML) that is consistent with the configuration format for Jenkins and the Kubernetes plug-in pod templates. One key benefit of using config maps, rather than image streams or image stream tags, is that you can control all the parameters of the Kubernetes plug-in pod template.
3434

3535
.Sample config map for `jenkins-agent`
3636
[source,yaml]
@@ -76,11 +76,72 @@ data:
7676
</org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
7777
----
7878

79+
The following example shows two containers that reference image streams that are present in the `openshift` namespace. One container handles the JNLP contract for launching Pods as Jenkins Agents. The other container uses an image with tools for building code in a particular coding language:
80+
81+
[source,yaml]
82+
----
83+
kind: ConfigMap
84+
apiVersion: v1
85+
metadata:
86+
name: jenkins-agent
87+
labels:
88+
role: jenkins-agent
89+
data:
90+
template2: |-
91+
<org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
92+
<inheritFrom></inheritFrom>
93+
<name>template2</name>
94+
<instanceCap>2147483647</instanceCap>
95+
<idleMinutes>0</idleMinutes>
96+
<label>template2</label>
97+
<serviceAccount>jenkins</serviceAccount>
98+
<nodeSelector></nodeSelector>
99+
<volumes/>
100+
<containers>
101+
<org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
102+
<name>jnlp</name>
103+
<image>image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base:latest</image>
104+
<privileged>false</privileged>
105+
<alwaysPullImage>true</alwaysPullImage>
106+
<workingDir>/home/jenkins/agent</workingDir>
107+
<command></command>
108+
<args>\$(JENKINS_SECRET) \$(JENKINS_NAME)</args>
109+
<ttyEnabled>false</ttyEnabled>
110+
<resourceRequestCpu></resourceRequestCpu>
111+
<resourceRequestMemory></resourceRequestMemory>
112+
<resourceLimitCpu></resourceLimitCpu>
113+
<resourceLimitMemory></resourceLimitMemory>
114+
<envVars/>
115+
</org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
116+
<org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
117+
<name>java</name>
118+
<image>image-registry.openshift-image-registry.svc:5000/openshift/java:latest</image>
119+
<privileged>false</privileged>
120+
<alwaysPullImage>true</alwaysPullImage>
121+
<workingDir>/home/jenkins/agent</workingDir>
122+
<command>cat</command>
123+
<args></args>
124+
<ttyEnabled>true</ttyEnabled>
125+
<resourceRequestCpu></resourceRequestCpu>
126+
<resourceRequestMemory></resourceRequestMemory>
127+
<resourceLimitCpu></resourceLimitCpu>
128+
<resourceLimitMemory></resourceLimitMemory>
129+
<envVars/>
130+
</org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
131+
</containers>
132+
<envVars/>
133+
<annotations/>
134+
<imagePullSecrets/>
135+
<nodeProperties/>
136+
</org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
137+
----
138+
139+
79140
[NOTE]
80141
====
81142
If you log in to the Jenkins console and make further changes to the pod template configuration after the pod template is created, and the {product-title} Sync plug-in detects that the config map has changed, it will replace the pod template and overwrite those configuration changes. You cannot merge a new configuration with the existing configuration.
82143
83-
Do not log in to the Jenkins console and modify the pod template configuration. If you do so after the pod template is created, and the {product-title} Sync plug-in detects that the image associated with the image stream or image stream tag has changed, it replaces the pod template and overwrites those configuration changes. You cannot merge a new configuration with the existing configuration.
144+
Do not log in to the Jenkins console and change the pod template configuration. If you do so after the pod template is created, and the {product-title} Sync plug-in detects that the image associated with the image stream or image stream tag has changed, it replaces the pod template and overwrites those configuration changes. You cannot merge a new configuration with the existing configuration.
84145
85146
Consider the config map approach if you have more complex configuration needs.
86147
====
@@ -94,4 +155,4 @@ The following rules apply:
94155
* Either creating appropriately labeled or annotated `ConfigMap`, `ImageStream`, or `ImageStreamTag` objects, or the adding of labels after their initial creation, leads to creating of a `PodTemplate` in the Kubernetes-plugin configuration.
95156
* In the case of the `PodTemplate` by config map form, changes to the config map data for the `PodTemplate` are applied to the `PodTemplate` settings in the Kubernetes plug-in configuration and overrides any changes that were made to the `PodTemplate` through the Jenkins UI between changes to the config map.
96157

97-
To use a container image as a Jenkins agent, the image must run the agent as an entrypoint. For more details about this, refer to the official https://wiki.jenkins-ci.org/display/JENKINS/Distributed+builds#Distributedbuilds-Launchslaveagentheadlessly[Jenkins documentation].
158+
To use a container image as a Jenkins agent, the image must run the agent as an entry point. For more details, see the official https://wiki.jenkins-ci.org/display/JENKINS/Distributed+builds#Distributedbuilds-Launchslaveagentheadlessly[Jenkins documentation].

‎modules/images-other-jenkins-create-service.adoc

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
Templates provide parameter fields to define all the environment variables with predefined default values. {product-title} provides templates to make creating a new Jenkins service easy. The Jenkins templates should be registered in the default `openshift` project by your cluster administrator during the initial cluster setup.
99

10-
The two available templates both define deployment configuration and a service. The templates differ in their storage strategy, which affects whether or not the Jenkins content persists across a pod restart.
10+
The two available templates both define deployment configuration and a service. The templates differ in their storage strategy, which affects whether the Jenkins content persists across a pod restart.
1111

1212
[NOTE]
1313
====
@@ -38,3 +38,12 @@ $ oc new-app jenkins-persistent
3838
----
3939
$ oc new-app jenkins-ephemeral
4040
----
41+
42+
With both templates, you can run `oc describe` on them to see all the parameters available for overriding.
43+
44+
For example:
45+
46+
[source,terminal]
47+
----
48+
$ oc describe jenkins-ephemeral
49+
----

‎modules/images-other-jenkins-env-var.adoc

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,16 +70,15 @@ By default, the JVM sets the initial heap size.
7070
|Default: `300000` - 5 minutes
7171

7272
|`OVERRIDE_PV_CONFIG_WITH_IMAGE_CONFIG`
73-
|When running this image with an {product-title} persistent volume (PV) for the Jenkins configuration directory, the transfer of configuration from the image to the PV is performed only the first time the image starts because the PV is assigned when the persistent volume claim (PVC) is created. If you create a custom image that extends this image and updates configuration in the custom image after the initial startup, the configuration is not copied over unless you set this environment variable to `true`.
73+
|When running this image with an {product-title} persistent volume (PV) for the Jenkins configuration directory, the transfer of configuration from the image to the PV is performed only the first time the image starts because the PV is assigned when the persistent volume claim (PVC) is created. If you create a custom image that extends this image and updates the configuration in the custom image after the initial startup, the configuration is not copied over unless you set this environment variable to `true`.
7474
|Default: `false`
7575

7676
|`OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS`
7777
|When running this image with an {product-title} PV for the Jenkins configuration directory, the transfer of plug-ins from the image to the PV is performed only the first time the image starts because the PV is assigned when the PVC is created. If you create a custom image that extends this image and updates plug-ins in the custom image after the initial startup, the plug-ins are not copied over unless you set this environment variable to `true`.
7878
|Default: `false`
7979

8080
|`ENABLE_FATAL_ERROR_LOG_FILE`
81-
|When running this image with an {product-title} PVC for the Jenkins configuration directory, this environment variable allows the fatal error
82-
log file to persist when a fatal error occurs. The fatal error file is saved at `/var/lib/jenkins/logs`.
81+
|When running this image with an {product-title} PVC for the Jenkins configuration directory, this environment variable allows the fatal error log file to persist when a fatal error occurs. The fatal error file is saved at `/var/lib/jenkins/logs`.
8382
|Default: `false`
8483

8584
|`NODEJS_SLAVE_IMAGE`
@@ -90,4 +89,20 @@ log file to persist when a fatal error occurs. The fatal error file is saved at
9089
|Setting this value overrides the image used for the default maven agent pod configuration. A related image stream tag named `jenkins-agent-maven` is in the project. This variable must be set before Jenkins starts the first time for it to have an effect.
9190
|Default Maven agent image in Jenkins server:
9291
`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-maven:latest`
92+
93+
|`AGENT_BASE_IMAGE`
94+
|Setting this value overrides the image used for the `jnlp` container in the sample Kubernetes plug-in pod templates provided with this image. Otherwise, the image from the `jenkins-agent-base:latest` image stream tag in the `openshift` namespace is used.
95+
|Default:
96+
`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base:latest`
97+
98+
|`JAVA_BUILDER_IMAGE`
99+
|Setting this value overrides the image used for the `java-builder` container in the `java-builder` sample Kubernetes plug-in pod templates provided with this image. Otherwise, the image from the `java:latest` image stream tag in the `openshift` namespace is used.
100+
|Default:
101+
`image-registry.openshift-image-registry.svc:5000/openshift/java:latest`
102+
103+
|`NODEJS_BUILDER_IMAGE`
104+
|Setting this value overrides the image used for the `nodejs-builder` container in the `nodejs-builder` sample Kubernetes plug-in pod templates provided with this image. Otherwise, the image from the `nodejs:latest` image stream tag in the `openshift` namespace is used.
105+
|Default:
106+
`image-registry.openshift-image-registry.svc:5000/openshift/nodejs:latest`
107+
93108
|===

‎modules/images-other-jenkins-kubernetes-plugin.adoc

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ items:
5454
- type: ConfigChange
5555
----
5656

57-
It is also possible to override the specification of the dynamically created Jenkins agent pod. The following is a modification to the previous example, which overrides the container memory and specifies an environment variable.
57+
It is also possible to override the specification of the dynamically created Jenkins agent pod. The following is a modification to the preceding example, which overrides the container memory and specifies an environment variable.
5858

5959
.Sample `BuildConfig` that the Jenkins Kubernetes Plug-in, specifying memory limit and environment variable
6060
[source,yaml]
@@ -100,3 +100,50 @@ spec:
100100
<9> The node stanza references the name of the defined pod template.
101101

102102
By default, the pod is deleted when the build completes. This behavior can be modified with the plug-in or within a pipeline Jenkinsfile.
103+
104+
Upstream Jenkins has more recently introduced a YAML declarative format for defining a `podTemplate` pipeline DSL in-line with your pipelines. An example of this format, using the sample `java-builder` pod template that is defined in the {product-title} Jenkins image:
105+
106+
[source,yaml]
107+
----
108+
def nodeLabel = 'java-buidler'
109+
110+
pipeline {
111+
agent {
112+
kubernetes {
113+
cloud 'openshift'
114+
label nodeLabel
115+
yaml """
116+
apiVersion: v1
117+
kind: Pod
118+
metadata:
119+
labels:
120+
worker: ${nodeLabel}
121+
spec:
122+
containers:
123+
- name: jnlp
124+
image: image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-base:latest
125+
args: ['\$(JENKINS_SECRET)', '\$(JENKINS_NAME)']
126+
- name: java
127+
image: image-registry.openshift-image-registry.svc:5000/openshift/java:latest
128+
command:
129+
- cat
130+
tty: true
131+
"""
132+
}
133+
}
134+
135+
options {
136+
timeout(time: 20, unit: 'MINUTES')
137+
}
138+
139+
stages {
140+
stage('Build App') {
141+
steps {
142+
container("java") {
143+
sh "mvn --version"
144+
}
145+
}
146+
}
147+
}
148+
}
149+
----

‎openshift_images/using_images/images-other-jenkins-agent.adoc

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,27 +5,29 @@ include::modules/common-attributes.adoc[]
55

66
toc::[]
77

8-
{product-title} provides three images that are suitable for use as Jenkins agents: the `Base`, `Maven`, and `Node.js` images.
8+
{product-title} provides Base, Maven, and Node.js images for use as Jenkins agents.
99

10-
The first is a base image for Jenkins agents:
10+
The Base image for Jenkins agents does the following:
1111

12-
* It pulls in both the required tools, headless Java, the Jenkins JNLP client, and the useful ones including `git`, `tar`, `zip`, and `nss` among others.
13-
* It establishes the JNLP agent as the entrypoint.
14-
* It includes the `oc` client tooling for invoking command line operations from within Jenkins jobs.
15-
* It provides Dockerfiles for both Red Hat Enterprise Linux (RHEL) and `localdev` images.
12+
* Pulls in both the required tools, headless Java, the Jenkins JNLP client, and the useful ones, including `git`, `tar`, `zip`, and `nss`, among others.
13+
* Establishes the JNLP agent as the entry point.
14+
* Includes the `oc` client tooling for invoking command line operations from within Jenkins jobs.
15+
* Provides Dockerfiles for both Red Hat Enterprise Linux (RHEL) and `localdev` images.
1616

17-
Two more images that extend the base image are also provided:
18-
19-
* Maven v3.5 image
20-
* Node.js v10 image and Node.js v12 image
21-
22-
The Maven and Node.js Jenkins agent images provide Dockerfiles for the Universal Base Image (UBI) that you can reference when building new agent images. Also note the `contrib` and `contrib/bin` subdirectories. They allow for the insertion of configuration files and executable scripts for your image.
17+
The Maven v3.5, Node.js v10, and Node.js v12 images extend the Base image. They provide Dockerfiles for the Universal Base Image (UBI) that you can reference when building new agent images. Also note the `contrib` and `contrib/bin` subdirectories, which enable you to insert configuration files and executable scripts for your image.
2318

2419
[IMPORTANT]
2520
====
26-
Use and extend an appropriate agent image version for the your of {product-title}. If the `oc` client version that is embedded in the agent image is not compatible with the {product-title} version, unexpected behavior can result.
21+
Use a version of the agent image that is appropriate for your {product-title} release version. Embedding an `oc` client version that is not compatible with the {product-title} version can cause unexpected behavior.
2722
====
2823

24+
The {product-title} Jenkins image also defines the following sample Pod templates to illustrate how you can use these agent images with the Jenkins Kubernetes plug-in:
25+
26+
- The `maven` pod template, which uses a single container that uses the {product-title} Maven Jenkins agent image.
27+
- The `nodejs` pod template, which uses a single container that uses the {product-title} Node.js Jenkins agent image.
28+
- The `java-builder` pod template, which employs two containers. One is the `jnlp` container, which uses the {product-title} Base agent image and handles the JNLP contract for starting and stopping Jenkins agents. The second is the `java` container which uses the `java` {product-title} Sample ImageStream, which contains the various Java binaries, including the Maven binary `mvn`, for building code.
29+
- The `nodejs-builder` pod template, which employs two containers. One is the `jnlp` container, which uses the {product-title} Base agent image and handles the JNLP contract for starting and stopping Jenkins agents. The second is the `nodejs` container which uses the `nodejs` {product-title} Sample ImageStream, which contains the various Node.js binaries, including the `npm` binary, for building code.
30+
2931
include::modules/images-other-jenkins-agent-images.adoc[leveloffset=+1]
3032

3133
include::modules/images-other-jenkins-agent-env-var.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)