Document imageLabels field in BuildConfigs

dev_guide/builds.adoc

@@ -2334,6 +2334,25 @@ Docker and Source builds set the following labels on output images:
 |Source URL for the build
 |===
 
+You can also use the `*BuildConfig.spec.output.imageLabels*` field to specify a
+list of custom labels that will be applied to each image built from the BuildConfig.
+
+.Custom labels to be applied to built images
+====
+[source,yaml]
+----
+output:
+  to:
+    kind: "ImageStreamTag"
+    name: "my-image:latest"
+  imageLabels:
+  - name: "vendor"
+    value: "MyCompany"
+  - name: "authoritative-source-url"
+    value: "registry.mycompany.com"
+----
+====
+
 [[using-external-artifacts]]
 == Using External Artifacts During a Build
 

install_config/build_defaults_overrides.adoc

@@ -30,16 +30,17 @@ new settings.
 
 The `*BuildDefaults*` admission control plug-in allows administrators to set
 global defaults for settings such as the Git HTTP and HTTPS proxy, as well as
-default environment variables. These defaults do not overwrite values that have
-been configured for a specific build. However, if those values are not present
-on the build definition, they are set to the default value.
+default environment variables and image labels. These defaults do not overwrite
+values that have been configured for a specific build. However, if those values
+are not present on the build definition, they are set to the default value.
 
 The `*BuildOverrides*` admission control plug-in allows administrators to
 override a setting in a build, regardless of the value stored in the build. It
 currently supports overriding the `*forcePull*` flag on a build strategy to
 enforce always refreshing the local image during a build by pulling the image
 from the registry. This ensures that a user can only build with an image that
-they are allowed to pull.
+they are allowed to pull. The plug-in can also be configured to apply a set of
+image labels to every built image.
 
 [[setting-global-build-defaults]]
 == Setting Global Build Defaults
@@ -128,6 +129,11 @@ kubernetesMasterConfig:
             value: https://my.proxy:8443
           - name: CUSTOM_VAR <6>
             value: custom_value
+          imageLabels:
+          - name: url <7>
+            value: https://containers.example.org
+          - name: vendor
+            value: ExampleCorp Ltd.
 ----
 <1> Sets the HTTP proxy to use when cloning source code from a Git repository.
 <2> Sets the HTTPS proxy to use when cloning source code from a Git repository.
@@ -140,6 +146,8 @@ build. This may be used for downloading dependencies during the assemble and
 build phases.
 <6> (Optional) Additional default environment variable that will be added to
 every build.
+<7> (Optional) Additional labels to be applied to every image built. Users can
+override these in their `*BuildConfig*`.
 ====
 
 Restart the master service for the changes to take effect:
@@ -167,9 +175,14 @@ kubernetesMasterConfig:
           apiVersion: v1
           kind: BuildOverridesConfig
           forcePull: true <1>
+          imageLabels:
+          - name: distribution-scope <2>
+            value: private
 ----
 <1> Force all builds to pull their builder image and any source images before
 starting the build.
+<2> (Optional) Additional labels to be applied to every image built. Labels
+defined here take precedence over labels defined in `*BuildConfig*`.
 ====
 
 Restart the master service for the changes to take effect: