Add using images Jenkins and PR14030 follow-up

Author: bmcelvee

_topic_map.yml

@@ -406,6 +406,16 @@ Topics:
   File: using-templates
 - Name: Using Ruby on Rails
   File: templates-using-ruby-on-rails
+- Name: Using images
+  Dir: using_images
+  Distros: openshift-enterprise,openshift-origin
+  Topics:
+  - Name: Using images overview
+    File: using-images-overview
+  - Name: Configuring Jenkins images
+    File: images-other-jenkins
+  - Name: Jenkins agent 
+    File: images-other-jenkins-agent
 ---
 Name: Applications
 Dir: applications

modules/builds-build-custom-builder-image.adoc

@@ -28,6 +28,6 @@ $ oc new-build --binary --strategy=docker --name custom-builder-image
 $ oc start-build custom-builder-image --from-dir . -F
 ----
 +
-After the build completes, your new custom builder image will be
-available in your project in an imagestream tag named
+After the build completes, your new custom builder image is
+available in your project in an imagestreamtag that is named
 `custom-builder-image:latest`.

modules/builds-image-source.adoc

@@ -11,7 +11,7 @@
 
 You can add additional files to the build process with images. Input images are
 referenced in the same way the `From` and `To` image targets are defined. This
-means both container images and imagestream tags can be referenced. In
+means both container images and imagestreamtags can be referenced. In
 conjunction with the image, you must provide one or more path pairs to indicate
 the path of the files or directories to copy the image and the destination to
 place them in the build context.
@@ -67,6 +67,6 @@ endif::[]
 
 * Custom Strategy
 ifndef::openshift-online[]
-* ImageStream Tags
+* ImageStreamTags
 endif::[]
 /////

modules/builds-using-image-change-triggers.adoc

@@ -15,7 +15,7 @@ latest RHEL base image.
 ====
 Imagestreams that point to container images in
 link:http://docs.docker.com/v1.7/reference/api/hub_registry_spec/#docker-registry-1-0[v1
-container registries] only trigger a build once when the imagestream tag
+container registries] only trigger a build once when the imagestreamtag
 becomes available and not on subsequent image updates. This is due to the lack
 of uniquely identifiable images in v1 container registries.
 ====

modules/deployments-triggers.adoc

@@ -41,7 +41,7 @@ triggers:
 === ImageChange deployment triggers
 
 The `ImageChange` trigger results in a new ReplicationController whenever the
