diff --git a/_topic_map.yml b/_topic_map.yml index c02171560559..18ccd76e01da 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -362,6 +362,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..5b59e9a542c0 100644 --- a/modules/builds-build-custom-builder-image.adoc +++ b/modules/builds-build-custom-builder-image.adoc @@ -29,5 +29,5 @@ $ 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 +available in your project in an imagestreamtag 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 6dc1aa1bc442..1947c40f51a5 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..dabcb08878f0 --- /dev/null +++ b/modules/images-other-jenkins-agent-env-var.adoc @@ -0,0 +1,57 @@ +// 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 + +|`JAVA_MAX_HEAP_PARAM`, +`CONTAINER_HEAP_PERCENT` (default: `0.5`, or 50%), +`JENKINS_MAX_HEAP_UPPER_BOUND_MB` +|These values control the maximum heap size of the Jenkins JVM. If +`JAVA_MAX_HEAP_PARAM` is set (example setting: `-Xmx512m`), its value takes +precedence. Otherwise, the maximum heap size is dynamically calculated as +`CONTAINER_HEAP_PERCENT`% (example setting: `0.5`, or 50%) of the container +memory limit, optionally capped at `JENKINS_MAX_HEAP_UPPER_BOUND_MB` MiB +(example setting: `512`). + +By default, the maximum heap size of the Jenkins JVM is set to 50% of the +container memory limit with no cap. + +|`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 (example setting: `-Xms32m`), its value takes +precedence. Otherwise, the initial heap size may be dynamically calculated as +`CONTAINER_INITIAL_PERCENT`% (example setting: `0.1`, or 10%) of the +dynamically calculated maximum heap size. + +By default, the initial heap sizing is left to the JVM. + +|`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` (default: `-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true`) +|Specifies options to be heeded by all JVMs running in this container. It is not +recommended to override this. + +|`JAVA_GC_OPTS` (default: `-XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90`) +|Specifies Jenkins JVM garbage collection parameters. It is not recommended to +override this. + +|`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`. + +|=== diff --git a/modules/images-other-jenkins-agent-gradle.adoc b/modules/images-other-jenkins-agent-gradle.adoc new file mode 100644 index 000000000000..ff70dd8940d7 --- /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 these are specified. + + +The following settings are suggested as a starting point for running Gradle +builds in a memory constrained Jenkins agent on {product-title}. Settings may be +relaxed subsequently 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. +* Set `java { options.fork = false }` in the `build.gradle` file to prevent +Java compilations running out-of-process. +* 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 +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..35759b1b50b5 --- /dev/null +++ b/modules/images-other-jenkins-agent-images.adoc @@ -0,0 +1,37 @@ +// 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 come in two varieties: + +*RHEL 7 Based Images* + +RHEL 7 Jenkins images are available through the Red Hat Registry: + +---- +$ docker pull quay.io/openshift3/jenkins-agent-maven-35-rhel7 +$ docker pull quay.io/openshift3/jenkins-agent-nodejs-8-rhel7 +---- + +[NOTE] +==== +The RHEL 7 Jenkins images exist as an imagestram in {product-title}. +==== + +*CentOS 7 Based Images* + +These images are available on Docker Hub: + +---- +//$ docker pull openshift/jenkins-slave-base-centos7 +//$ docker pull openshift/jenkins-slave-maven-centos7 +//$ docker pull openshift/jenkins-slave-nodejs-centos7 +$ docker pull openshift/jenkins-agent-maven-35-centos7 +$ docker pull openshift/jenkins-agent-nodejs-8-centos7 +---- + +To use these images, you can either access them directly from these registries +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..1451b08516b2 --- /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, by default the Jenkins image dynamically uses a 32-bit +JVM if running in a container with a memory limit under 2GiB. 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 executed in the Jenkins agent container, such as +shell scripts or `oc` commands run from pipelines, may not be able to use more +than the remaining 50% memory limit without provoking an OOM kill. + +By default, each further JVM process run in a Jenkins agent container will use +up to 25% of the container memory limit for their heap. It may be necessary to +tune this 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..261726983ba6 --- /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 aborted. 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 may 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..891595ea86f3 --- /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 new Jenkins application using standard Jenkins authentication: + +---- +$ oc new-app -e \ + JENKINS_PASSWORD= \ + openshift/jenkins-2-centos7 +---- diff --git a/modules/images-other-jenkins-config-kubernetes.adoc b/modules/images-other-jenkins-config-kubernetes.adoc new file mode 100644 index 000000000000..a676a467c221 --- /dev/null +++ b/modules/images-other-jenkins-config-kubernetes.adoc @@ -0,0 +1,139 @@ +// 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 five images 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, +execution of the given job is done 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 within the project +that it is running, or the projects specifically listed in the plug-in's +configuration for the following: + +* 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 +running the container image 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] +==== +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 image associated with the ImageStream or ImageStreamTag has +changed, it will replace the Pod Template and overwrite those configuration +changes. No merging of configuration will occur. + +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 consistent +with the config 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 various fields of the +Kubernetes plug-in pod template. + +The following is an example ConfigMap: + +[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. No merging of configuration will occur. +==== + +Once 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: + +* Removal of the label or annotation from the `ConfigMap`, `ImageStream`, or +`ImageStreamTag` result 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 the creation of appropriately labeled or annotated `ConfigMap`, +`ImageStream`, or `ImageStreamTag` objects, or the adding of labels after their +initial creation, leads to the creation 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` is applied to the `PodTemplate` settings in the +Kubernetes plug-in configuration, and overrides any changes made to the +`PodTemplate` through the Jenkins UI in the interim 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..4092c955a74e --- /dev/null +++ b/modules/images-other-jenkins-create-service.adoc @@ -0,0 +1,51 @@ +// 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 +(password) with predefined defaults. {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 may 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 useful for development or testing only. + +* `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. + +Once you have selected which template you want, you must instantiate the +template to be able to use Jenkins. + +.Procedure + +. Ensure the default imagestreams and templates are already installed. + +. Create a new Jenkins application using: +.. 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..1d188f95d9ee --- /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 as a deployment within your +same project, you need to 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 needs to 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 # for example, jenkins-token-uyswp +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 field contains the token value Jenkins needs 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..8f8fbaf26931 --- /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 builder. + +You can use S2I to copy your custom Jenkins Jobs definitions, additional +plug-ins or replace the provided `config.xml` file with your own, custom, +configuration. + +In order to include your modifications in the Jenkins image, you need to 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: + +---- +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 +into the *_/var/lib/jenkins/_* directory, so you can also include +additional files, such as *_credentials.xml_*, there. + +The following is an example build configuration that 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` field defines the source Git repository +with the layout described above. +<2> The `strategy` field defines the original Jenkins image to use +as a source image for the build. +<3> The `output` field defines the resulting, customized Jenkins image +you can use in deployment configuration 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..c0c78aba5ea1 --- /dev/null +++ b/modules/images-other-jenkins-env-var.adoc @@ -0,0 +1,126 @@ +// 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 + +|`OPENSHIFT_ENABLE_OAUTH` (default: `false`) +|Determines whether the OpenShift Login plug-in manages authentication when +logging into Jenkins. To enable, set to `true`. + +|`JENKINS_PASSWORD` (default: `password`) +|The password for the `admin` user when using standard Jenkins authentication. +Not applicable when `OPENSHIFT_ENABLE_OAUTH` is set to `true`. + +|`JAVA_MAX_HEAP_PARAM`, +`CONTAINER_HEAP_PERCENT` (default: `0.5`, or 50%), +`JENKINS_MAX_HEAP_UPPER_BOUND_MB` +|These values control the maximum heap size of the Jenkins JVM. If +`JAVA_MAX_HEAP_PARAM` is set (example setting: `-Xmx512m`), its value takes +precedence. Otherwise, the maximum heap size is dynamically calculated as +`CONTAINER_HEAP_PERCENT`% (example setting: `0.5`, or 50%) of the container +memory limit, optionally capped at `JENKINS_MAX_HEAP_UPPER_BOUND_MB` MiB +(example setting: `512`). + +By default, the maximum heap size of the Jenkins JVM is set to 50% of the +container memory limit with no cap. + +|`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 (example setting: `-Xms32m`), its value takes +precedence. Otherwise, the initial heap size may be dynamically calculated as +`CONTAINER_INITIAL_PERCENT`% (example setting: `0.1`, or 10%) of the +dynamically calculated maximum heap size. + +By default, the initial heap sizing is left to the JVM. + +|`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` (default: `-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true`) +|Specifies options to be heeded by all JVMs running in this container. It is not +recommended to override this. + +|`JAVA_GC_OPTS` (default: `-XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90`) +|Specifies Jenkins JVM garbage collection parameters. It is not recommended to +override this. + +|`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` (see below). +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` (default: `300000` - 5 minutes) +|Specifies in milliseconds how often the OpenShift Login plug-in polls +{product-title} for the permissions associated with each user defined in Jenkins. + +|`OVERRIDE_PV_CONFIG_WITH_IMAGE_CONFIG` (default: `false`) +|When running this image with an {product-title} persistent volume for the Jenkins +config directory, the transfer of configuration from the image to the persistent +volume is only done the first startup of the image as the persistent volume is +assigned by the persistent volume claim creation. If you create a custom image +that extends this image and updates configuration in the custom image after +the initial startup, by default it is not copied over, unless you set this +environment variable to `true`. + +|`OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS` (default: `false`) +|When running this image with an {product-title} persistent volume for the Jenkins +config directory, the transfer of plugins from the image to the persistent +volume is only done the first startup of the image as the persistent volume is +assigned by the persistent volume claim creation. If you create a custom image +that extends this image and updates plugins in the custom image after +the initial startup, by default they are not copied over, unless you set this +environment variable to `true`. + +|`ENABLE_FATAL_ERROR_LOG_FILE` (default: `false`) +|When running this image with an {product-title} persistent claim for the Jenkins +config 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`. + +|`NODEJS_SLAVE_IMAGE` +|Setting this value overrides the image used for the default NodeJS agent pod +configuration. The default NodeJS agent image in Jenkins server is +`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-nodejs:latest`. +There is a related imagestreamtag named `jenkins-agent-nodejs` in the OpenShift +project. This variable must be set before Jenkins starts +the first time for it to have an effect. + +|`MAVEN_SLAVE_IMAGE` +|Setting this value overrides the image used for the default maven agent pod configuration. +The default maven agent image in Jenkins server is +`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-maven:latest`. +There is a related imagestreamtag named `jenkins-agent-maven` in the OpenShift +project.This variable must be set before Jenkins starts +the first time for it to have an effect. + +|`JENKINS_UC_INSECURE` +|Determines whether Jenkins plugins downloads are allowed if the Jenkins Update Center repository +uses an invalid SSL certificate. This could be the case if a self hosted repository +using self-signed certificate with an unknow CA is used or if an enteprise proxy +performs man-in-the-middle interceptions. This variable applies to plugins downloads which may +occur during Jenkins image build or if an extension of the Jenkins image is built or if you +run the Jenkins image and leverage one of the options to download additional plugins +(use of s2i whith plugins.txt or use of `INSTALL_PLUGINS` environment variable). +To enable, set to `true`. +|=== diff --git a/modules/images-other-jenkins-kubernetes-plugin.adoc b/modules/images-other-jenkins-kubernetes-plugin.adoc new file mode 100644 index 000000000000..f28996e608b0 --- /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, builds a WAR file, then causes a second BuildConfig, +`openshift-jee-sample-docker` to run to layer the newly created WAR file into a +container image. + +The following example is a BuildConfig using 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 above example which +overrides the container memory and specifies an environment variable: + +The following example is a BuildConfig using 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 on-the-fly. The new Pod +template name is referenced in the node stanza below. +<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, we inherit from the "maven" Pod template which is +pre-defined by {product-title}. +<4> We are overriding values in the pre-existing Container, therefore we must +specify it by name. All Jenkins agent images shipped with {product-title} use +the Container name `jnlp`. +<5> The Container image must be re-specified. This is a known issue. +<6> A memory request of 512Mi is specified. +<7> A memory limit of 512Mi is specified. +<8> An environment variable CONTAINER_HEAP_PERCENT, with value "0.25", is +specified. +<9> The node stanza references the name of the Pod template newly defined above. + +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..07401bf390d4 --- /dev/null +++ b/modules/images-other-jenkins-memory.adoc @@ -0,0 +1,24 @@ +// 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 512MiB. + +By default all other processes executed in the Jenkins +container, such as shell scripts or `oc` commands run locally from pipelines, are +not likely to be able to use more than the remaining 256MiB memory combined +without provoking an OOM kill. 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. As admin, defaults can be set on a +per-agent image basis through the Jenkins configuration. The memory request +and limit 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..be4a5c20291c --- /dev/null +++ b/modules/images-other-jenkins-oauth-auth.adoc @@ -0,0 +1,52 @@ +// 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 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 OpenShift 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. +ifdef::openshift-enterprise,openshift-origin,openshift-dedicated[] +For example, if `Allow All` is the default identity provider, you can provide +any non-empty string for both the user name and password. +endif::[] + +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, unless the {product-title} cluster administrator +explicitly defines that user in the {product-title} identity provider and +assigns the `admin` role to the user. +==== + +Jenkins' users permissions 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..f3a8c5f83bc3 --- /dev/null +++ b/modules/images-other-jenkins-permissions.adoc @@ -0,0 +1,38 @@ +// 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 mounted into the Pod, with permissions associated with the +service account, control which operations against the {product-title} master are +allowed from the Pod. + +Consider the following with service accounts used for the Pod, launched by the +Kubernetes Plug-in running in the {product-title} Jenkins image: + +If you use the example template for Jenkins provided by {product-title}, the +`jenkins` service account is defined with the `edit` role for the project +Jenkins is running in, and the master Jenkins Pod has that service account +mounted. + +The two default Maven and NodeJS Pod Templates injected into the Jenkins +configuration are also set to use the same service account as the master. + +* Any Pod Templates auto-discovered by the OpenShift Sync plug-in as +a result of imagestreams or imagestreamtags having the required label or +annotations have their service account set to the master's 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 +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. +* You need to 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..16f24e633a8e --- /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 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 CentOS and RHEL 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 both CentOS +and RHEL 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 version +of {product-title} that you are using. If the `oc` client version embedded in +the agent image is not compatible with the {product-title} version, unexpected +behavior may 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..a055688ff0f3 --- /dev/null +++ b/openshift_images/using_images/images-other-jenkins.adoc @@ -0,0 +1,79 @@ +[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* defined in {product-title}, tests the output of that build, and +then on successful build, retags the output to indicate 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 containing Jenkins 2.x. + +== Images + +The {product-title} Jenkins image comes in two varieties: + +*RHEL 7 Based Image* + +The RHEL 7 image is available through the Red Hat Registry: + +---- +$ docker pull quay.io/openshift4/jenkins-2-rhel7 +---- + +*CentOS 7 Based Image* + +This image is available on Docker Hub: + +---- +$ docker pull openshift/jenkins-2-centos7 +---- + +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] 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..b3601a405c05 --- /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-
` for 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` for the JBoss EAP +image. + +All Red Hat supported images covered in this book 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 6fe31c2d95ed..f9f4b0c932f9 100644 --- a/release_notes/ocp-4-1-release-notes.adoc +++ b/release_notes/ocp-4-1-release-notes.adoc @@ -649,7 +649,8 @@ features marked *GA* indicate _General Availability_. |- |- -|Image Streams with Kubernetes Resources +|ImageStreams with Kubernetes Resources +| |GA |GA