From 13fdc68051642ef8028e055f4ce21b63132910fb Mon Sep 17 00:00:00 2001 From: bmcelvee Date: Mon, 25 Mar 2019 16:16:59 -0400 Subject: [PATCH] Add using images Jenkins and PR14030 follow-up --- _topic_map.yml | 10 ++ .../builds-build-custom-builder-image.adoc | 4 +- modules/builds-image-source.adoc | 4 +- .../builds-using-image-change-triggers.adoc | 2 +- modules/deployments-triggers.adoc | 2 +- ...mages-getting-info-about-imagestreams.adoc | 2 +- modules/images-imagestream-configure.adoc | 6 +- modules/images-imagestream-import.adoc | 2 +- modules/images-imagestream-remove-tag.adoc | 2 +- modules/images-imagestream-tag.adoc | 4 +- modules/images-imagestream-trigger.adoc | 2 +- modules/images-imagestream-update-tag.adoc | 2 +- modules/images-imagestream-use.adoc | 10 +- .../images-other-jenkins-agent-env-var.adoc | 67 ++++++++ .../images-other-jenkins-agent-gradle.adoc | 31 ++++ .../images-other-jenkins-agent-images.adoc | 22 +++ .../images-other-jenkins-agent-memory.adoc | 27 ++++ ...ges-other-jenkins-agent-pod-retention.adoc | 41 +++++ modules/images-other-jenkins-auth.adoc | 25 +++ ...mages-other-jenkins-config-kubernetes.adoc | 150 ++++++++++++++++++ .../images-other-jenkins-create-service.adoc | 49 ++++++ .../images-other-jenkins-cross-project.adoc | 43 +++++ .../images-other-jenkins-customize-s2i.adoc | 71 +++++++++ modules/images-other-jenkins-env-var.adoc | 134 ++++++++++++++++ ...mages-other-jenkins-kubernetes-plugin.adoc | 118 ++++++++++++++ modules/images-other-jenkins-memory.adoc | 23 +++ modules/images-other-jenkins-oauth-auth.adoc | 48 ++++++ modules/images-other-jenkins-permissions.adoc | 39 +++++ modules/images-using-imagestream-tags.adoc | 36 ++--- .../quotas-sample-resource-quotas-def.adoc | 2 +- modules/templates-creating-from-console.adoc | 2 +- modules/templates-overview.adoc | 2 +- openshift_images/image-streams-manage.adoc | 2 +- .../images-other-jenkins-agent.adoc | 45 ++++++ .../using_images/images-other-jenkins.adoc | 75 +++++++++ .../using_images/using-images-overview.adoc | 32 ++++ release_notes/ocp-4-1-release-notes.adoc | 3 +- 37 files changed, 1095 insertions(+), 44 deletions(-) create mode 100644 modules/images-other-jenkins-agent-env-var.adoc create mode 100644 modules/images-other-jenkins-agent-gradle.adoc create mode 100644 modules/images-other-jenkins-agent-images.adoc create mode 100644 modules/images-other-jenkins-agent-memory.adoc create mode 100644 modules/images-other-jenkins-agent-pod-retention.adoc create mode 100644 modules/images-other-jenkins-auth.adoc create mode 100644 modules/images-other-jenkins-config-kubernetes.adoc create mode 100644 modules/images-other-jenkins-create-service.adoc create mode 100644 modules/images-other-jenkins-cross-project.adoc create mode 100644 modules/images-other-jenkins-customize-s2i.adoc create mode 100644 modules/images-other-jenkins-env-var.adoc create mode 100644 modules/images-other-jenkins-kubernetes-plugin.adoc create mode 100644 modules/images-other-jenkins-memory.adoc create mode 100644 modules/images-other-jenkins-oauth-auth.adoc create mode 100644 modules/images-other-jenkins-permissions.adoc create mode 100644 openshift_images/using_images/images-other-jenkins-agent.adoc create mode 100644 openshift_images/using_images/images-other-jenkins.adoc create mode 100644 openshift_images/using_images/using-images-overview.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 0cce92f3cf4a..a964d27e4814 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/modules/builds-build-custom-builder-image.adoc b/modules/builds-build-custom-builder-image.adoc index a3dc7f1ff3df..7006fc15c20a 100644 --- a/modules/builds-build-custom-builder-image.adoc +++ b/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`. diff --git a/modules/builds-image-source.adoc b/modules/builds-image-source.adoc index 89e6f7f3f6f4..76db8fc95dcf 100644 --- a/modules/builds-image-source.adoc +++ b/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::[] ///// diff --git a/modules/builds-using-image-change-triggers.adoc b/modules/builds-using-image-change-triggers.adoc index bf018c0984f8..fddb76d094b2 100644 --- a/modules/builds-using-image-change-triggers.adoc +++ b/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. ==== diff --git a/modules/deployments-triggers.adoc b/modules/deployments-triggers.adoc index d79a392b5b81..344aecc46ba8 100644 --- a/modules/deployments-triggers.adoc +++ b/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 diff --git a/modules/images-getting-info-about-imagestreams.adoc b/modules/images-getting-info-about-imagestreams.adoc index 549884a03159..9f6683736e5d 100644 --- a/modules/images-getting-info-about-imagestreams.adoc +++ b/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/: diff --git a/modules/images-imagestream-configure.adoc b/modules/images-imagestream-configure.adoc index 883d0ec4f7df..5b1c1606790e 100644 --- a/modules/images-imagestream-configure.adoc +++ b/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. diff --git a/modules/images-imagestream-import.adoc b/modules/images-imagestream-import.adoc index 53b25d7face7..386faab1b0ed 100644 --- a/modules/images-imagestream-import.adoc +++ b/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 diff --git a/modules/images-imagestream-remove-tag.adoc b/modules/images-imagestream-remove-tag.adoc index 2829418a9c0b..b29860cf1098 100644 --- a/modules/images-imagestream-remove-tag.adoc +++ b/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. diff --git a/modules/images-imagestream-tag.adoc b/modules/images-imagestream-tag.adoc index afb733645bda..ecb68b1c7752 100644 --- a/modules/images-imagestream-tag.adoc +++ b/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. diff --git a/modules/images-imagestream-trigger.adoc b/modules/images-imagestream-trigger.adoc index 04330d3316c0..996080cc2524 100644 --- a/modules/images-imagestream-trigger.adoc +++ b/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. diff --git a/modules/images-imagestream-update-tag.adoc b/modules/images-imagestream-update-tag.adoc index 2d1c66d87944..902e2eb2866b 100644 --- a/modules/images-imagestream-update-tag.adoc +++ b/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. diff --git a/modules/images-imagestream-use.adoc b/modules/images-imagestream-use.adoc index 874385ec9d36..21c273da2d8d 100644 --- a/modules/images-imagestream-use.adoc +++ b/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. diff --git a/modules/images-other-jenkins-agent-env-var.adoc b/modules/images-other-jenkins-agent-env-var.adoc new file mode 100644 index 000000000000..67035521870b --- /dev/null +++ b/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` + +|=== diff --git a/modules/images-other-jenkins-agent-gradle.adoc b/modules/images-other-jenkins-agent-gradle.adoc new file mode 100644 index 000000000000..f71c27bb9c3a --- /dev/null +++ b/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. diff --git a/modules/images-other-jenkins-agent-images.adoc b/modules/images-other-jenkins-agent-images.adoc new file mode 100644 index 000000000000..8994a8cd886b --- /dev/null +++ b/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: +$ docker pull regsitry.redhat.io/openshift4/ose-jenkins-agent-nodejs: +$ docker pull regsitry.redhat.io/openshift4/ose-jenkins-agent-maven: +$ docker pull regsitry.redhat.io/openshift4/ose-jenkins-agent-base: +---- + +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. diff --git a/modules/images-other-jenkins-agent-memory.adoc b/modules/images-other-jenkins-agent-memory.adoc new file mode 100644 index 000000000000..cb7e0a7ee9cf --- /dev/null +++ b/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. diff --git a/modules/images-other-jenkins-agent-pod-retention.adoc b/modules/images-other-jenkins-agent-pod-retention.adoc new file mode 100644 index 000000000000..012a61c1da00 --- /dev/null +++ b/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. +==== diff --git a/modules/images-other-jenkins-auth.adoc b/modules/images-other-jenkins-auth.adoc new file mode 100644 index 000000000000..f1c38dcd0f1d --- /dev/null +++ b/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= \ + openshift4/ose-jenkins +---- diff --git a/modules/images-other-jenkins-config-kubernetes.adoc b/modules/images-other-jenkins-config-kubernetes.adoc new file mode 100644 index 000000000000..caa2c4b8d307 --- /dev/null +++ b/modules/images-other-jenkins-config-kubernetes.adoc @@ -0,0 +1,150 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-config-kubernetes_{context}"] += Configuring the Jenkins Kubernetes plug-in + +The {product-title} Jenkins image includes the pre-installed +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}. + +To use the Kubernetes plug-in, {product-title} provides images that are suitable +for use as Jenkins agents: the `Base`, `Maven`, and `Node.js` images. + +Both the Maven and Node.js agent images are automatically configured as +Kubernetes Pod Template images within the {product-title} Jenkins image's +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. + +The Jenkins image also provides auto-discovery and auto-configuration of +additional agent images for the Kubernetes plug-in. + +With the {product-title} Sync plug-in, the Jenkins image on Jenkins start-up +searches for the following within the project that it is running or the +projects specifically listed in the plug-in's configuration: + +* Imagestreams that have the label `role` set to `jenkins-slave`. +* Imagestreamtags that have the annotation `role` set to `jenkins-slave`. +* ConfigMaps that have the label `role` set to `jenkins-slave`. + +When it finds an imagestream with the appropriate label, or imagestreamtag +with the appropriate annotation, it generates the corresponding Kubernetes +plug-in configuration so you can assign your Jenkins jobs to run in a Pod +that runs the container image that is provided by the imagestream. + +The name and image references of the imagestream or imagestreamtag are mapped +to the name and image fields in the Kubernetes plug-in Pod template. You can +control the label field of the Kubernetes plug-in Pod template by setting an +annotation on the imagestream or imagestreamtag object with the key +`slave-label`. Otherwise, the name is used as the label. + +[NOTE] +==== +Do not log into the Jenkins console and modify the Pod Template configuration. +If you do so after the Pod Template is created, and the OpenShift Sync plug-in +detects that the image associated with the ImageStream or ImageStreamTag has +changed, it replaces the Pod Template and overwrites those configuration +changes. You cannot merge a new configuration with the existing configuration. + +Consider the ConfigMap approach if you have more complex configuration needs. +==== + +When it finds a ConfigMap with the appropriate label, it assumes that any values +in the key-value data payload of the ConfigMap contains XML that is consistent +with the configuration format for Jenkins and the Kubernetes plug-in Pod +templates. A key differentiator to note when using ConfigMaps, instead of +imagestreams or imagestreamtags, is that you can control all the parameters +of the Kubernetes plug-in Pod template. + +Example ConfigMap for `jenkins-agent`: + +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: jenkins-agent + labels: + role: jenkins-slave +data: + template1: |- + + + template1 + 2147483647 + 0 + + jenkins + + + + + jnlp + openshift/jenkins-agent-maven-35-centos7:v3.10 + false + true + /tmp + + ${computer.jnlpmac} ${computer.name} + false + + + + + + + + + + + + +---- + +[NOTE] +==== +If you log into the Jenkins console and make further changes to the Pod Template +configuration after the Pod Template is created, and the OpenShift Sync plug-in +detects that the ConfigMap has changed, it will replace the Pod Template and +overwrite those configuration changes. You cannot merge a new configuration with +the existing configuration. + +Do not log into the Jenkins console and modify the Pod Template configuration. +If you do so after the Pod Template is created, and the OpenShift Sync plug-in +detects that the image associated with the ImageStream or ImageStreamTag has +changed, it replaces the Pod Template and overwrites those configuration +changes. You cannot merge a new configuration with the existing configuration. + +Consider the ConfigMap approach if you have more complex configuration needs. + +==== + +After it is installed, the OpenShift Sync plug-in monitors the API server of +{product-title} for updates to `ImageStreams`, `ImageStreamTags`, and +`ConfigMaps` and adjusts the configuration of the Kubernetes plug-in. + +The following rules apply: + +* Removing the label or annotation from the `ConfigMap`, `ImageStream`, or +`ImageStreamTag` results in the deletion of any existing `PodTemplate` from +the configuration of the Kubernetes plug-in. +* If those objects are removed, the corresponding configuration +is removed from the Kubernetes plug-in. +* 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. +* In the case of the `PodTemplate` by `ConfigMap` form, changes to the `ConfigMap` +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 `ConfigMap`. + +To use a container image as a Jenkins agent, the image must run the slave 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]. diff --git a/modules/images-other-jenkins-create-service.adoc b/modules/images-other-jenkins-create-service.adoc new file mode 100644 index 000000000000..3eaa7fcd6133 --- /dev/null +++ b/modules/images-other-jenkins-create-service.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-create-service_{context}"] += Creating a Jenkins service from a template + +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. + +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. + +[NOTE] +==== +A Pod might be restarted when it is moved to another node or when an update of +the deployment configuration triggers a redeployment. +==== + +* `jenkins-ephemeral` uses ephemeral storage. On Pod restart, all data is lost. +This template is only useful for development or testing. + +* `jenkins-persistent` uses a Persistent Volume store. Data survives a Pod +restart. + +To use a Persistent Volume store, the cluster administrator must define a +Persistent Volume pool in the {product-title} deployment. + +After you select which template you want, you must instantiate the +template to be able to use Jenkins. + +.Procedure + +. Create a new Jenkins application using one of the following methods: +** A Persistent Volume: ++ +---- +$ oc new-app jenkins-persistent +---- + +** Or an `emptyDir` type volume where configuration does not persist across Pod restarts: ++ +---- +$ oc new-app jenkins-ephemeral +---- diff --git a/modules/images-other-jenkins-cross-project.adoc b/modules/images-other-jenkins-cross-project.adoc new file mode 100644 index 000000000000..8fa2a90b2596 --- /dev/null +++ b/modules/images-other-jenkins-cross-project.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-cross-project_{context}"] += Providing Jenkins cross project access + +If you are going to run Jenkins somewhere other than your +same project, you must provide an access token to Jenkins to access your +project. + +.Procedure + +. Identify the secret for the service account that has appropriate permissions +to access the project Jenkins must access: ++ +---- +$ oc describe serviceaccount jenkins +Name: default +Labels: +Secrets: { jenkins-token-uyswp } + { jenkins-dockercfg-xcr3d } +Tokens: jenkins-token-izv1u + jenkins-token-uyswp +---- ++ +In this case the secret is named `jenkins-token-uyswp`. + +. Retrieve the token from the secret: ++ +---- +$ oc describe secret +Name: jenkins-token-uyswp +Labels: +Annotations: kubernetes.io/service-account.name=jenkins,kubernetes.io/service-account.uid=32f5b661-2a8f-11e5-9528-3c970e3bf0b7 +Type: kubernetes.io/service-account-token +Data +==== +ca.crt: 1066 bytes +token: eyJhbGc......wRA +---- ++ +The token parameter contains the token value Jenkins requires to access the project. diff --git a/modules/images-other-jenkins-customize-s2i.adoc b/modules/images-other-jenkins-customize-s2i.adoc new file mode 100644 index 000000000000..a4f2a400d44f --- /dev/null +++ b/modules/images-other-jenkins-customize-s2i.adoc @@ -0,0 +1,71 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-customize-s2i_{context}"] += Customizing the Jenkins image through Source-To-Image + +To customize the official {product-title} Jenkins image, you can use the image +as a Source-To-Image (S2I) builder. + +You can use S2I to copy your custom Jenkins Jobs definitions, add additional +plug-ins, or replace the provided `config.xml` file with your own, custom, +configuration. + +To include your modifications in the Jenkins image, you must have a +Git repository with the following directory structure: + +`plugins`:: +This directory contains those binary Jenkins plug-ins you want to copy into +Jenkins. + +`plugins.txt`:: +This file lists the plug-ins you want to install using the the following syntax: + +---- +pluginId:pluginVersion +---- + +`configuration/jobs`:: +This directory contains the Jenkins job definitions. + +`configuration/config.xml`:: +This file contains your custom Jenkins configuration. + +The contents of the `configuration/` directory is copied +to the `/var/lib/jenkins/` directory, so you can also include +additional files, such as `credentials.xml`, there. + +The following example build configuration customizes the Jenkins +image in {product-title}: + +[source,yaml] +---- +apiVersion: v1 +kind: BuildConfig +metadata: + name: custom-jenkins-build +spec: + source: <1> + git: + uri: https://github.com/custom/repository + type: Git + strategy: <2> + sourceStrategy: + from: + kind: ImageStreamTag + name: jenkins:2 + namespace: openshift + type: Source + output: <3> + to: + kind: ImageStreamTag + name: custom-jenkins:latest +---- + +<1> The `source` parameter defines the source Git repository +with the layout described above. +<2> The `strategy` parameter defines the original Jenkins image to use +as a source image for the build. +<3> The `output` parameter defines the resulting, customized Jenkins image that +you can use in deployment configurations instead of the official Jenkins image. diff --git a/modules/images-other-jenkins-env-var.adoc b/modules/images-other-jenkins-env-var.adoc new file mode 100644 index 000000000000..6ceea1aad519 --- /dev/null +++ b/modules/images-other-jenkins-env-var.adoc @@ -0,0 +1,134 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-env-var_{context}"] += Jenkins environment variables + +The Jenkins server can be configured with the following environment variables: + +[options="header"] +|=== +| Variable | Definition | Example values and settings + +|`OPENSHIFT_ENABLE_OAUTH` +|Determines whether the OpenShift Login plug-in manages authentication when +logging into Jenkins. To enable, set to `true`. +|Default: `false` + +|`JENKINS_PASSWORD` +|The password for the `admin` user when using standard Jenkins authentication. +Not applicable when `OPENSHIFT_ENABLE_OAUTH` is set to `true`. +|Default: `password` + +|`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 may 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`. + +|`JENKINS_OPTS` +|Specifies arguments to Jenkins. +| + +|`INSTALL_PLUGINS` +|Specifies additional Jenkins plug-ins to install when the container is first run +or when `OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS` is set to `true`. +Plug-ins are specified as a comma-delimited list of name:version pairs. +|Example setting: `git:3.7.0,subversion:2.10.2`. + +|`OPENSHIFT_PERMISSIONS_POLL_INTERVAL` +|Specifies the interval in milliseconds that the OpenShift Login plug-in polls +{product-title} for the permissions that are associated with each user that is +defined in Jenkins. +|Default: `300000` - 5 minutes + +|`OVERRIDE_PV_CONFIG_WITH_IMAGE_CONFIG` +|When running this image with an {product-title} persistent volume for the Jenkins +configuration directory, the transfer of configuration from the image to the Persistent +Volume is performed only the first time the image starts because the Persistent +Volume is assigned when the Persistent Volume Claim 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`. +|Default: `false` + +|`OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS` +|When running this image with an {product-title} persistent volume for the Jenkins +configuration directory, the transfer of plugins from the image to the Persistent +Volume is performed only the first time the image starts because the Persistent +Volume is assigned when the Persistent Volume Claim 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`. +|Default: `false` + +|`ENABLE_FATAL_ERROR_LOG_FILE` +|When running this image with an {product-title} Persistent Volume Claim 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`. +|Default: `false` + +|`NODEJS_SLAVE_IMAGE` +|Setting this value overrides the image that is used for the default NodeJS agent +Pod configuration. A related imagestreamtag named `jenkins-agent-nodejs` is in +in the project. This variable must be set before Jenkins starts the first time +for it to have an effect. +|Default NodeJS agent image in Jenkins server: +`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-nodejs:latest` + +|`MAVEN_SLAVE_IMAGE` +|Setting this value overrides the image used for the default maven agent Pod +configuration. A related imagestreamtag 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. +|Default Maven agent image in Jenkins server: +`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-maven:latest` +|=== diff --git a/modules/images-other-jenkins-kubernetes-plugin.adoc b/modules/images-other-jenkins-kubernetes-plugin.adoc new file mode 100644 index 000000000000..bbe0c058f79a --- /dev/null +++ b/modules/images-other-jenkins-kubernetes-plugin.adoc @@ -0,0 +1,118 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-kubernetes-plugin_{context}"] += Using the Jenkins Kubernetes plug-in + +In the following example, the `openshift-jee-sample` BuildConfig causes a +Jenkins Maven agent Pod to be dynamically provisioned. The Pod clones some Java +source code, builds a WAR file, and causes a second BuildConfig, +`openshift-jee-sample-docker` to run. The second BuildConfig layers the new WAR +file into a container image. + +The following example is a BuildConfig that uses the Jenkins Kubernetes plug-in. + +[source,yaml] +---- +kind: List +apiVersion: v1 +items: +- kind: ImageStream + apiVersion: v1 + metadata: + name: openshift-jee-sample +- kind: BuildConfig + apiVersion: v1 + metadata: + name: openshift-jee-sample-docker + spec: + strategy: + type: Docker + source: + type: Docker + dockerfile: |- + FROM openshift/wildfly-101-centos7:latest + COPY ROOT.war /wildfly/standalone/deployments/ROOT.war + CMD $STI_SCRIPTS_PATH/run + binary: + asFile: ROOT.war + output: + to: + kind: ImageStreamTag + name: openshift-jee-sample:latest +- kind: BuildConfig + apiVersion: v1 + metadata: + name: openshift-jee-sample + spec: + strategy: + type: JenkinsPipeline + jenkinsPipelineStrategy: + jenkinsfile: |- + node("maven") { + sh "git clone https://github.com/openshift/openshift-jee-sample.git ." + sh "mvn -B -Popenshift package" + sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war" + } + triggers: + - type: ConfigChange +---- + +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: + +The following example is a BuildConfig that the Jenkins Kubernetes Plug-in, +specifying memory limit and environment variable. + +[source,yaml] +---- +kind: BuildConfig +apiVersion: v1 +metadata: + name: openshift-jee-sample +spec: + strategy: + type: JenkinsPipeline + jenkinsPipelineStrategy: + jenkinsfile: |- + podTemplate(label: "mypod", <1> + cloud: "openshift", <2> + inheritFrom: "maven", <3> + containers: [ + containerTemplate(name: "jnlp", <4> + image: "openshift/jenkins-agent-maven-35-centos7:v3.10", <5> + resourceRequestMemory: "512Mi", <6> + resourceLimitMemory: "512Mi", <7> + envVars: [ + envVar(key: "CONTAINER_HEAP_PERCENT", value: "0.25") <8> + ]) + ]) { + node("mypod") { <9> + sh "git clone https://github.com/openshift/openshift-jee-sample.git ." + sh "mvn -B -Popenshift package" + sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war" + } + } + triggers: + - type: ConfigChange +---- +<1> A new Pod template called `mypod` is defined dynamically. The new Pod +template name is referenced in the node stanza. +<2> The `cloud` value must be set to `openshift`. +<3> The new Pod template can inherit its configuration from an existing Pod +template. In this case, inherited from the Maven Pod template that is +pre-defined by {product-title}. +<4> This example overrides values in the pre-existing Container, and must be +specified by name. All Jenkins agent images shipped with {product-title} use +the Container name `jnlp`. +<5> Specify the Container image name again. This is a known issue. +<6> A memory request of `512 Mi` is specified. +<7> A memory limit of `512 Mi` is specified. +<8> An environment variable `CONTAINER_HEAP_PERCENT`, with value `0.25`, is +specified. +<9> The node stanza references the name of the defined Pod template. + +By default, the pod is deleted when the build completes. This behavior can be +modified with the plug-in or within a pipeline Jenkinsfile. diff --git a/modules/images-other-jenkins-memory.adoc b/modules/images-other-jenkins-memory.adoc new file mode 100644 index 000000000000..4c97551bf042 --- /dev/null +++ b/modules/images-other-jenkins-memory.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-memory_{context}"] += Jenkins memory requirements + +When deployed by the provided Jenkins Ephemeral or Jenkins Persistent +templates, the default memory limit is `1 Gi`. + +By default, all other process that run in the Jenkins container cannot use more +than a total of `512 MiB` of memory. If they require more memory, the container +halts. It is therefore highly recommended that pipelines run external commands +in a agent container wherever possible. + +It is recommended to specify memory request and limit values on agent containers +created by the Jenkins Kubernetes Plug-in. Admin users can set default values on +a per-agent image basis through the Jenkins configuration. The memory request +and limit parameters can also be overridden on a per-container basis. + +You can increase the amount of memory available to Jenkins by overriding +the `MEMORY_LIMIT` parameter when instantiating the Jenkins Ephemeral or +Jenkins Persistent template. diff --git a/modules/images-other-jenkins-oauth-auth.adoc b/modules/images-other-jenkins-oauth-auth.adoc new file mode 100644 index 000000000000..c862800e5442 --- /dev/null +++ b/modules/images-other-jenkins-oauth-auth.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-oauth-auth_{context}"] += {product-title} OAuth authentication + +OAuth authentication is activated by configuring options on the *Configure +Global Security* panel in the Jenkins UI, or by setting the +`OPENSHIFT_ENABLE_OAUTH` environment variable on the Jenkins *Deployment +configuration* to anything other than `false`. This activates the {product-title} +Login plug-in, which retrieves the configuration information from Pod data or by +interacting with the {product-title} API server. + +Valid credentials are controlled by the {product-title} identity provider. + +Jenkins supports both browser and non-browser access. + +Valid users are automatically added to the Jenkins authorization matrix at log +in, where {product-title} `Roles` dictate the specific Jenkins permissions the +users have. + +Users with the `admin` role have the traditional Jenkins administrative +user permissions. Users with the `edit` or `view` role have progressively +fewer permissions. + +[NOTE] +==== +The `admin` user that is pre-populated in the {product-title} Jenkins image with +administrative privileges is not given those privileges when +{product-title} OAuth is used. To grant these permissions the {product-title} +cluster administrator must explicitly define that user in the {product-title} +identity provider and assigs the `admin` role to the user. +==== + +Jenkins users' permissions that are stored can be changed after the users are +initially established. The OpenShift Login plug-in polls the {product-title} API +server for permissions and updates the permissions stored in Jenkins for each +user with the permissions retrieved from {product-title}. If the Jenkins UI is +used to update permissions for a Jenkins user, the permission changes are +overwritten the next time the plug-in polls {product-title}. + +You can control how often the polling occurs with the +`OPENSHIFT_PERMISSIONS_POLL_INTERVAL` environment variable. The default polling +interval is five minutes. + +The easiest way to create a new Jenkins service using OAuth authentication is to +use a template. diff --git a/modules/images-other-jenkins-permissions.adoc b/modules/images-other-jenkins-permissions.adoc new file mode 100644 index 000000000000..eb1668e71577 --- /dev/null +++ b/modules/images-other-jenkins-permissions.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * images/using_images/images-other-jenkins.adoc + +[id="images-other-jenkins-permissions_{context}"] += Jenkins permissions + +If in the ConfigMap the `` element of the Pod Template XML is +the {product-title} Service Account used for the resulting Pod, the service +account credentials are mounted into the Pod. The permissions are associated +with the service account and control which operations against the +{product-title} master are allowed from the Pod. + +Consider the following scenario with service accounts used for the Pod, which +is launched by the Kubernetes Plug-in that runs in the {product-title} Jenkins +image: + +If you use the example template for Jenkins that is provided by {product-title}, +the `jenkins` service account is defined with the `edit` role for the project +Jenkins runs in, and the master Jenkins Pod has that service account +mounted. + +The two default Maven and NodeJS Pod Templates that are injected into the Jenkins +configuration are also set to use the same service account as the Jenkins master. + +* Any Pod templates that are automatically discovered by the OpenShift Sync +plug-in because their imagestreams or imagestreamtags have the required label or +annotations are configured to use the Jenkins master's service account as their +service account. +* For the other ways you can provide a Pod Template definition into Jenkins and +the Kubernetes plug-in, you have to explicitly specify the service account to +use. Those other ways include the Jenkins console, the `podTemplate` pipeline DSL +that is provided by the Kubernetes plug-in, or labeling a ConfigMap whose data +is the XML configuration for a Pod Template. +* If you do not specify a value for the service account, the `default` service +account is used. +* Ensure that whatever service account is used has the necessary +permissions, roles, and so on defined within {product-title} to manipulate +whatever projects you choose to manipulate from the within the Pod. diff --git a/modules/images-using-imagestream-tags.adoc b/modules/images-using-imagestream-tags.adoc index d3b1f60f500d..222aba0726ad 100644 --- a/modules/images-using-imagestream-tags.adoc +++ b/modules/images-using-imagestream-tags.adoc @@ -2,13 +2,13 @@ // * assembly/openshift_images [id="images-using-imagestream-tags_{context}"] -= Imagestream tags += Imagestreamtags -An imagestream tag is a named pointer to an image in an _imagestream_. It is -often abbreviated as _istag_. An imagestream tag is used to reference or +An imagestreamtag is a named pointer to an image in an _imagestream_. It is +often abbreviated as _istag_. An imagestreamtag is used to reference or retrieve an image for a given imagestream and tag. -Imagestream tags can reference any local or externally managed image. It +Imagestreamtags can reference any local or externally managed image. It contains a history of images represented as a stack of all images the tag ever pointed to. Whenever a new or existing image is tagged under particular image stream tag, it is placed at the first position in the history stack. The image @@ -16,9 +16,9 @@ previously occupying the top position will be available at the second position, and so forth. This allows for easy rollbacks to make tags point to historical images again. -The following imagestream tag is from an imagestream object: +The following imagestreamtag is from an imagestream object: -.Imagestream tag with two images in its history +.Imagestreamtag with two images in its history [source,yaml] ---- @@ -35,28 +35,28 @@ The following imagestream tag is from an imagestream object: tag: latest ---- -Imagestream tags can be _permanent_ tags or _tracking_ tags. +Imagestreamtags can be _permanent_ tags or _tracking_ tags. * _Permanent tags_ are version-specific tags that point to a particular version of an image, such as Python 3.5. -* _Tracking tags_ are reference tags that follow another imagestream tag and +* _Tracking tags_ are reference tags that follow another imagestreamtag and could be updated in the future to change which image they follow, much like a symlink. Note that these new levels are not guaranteed to be backwards-compatible. + -For example, the `latest` imagestream tags that ship with {product-title} are -tracking tags. This means consumers of the `latest` imagestream tag will be +For example, the `latest` imagestreamtags that ship with {product-title} are +tracking tags. This means consumers of the `latest` imagestreamtag will be updated to the newest level of the framework provided by the image when a new -level becomes available. A `latest` imagestream tag to `v3.10` could be changed +level becomes available. A `latest` imagestreamtag to `v3.10` could be changed to `v3.11` at any time. It is important to be aware that these `latest` image stream tags behave differently than the Docker `latest` tag. The `latest` image stream tag, in this case, does not point to the latest image in the Docker -repository. It points to another imagestream tag, which might not be the latest -version of an image. For example, if the `latest` imagestream tag points to +repository. It points to another imagestreamtag, which might not be the latest +version of an image. For example, if the `latest` imagestreamtag points to `v3.10` of an image, when the `3.11` version is released, the `latest` tag is not automatically updated to `v3.11`, and remains at `v3.10` until it is -manually updated to point to a `v3.11` imagestream tag. +manually updated to point to a `v3.11` imagestreamtag. + [NOTE] ==== @@ -64,18 +64,18 @@ Tracking tags are limited to a single imagestream and cannot reference other imagestreams. ==== -You can create your own imagestream tags for your own needs. +You can create your own imagestreamtags for your own needs. -The imagestream tag is composed of the name of the imagestream and a tag, +The imagestreamtag is composed of the name of the imagestream and a tag, separated by a colon: ---- -: +: ---- For example, to refer to the `sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d` image -in the imagestream object example earlier, the imagestream tag +in the imagestream object example earlier, the imagestreamtag would be: ---- diff --git a/modules/quotas-sample-resource-quotas-def.adoc b/modules/quotas-sample-resource-quotas-def.adoc index 11af856d8379..1ab993586d7e 100644 --- a/modules/quotas-sample-resource-quotas-def.adoc +++ b/modules/quotas-sample-resource-quotas-def.adoc @@ -40,7 +40,7 @@ spec: hard: openshift.io/imagestreams: "10" <1> ---- -<1> The total number of image streams that can exist in the project. +<1> The total number of imagestreams that can exist in the project. .`compute-resources.yaml` [source,yaml] diff --git a/modules/templates-creating-from-console.adoc b/modules/templates-creating-from-console.adoc index 36532cbcd383..143d51d71ec3 100644 --- a/modules/templates-creating-from-console.adoc +++ b/modules/templates-creating-from-console.adoc @@ -16,7 +16,7 @@ from the service catalog. + [NOTE] ==== -Only imagestream tags that have the *builder* tag listed in their annotations +Only imagestreamtags that have the *builder* tag listed in their annotations appear in this list, as demonstrated here: ==== + diff --git a/modules/templates-overview.adoc b/modules/templates-overview.adoc index 5c6f0eff54e4..d8242b0f4701 100644 --- a/modules/templates-overview.adoc +++ b/modules/templates-overview.adoc @@ -18,5 +18,5 @@ global template library, using the web console. //.Additional resources //For a curated set of templates, see the -//link:https://github.com/openshift/library[OpenShift Image Streams and Templates +//link:https://github.com/openshift/library[OpenShift ImageStreams and Templates //library]. diff --git a/openshift_images/image-streams-manage.adoc b/openshift_images/image-streams-manage.adoc index e0c33221597d..c8f45e737df2 100644 --- a/openshift_images/image-streams-manage.adoc +++ b/openshift_images/image-streams-manage.adoc @@ -22,7 +22,7 @@ include::modules/images-imagestream-mapping.adoc[leveloffset=+1] == Working with imagestreams -The following sections describe how to use imagestreams and imagestream tags. +The following sections describe how to use imagestreams and imagestreamtags. include::modules/images-getting-info-about-imagestreams.adoc[leveloffset=+2] include::modules/images-imagestream-adding-tags.adoc[leveloffset=+2] diff --git a/openshift_images/using_images/images-other-jenkins-agent.adoc b/openshift_images/using_images/images-other-jenkins-agent.adoc new file mode 100644 index 000000000000..a3d6a2aaadde --- /dev/null +++ b/openshift_images/using_images/images-other-jenkins-agent.adoc @@ -0,0 +1,45 @@ +[id="images-other-jenkins-agent"] += Jenkins agent +include::modules/common-attributes.adoc[] +:context: images-other-jenkins-agent +toc::[] + +{product-title} provides three images that suitable for use as Jenkins agents: +the *_Base_*, *_Maven_*, and *_Node.js_* images. + +The first is a base image for Jenkins agents: + +* 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. +* It establishes the JNLP agent as the entrypoint. +* It includes the `oc` client tooling for invoking command line operations from + within Jenkins jobs. +* It provides Dockerfiles for both Red Hat Enterprise Linux (RHEL) and `localdev` images. + +Two more images that extend the base image are also provided: + +* Maven v3.5 image +* Node.js v8 image + +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. + +[IMPORTANT] +==== +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. +==== + +include::modules/images-other-jenkins-agent-images.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-agent-env-var.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-agent-memory.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-agent-gradle.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-agent-pod-retention.adoc[leveloffset=+1] diff --git a/openshift_images/using_images/images-other-jenkins.adoc b/openshift_images/using_images/images-other-jenkins.adoc new file mode 100644 index 000000000000..1838571c10bb --- /dev/null +++ b/openshift_images/using_images/images-other-jenkins.adoc @@ -0,0 +1,75 @@ +[id="images-other-jenkins"] += Configuring Jenkins images +include::modules/common-attributes.adoc[] +:context: images-other-jenkins +toc::[] + +{product-title} provides a container image for running Jenkins. This image +provides a Jenkins server instance, which can be used to set up a basic flow for +continuous testing, integration, and delivery. + +This image also includes a sample Jenkins job, which triggers a new build of a +BuildConfig that is defined in {product-title}, tests the output of that build, +and then on successful build, retags the output to indicate that the build is ready +for production. + +{product-title} follows the link:https://jenkins.io/changelog-stable/[LTS] +release of Jenkins. {product-title} provides an image that contains Jenkins 2.x. + +The {product-title} Jenkins 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: +---- + +To use these images, you can either access them directly from these registries +or push them into your {product-title} container image registry. Additionally, +you can create an ImageStream that points to the image, either in your container +image registry or at the external location. Your {product-title} resources can +then reference the ImageStream. + +== Configuration and customization + +You can manage Jenkins authentication in two ways: + +* {product-title} OAuth authentication provided by the OpenShift Login +plug-in. +* Standard authentication provided by Jenkins. + +include::modules/images-other-jenkins-oauth-auth.adoc[leveloffset=+2] + +include::modules/images-other-jenkins-auth.adoc[leveloffset=+2] + +include::modules/images-other-jenkins-env-var.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-cross-project.adoc[leveloffset=+1] + +== Jenkins cross volume mount points + +The Jenkins image can be run with mounted volumes to enable persistent storage +for the configuration: + +* `/var/lib/jenkins` - This is the data directory where Jenkins stores +configuration files, including job definitions. + +include::modules/images-other-jenkins-customize-s2i.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-config-kubernetes.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-permissions.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-create-service.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-kubernetes-plugin.adoc[leveloffset=+1] + +include::modules/images-other-jenkins-memory.adoc[leveloffset=+1] + +== Additional Resources + +* See xref:../../architecture/understanding-development.adoc#base-image-options[Base +image options] for more information on the +link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/getting_started_with_containers/index#using_red_hat_base_container_images_standard_and_minimal[Red +Hat Universal Base Images] (UBI). diff --git a/openshift_images/using_images/using-images-overview.adoc b/openshift_images/using_images/using-images-overview.adoc new file mode 100644 index 000000000000..ba5bf9291ad9 --- /dev/null +++ b/openshift_images/using_images/using-images-overview.adoc @@ -0,0 +1,32 @@ +[id="using-images-overview"] += Using images overview +include::modules/common-attributes.adoc[] +:context: using-images-overview +toc::[] + +Use the following topics to discover the different Source-to-Image (S2I), +database, and other container images that are available for {product-title} +users. + +Red Hat’s official container images are provided in the Red Hat Registry at +link:registry.redhat.io[registry.redhat.io]. {product-title}’s supported S2I, +database, and Jenkins images are provided in the `openshift4` repository in the +Red Hat Quay Registry. For example, +`quay.io/openshift-release-dev/ocp-v4.0-
` is the name of the OpenShift +Application Platform image. + +The xPaaS middleware images are provided in their respective product +repositories on the Red Hat Registry but suffixed with a `-openshift`. For +example, `registry.redhat.io/jboss-eap-6/eap64-openshift` is the name of the +JBoss EAP image. + +All Red Hat supported images covered in this section are described in the Red Hat +Container Catalog. For every version of each image, you can find details on its +contents and usage. Browse or search for the image that interests you. + +[IMPORTANT] +==== +The newer versions of container images are not compatible with earlier versions +of {product-title}. Verify and use the correct version of container images, +based on your version of {product-title}. +==== diff --git a/release_notes/ocp-4-1-release-notes.adoc b/release_notes/ocp-4-1-release-notes.adoc index 005b7224f3f7..46ed49f88684 100644 --- a/release_notes/ocp-4-1-release-notes.adoc +++ b/release_notes/ocp-4-1-release-notes.adoc @@ -658,7 +658,8 @@ features marked *GA* indicate _General Availability_. |- |- -|Image Streams with Kubernetes Resources +|ImageStreams with Kubernetes Resources +| |GA |GA