-content of an imagestream tag changes (when a new version of the image is
+content of an imagestreamtag changes (when a new version of the image is
 pushed).
 
 .ImageChange deployment trigger

modules/images-getting-info-about-imagestreams.adoc

@@ -38,7 +38,7 @@ Tags:			1
       About a minute ago
 ----
 
-* Get all the information available about particular imagestream tag:
+* Get all the information available about particular imagestreamtag:
 +
 ----
 $ oc describe istag/<image-stream>:<tag-name>

modules/images-imagestream-configure.adoc

@@ -46,6 +46,6 @@ status:
 
 <1> The name of the imagestream.
 <2> Docker repository path where new images can be pushed to add/update them in this imagestream.
-<3> The SHA identifier that this imagestream tag currently references. Resources that reference this imagestream tag use this identifier.
-<4> The SHA identifier that this imagestream tag previously referenced. Can be used to rollback to an older image.
-<5> The imagestream tag name.
+<3> The SHA identifier that this imagestreamtag currently references. Resources that reference this imagestreamtag use this identifier.
+<4> The SHA identifier that this imagestreamtag previously referenced. Can be used to rollback to an older image.
+<5> The imagestreamtag name.

modules/images-imagestream-import.adoc

@@ -2,7 +2,7 @@
 // * assembly/openshift_images
 
 [id="images-imagestreams-import_{context}"]
-= Configuring periodic importing of imagestream tags
+= Configuring periodic importing of imagestreamtags
 
 When working with an external container image registry, to periodically
 re-import an image, for example to get latest security updates, you can use the

modules/images-imagestream-remove-tag.adoc

@@ -2,7 +2,7 @@
 // * assembly/openshift_images
 
 [id="images-imagestreams-remove-tag_{context}"]
-= Removing imagestream tags
+= Removing imagestreamtags
 
 You can remove old tags from an imagestream.
 

modules/images-imagestream-tag.adoc

@@ -2,7 +2,7 @@
 // * assembly/openshift_images
 
 [id="images-imagestream-tag_{context}"]
-== Imagestream tags
+== Imagestreamtags
 
-An imagestream tag is a named pointer to an image in an imagestream. An image
+An imagestreamtag is a named pointer to an image in an imagestream. An image
 stream tag is similar to a container image tag.

modules/images-imagestream-trigger.adoc

@@ -4,7 +4,7 @@
 [id="image-stream-trigger_{context}"]
 = Imagestream triggers
 
-An imagestream trigger causes a specific action when an imagestream tag
+An imagestream trigger causes a specific action when an imagestreamtag
 changes. For example, importing can cause the value of the tag to change, which
 causes a trigger to fire when there are Deployments, Builds, or other resources
 listening for those.

modules/images-imagestream-update-tag.adoc

@@ -2,7 +2,7 @@
 // * assembly/openshift_images
 
 [id="images-imagestreams-update-tag_{context}"]
-= Updating imagestream tags
+= Updating imagestreamtags
 
 You can update a tag to reflect another tag in an imagestream.
 

modules/images-imagestream-use.adoc

@@ -20,7 +20,7 @@ For example, if a Deployment is using a certain image and a new version of that
 image is created, a Deployment could be automatically performed to pick up the
 new version of the image.
 
-However, if the imagestream tag used by the Deployment or Build is not updated,
+However, if the imagestreamtag used by the Deployment or Build is not updated,
 then even if the container image in the container image registry is updated, the
 Build or Deployment will continue using the previous, presumably known good
 image.
@@ -31,10 +31,10 @@ The source images can be stored in any of the following:
 * An external registry, for example `registry.redhat.io` or `hub.docker.com`.
 * Other imagestreams in the {product-title} cluster.
 
-When you define an object that references an imagestream tag (such as a Build
-or Deployment configuration), you point to an imagestream tag, not the Docker
+When you define an object that references an imagestreamtag (such as a Build
+or Deployment configuration), you point to an imagestreamtag, not the Docker
 repository. When you Build or Deploy your application, {product-title} queries
-the Docker repository using the imagestream tag to locate the associated ID of
+the Docker repository using the imagestreamtag to locate the associated ID of
 the image and uses that exact image.
 
 The imagestream metadata is stored in the etcd instance along with other
@@ -56,7 +56,7 @@ and/or Deployment flow, depending upon the Build or Deployment configuration.
 * You can share images using fine-grained access control and quickly distribute
 images across your teams.
 
-* If the source image changes, the imagestream tag will still point to a
+* If the source image changes, the imagestreamtag will still point to a
 known-good version of the image, ensuring that your application will not break
 unexpectedly.
 

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

@@ -0,0 +1,67 @@
+// Module included in the following assemblies:
+//
+// * images/using_images/images-other-jenkins-agent.adoc
+
+[id="images-other-jenkins-agent-env-var_{context}"]
+= Jenkins agent environment variables
+
+Each Jenkins agent container can be configured with the following environment
+variables.
+
+[options="header"]
+|===
+| Variable | Definition | Example values and settings
+
+|`JAVA_MAX_HEAP_PARAM`,
+`CONTAINER_HEAP_PERCENT`,
+`JENKINS_MAX_HEAP_UPPER_BOUND_MB`
+|These values control the maximum heap size of the Jenkins JVM. If
+`JAVA_MAX_HEAP_PARAM` is set, its value takes
+precedence. Otherwise, the maximum heap size is dynamically calculated as
+`CONTAINER_HEAP_PERCENT` of the container
+memory limit, optionally capped at `JENKINS_MAX_HEAP_UPPER_BOUND_MB` MiB.
+
+By default, the maximum heap size of the Jenkins JVM is set to 50% of the
+container memory limit with no cap.
+|`JAVA_MAX_HEAP_PARAM` example setting: `-Xmx512m`
+
+`CONTAINER_HEAP_PERCENT` default: `0.5`, or 50%
+
+`JENKINS_MAX_HEAP_UPPER_BOUND_MB` example setting: `512 MiB`
+
+|`JAVA_INITIAL_HEAP_PARAM`,
+`CONTAINER_INITIAL_PERCENT`
+|These values control the initial heap size of the Jenkins JVM. If
+`JAVA_INITIAL_HEAP_PARAM` is set, its value takes
+precedence. Otherwise, the initial heap size is dynamically calculated as
+`CONTAINER_INITIAL_PERCENT` of the
+dynamically calculated maximum heap size.
+
+By default, the JVM sets the initial heap size.
+|`JAVA_INITIAL_HEAP_PARAM` example setting: `-Xms32m`
+
+`CONTAINER_INITIAL_PERCENT` example setting: `0.1`, or 10%
+
+|`CONTAINER_CORE_LIMIT`
+|If set, specifies an integer number of cores used for sizing numbers of internal
+JVM threads.
+|Example setting: `2`
+
+|`JAVA_TOOL_OPTIONS`
+|Specifies options to apply to all JVMs running in this container. It is not
+recommended to override this value.
+|Default: `-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true`
+
+|`JAVA_GC_OPTS`
+|Specifies Jenkins JVM garbage collection parameters. It is not recommended to
+override this value.
+|Default: `-XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90`
+
+|`JENKINS_JAVA_OVERRIDES`
+|Specifies additional options for the Jenkins JVM. These options are appended to
+all other options, including the Java options above, and can be used to override
+any of them, if necessary. Separate each additional option with a space; if any
+option contains space characters, escape them with a backslash.
+|Example settings: `-Dfoo -Dbar`; `-Dfoo=first\ value -Dbar=second\ value`
+
+|===

modules/images-other-jenkins-agent-gradle.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * images/using_images/images-other-jenkins-agent.adoc
+
+[id="images-other-jenkins-agent-gradle_{context}"]
+= Jenkins agent Gradle builds
+
+Hosting Gradle builds in the Jenkins agent on {product-title} presents
+additional complications because in addition to the Jenkins JNLP agent and
+Gradle JVMs, Gradle spawns a third JVM to run tests if they are specified.
+
+
+The following settings are suggested as a starting point for running Gradle
+builds in a memory constrained Jenkins agent on {product-title}. You can modify
+these settings as required.
+
+* Ensure the long-lived Gradle daemon is disabled by adding
+`org.gradle.daemon=false` to the `gradle.properties` file.
+* Disable parallel build execution by ensuring `org.gradle.parallel=true` is not
+set in the `gradle.properties` file and that `--parallel` is not set as a command
+line argument.
+* To prevent Java compilations running out-of-process, set `java { options.fork =
+false }` in the `build.gradle` file .
+* Disable multiple additional test processes by ensuring
+`test { maxParallelForks = 1 }` is set in the `build.gradle` file.
+* Override the Gradle JVM memory parameters by the `GRADLE_OPTS`, `JAVA_OPTS` or
+`JAVA_TOOL_OPTIONS` environment.
+variables.
+* Set the maximum heap size and JVM arguments for any Gradle test JVM by defining
+the `maxHeapSize` and `jvmArgs` settings in `build.gradle`, or though the
+`-Dorg.gradle.jvmargs` command line argument.

modules/images-other-jenkins-agent-images.adoc

@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// * images/using_images/images-other-jenkins-agent.adoc
+
+[id="images-other-jenkins-agent-images_{context}"]
+= Jenkins agent images
+
+The {product-title} Jenkins agent images are available on `quay.io` or
+`registry.redhat.io`.
+
+Jenkins images are available through the Red Hat Registry:
+
+----
+$ docker pull regsitry.redhat.io/openshift4/ose-jenkins:<v4.1.4>
+$ docker pull regsitry.redhat.io/openshift4/ose-jenkins-agent-nodejs:<v4.1.4>
+$ docker pull regsitry.redhat.io/openshift4/ose-jenkins-agent-maven:<v4.1.4>
+$ docker pull regsitry.redhat.io/openshift4/ose-jenkins-agent-base:<v4.1.4>
+----
+
+To use these images, you can either access them directly from `quay.io` or
+`registry.redhat.io` or push them into your {product-title} container image
+registry.

modules/images-other-jenkins-agent-memory.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * images/using_images/images-other-jenkins-agent.adoc
+
+[id="images-other-jenkins-agent-memory_{context}"]
+= Jenkins agent memory requirements
+
+A JVM is used in all Jenkins agents to host the Jenkins JNLP agent as well as
+to run any Java applications such as `javac`, Maven, or Gradle.
+
+For memory efficiency, the Jenkins image dynamically uses a 32-bit
+JVM if it runs in a container with a memory limit under 2 GiB by default. The
+JVM choice applies by default both for the Jenkins JNLP agent as well as for any
+other Java processes within the agent container.
+
+By default, the Jenkins JNLP agent JVM uses 50% of the container memory limit for
+its heap. This value can be modified by the `CONTAINER_HEAP_PERCENT`
+environment variable. It can also be capped at an upper limit or overridden
+entirely.
+
+By default any other processes run in the Jenkins agent container, such as
+shell scripts or `oc` commands run from pipelines, cannot use more
+than the remaining 50% memory limit without provoking an OOM kill.
+
+By default, each further JVM process that runs in a Jenkins agent container uses
+up to 25% of the container memory limit for it's heap. It might be necessary to
+tune this limit for many build workloads.

modules/images-other-jenkins-agent-pod-retention.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * images/using_images/images-other-jenkins-agent.adoc
+
+[id="images-other-jenkins-agent-pod-retention_{context}"]
+= Jenkins agent pod retention
+
+Jenkins agent pods, also known as slave pods, are deleted by default after the
+build completes or is stopped. This behavior can be changed by the Kubernetes
+plug-in _Pod Retention_ setting. Pod retention can be set for all Jenkins
+builds, with overrides for each pod template. The following behaviors are
+supported:
+
+* `Always` keeps the build pod regardless of build result.
+* `Default` uses the plug-in value (pod template only).
+* `Never` always deletes the pod.
+* `On Failure` keeps the pod if it fails during the build.
+
+You can override pod retention in the pipeline Jenkinsfile:
+
+[source,groovy]
+----
+podTemplate(label: "mypod",
+  cloud: "openshift",
+  inheritFrom: "maven",
+  podRetention: onFailure(), <1>
+  containers: [
+    ...
+  ]) {
+  node("mypod") {
+    ...
+  }
+}
+----
+<1> Allowed values for `podRetention` are `never()`, `onFailure()`, `always()`,
+and `default()`.
+
+[WARNING]
+====
+Pods that are kept might continue to run and count against resource quotas.
+====

modules/images-other-jenkins-auth.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * images/using_images/images-other-jenkins.adoc
+
+[id="images-other-jenkins-auth_{context}"]
+= Jenkins authentication
+
+Jenkins authentication is used by default if the image is run directly, without
+using a template.
+
+The first time Jenkins starts, the configuration is created along with the
+administrator user and password. The default user credentials are `admin` and
+`password`. Configure the default password by setting the `JENKINS_PASSWORD`
+environment variable when using, and only when using, standard Jenkins
+authentication.
+
+.Procedure
+
+* Create a Jenkins application that uses standard Jenkins authentication:
++
+----
+$ oc new-app -e \
+    JENKINS_PASSWORD=<password> \
+    openshift4/ose-jenkins
+----