Merge pull request #3452 from oatmealraisin/rymurphy/jenkins-pipeline-svc

Added notice for setting up external jenkins

Author: ahardin-rh

architecture/core_concepts/builds_and_image_streams.adoc

@@ -137,11 +137,14 @@ Pipeline workflows are defined in a Jenkinsfile,
 either embedded directly in the build configuration,
 or supplied in a Git repository and referenced by the build configuration.
 
-The first time a project defines a build configuration using a Pipeline strategy,
-{product-title} instantiates a Jenkins server to execute the pipeline.
-Subsequent Pipeline build configurations
-in the project share this Jenkins server.  For more details on how the Jenkins
-server is deployed, see xref:../../install_config/configuring_pipeline_execution.adoc#overview[configuring pipeline execution].
+The first time a project defines a build configuration using a Pipeline
+strategy, {product-title} instantiates a Jenkins server to execute the
+pipeline.  Subsequent Pipeline build configurations in the project share this
+Jenkins server. 
+
+For more details on how the Jenkins server is deployed and how to configure or
+disable the autoprovisioning behavior, see
+xref:../../install_config/configuring_pipeline_execution.adoc#overview[configuring pipeline execution].
 
 [NOTE]
 ====

install_config/configuring_pipeline_execution.adoc

@@ -65,12 +65,25 @@ jenkinsPipelineConfig:
 <5> Optional values to pass to the template during instantiation.
 ====
 
-[IMPORTANT]
-====
-When a Pipeline build configuration is created,
-{product-title} instantiates the `*jenkinsPipelineConfig*` template *only if*
-no existing service name in the project matches the `*serviceName*` field.
-This means `*serviceName*` must be chosen such that it is unique in the project.
+When a Pipeline build configuration is created, {product-title} looks for a
+Service matching `*serviceName*`. This means `*serviceName*` must be chosen
+such that it is unique in the project. If no Service is found, {product-title}
+instantiates the `*jenkinsPipelineConfig*` template. If this is not desirable
+(if you would like to use a Jenkins server external to {product-title}, for
+example), there are a few things you can do, depending on who you are.
+
+* If you are a cluster administrator, simply set `*autoProvisionEnabled*` to `*false*`.
+  This will disable autoprovisioning across the cluster.
+* If you are an unpriviledged user, a Service must be created for {product-title}
+  to use. The service name must match the cluster configuration value of
+  `*serviceName*` in the `*jenkinsPipelineConfig*`. The default value is
+  `*jenkins*`. If you are disabling autoprovisioning because you are running a
+  Jenkins server outside your project, it is recommended that you point this new
+  service to your existing Jenkins server. See:
+xref:../dev_guide/integrating_external_services.adoc#dev-guide-integrating-external-services[Integrating External Services]
+
+The latter option could also be used to disable autoprovisioning in select
+projects only.
 ====
 
 // end::installconfig_configuring_pipeline_execution[]