Merge pull request #14989 from bmcelvee/build-image-config

Document build and image configuration resources

_topic_map.yml

@@ -326,6 +326,9 @@ Topics:
 - Name: Securing builds by strategy
   File: securing-builds-by-strategy
   Distros: openshift-enterprise,openshift-origin
+- Name: Build configuration resources
+  File: build-configuration
+  Distros: openshift-enterprise,openshift-origin
 - Name: Troubleshooting builds
   File: troubleshooting-builds
   Distros: openshift-enterprise,openshift-origin
@@ -344,6 +347,9 @@ Topics:
   File: create-images
 - Name: Managing imagestreams
   File: image-streams-manage
+- Name: Image configuration resources
+  File: image-configuration
+  Distros: openshift-enterprise,openshift-origin
 - Name: Using templates
   File: using-templates
 - Name: Using Ruby on Rails

builds/build-configuration.adoc

@@ -0,0 +1,11 @@
+[id="build-configuration"]
+= Build configuration resources
+include::modules/common-attributes.adoc[]
+:context: build-configuration
+toc::[]
+
+Use the following procedure to configure build settings.
+
+include::modules/builds-configuration-parameters.adoc[leveloffset=+1]
+
+include::modules/builds-configuration-file.adoc[leveloffset=+1]

modules/builds-configuration-file.adoc

@@ -0,0 +1,87 @@
+// Module included in the following assemblies:
+//
+// * builds/build-configuration.adoc
+
+[id="builds-configuration-file_{context}"]
+= Configuring build settings
+
+You can configure build settings by editing the
+`build.config.openshift.io/cluster` resource.
+
+.Procedure
+
+* Edit the `build.config.openshift.io/cluster` resource:
++
+----
+$ oc edit build.config.openshift.io/cluster
+----
++
+The following is an example `build.config.openshift.io/cluster` resource:
++
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Build<1>
+metadata:
+  annotations:
+    release.openshift.io/create-only: "true"
+  creationTimestamp: "2019-05-17T13:44:26Z"
+  generation: 2
+  name: cluster
+  resourceVersion: "107233"
+  selfLink: /apis/config.openshift.io/v1/builds/cluster
+  uid: e2e9cc14-78a9-11e9-b92b-06d6c7da38dc
+spec:
+  buildDefaults:<2>
+    defaultProxy:<3>
+      httpProxy: http://proxy.com
+      httpsProxy: https://proxy.com
+      noProxy: internal.com
+    env:<4>
+    - name: envkey
+      value: envvalue
+    gitProxy:<5>
+      httpProxy: http://gitproxy.com
+      httpsProxy: https://gitproxy.com
+      noProxy: internalgit.com
+    imageLabels:<6>
+    - name: labelkey
+      value: labelvalue
+    resources:<7>
+      limits:
+        cpu: 100m
+        memory: 50Mi
+      requests:
+        cpu: 10m
+        memory: 10Mi
+  buildOverrides:<8>
+    imageLabels:<9>
+    - name: labelkey
+      value: labelvalue
+    nodeSelector:<10>
+      selectorkey: selectorvalue
+    tolerations:<11>
+    - effect: NoSchedule
+      key: node-role.kubernetes.io/builds
+operator: Exists
+----
+<1> `Build`: Holds cluster-wide information on how to handle builds. The
+canonical, and only valid name is `cluster`.
+<2> `buildDefaults`: Controls the default information for builds.
+<3> `defaultProxy`: Contains the default proxy settings for all build operations,
+including image pull or push and source download.
+<4> `env`: A set of default environment variables that are applied to the build if
+the specified variables do not exist on the build.
+<5> `gitProxy`: Contains the proxy settings for Git operations only. If set, this
+overrides any Proxy settings for all Git commands, such as `git clone`.
+<6> `imageLabels`: A list of labels that are applied to the resulting image.
+You can override a default label by providing a label with the same name in the
+`BuildConfig`.
+<7> `resources`: Defines resource requirements to execute the build.
+<8> `buildOverrides`: Controls override settings for builds.
+<9> `imageLabels`: A list of labels that are applied to the resulting image.
+If you provided a label in the `BuildConfig` with the same name as one in this
+table, your label will be overwritten.
+<10> `nodeSelector`: A selector which must be true for the build pod to fit on a node.
+<11> `tolerations`: A list of tolerations that overrides any existing tolerations set
+on a build pod.

modules/builds-configuration-parameters.adoc

@@ -0,0 +1,63 @@
+// Module included in the following assemblies:
+//
+// * builds/build-configuration.adoc
+
+[id="builds-configuration-parameters_{context}"]
+= Build controller configuration parameters
+
+The `build.config.openshift.io/cluster` resource offers the following
+configuration parameters.
+
+[cols="3a,8a",options="header"]
+|===
+|Parameter |Description
+
+|`Build`
+|Holds cluster-wide information on how to handle builds. The canonical, and only
+valid name is `cluster`.
+
+`spec`: Holds user-settable values for the build controller
+configuration.
+
+|`buildDefaults`
+|Controls the default information for builds.
+
+`defaultProxy`: Contains the default proxy settings for all build operations,
+including image pull or push and source download.
+
+You can override values by setting the `HTTP_PROXY`, `HTTPS_PROXY`, and
+`NO_PROXY` environment variables in the `BuildConfig` strategy.
+
+`gitProxy`: Contains the proxy settings for Git operations only. If set, this
+overrides any Proxy settings for all Git commands, such as `git clone`.
+
+Values that are not set here are inherited from DefaultProxy.
+
+`env`: A set of default environment variables that are applied to the build if
+the specified variables do not exist on the build.
+
+`imageLabels`: A list of labels that are applied to the resulting image.
+You can override a default label by providing a label with the same name in the
+`BuildConfig`.
+
+`resources`: Defines resource requirements to execute the build.
+
+|`ImageLabel`
+|`name`: Defines the name of the label. It must have non-zero length.
+
+|`buildOverrides`
+|Controls override settings for builds.
+
+`imageLabels`: A list of labels that are applied to the resulting image.
+If you provided a label in the `BuildConfig` with the same name as one in this
+table, your label will be overwritten.
+
+`nodeSelector`: A selector which must be true for the build pod to fit on a node.
+
+`tolerations`: A list of tolerations that overrides any existing tolerations set
+on a build pod.
+
+|`BuildList`
+|`items`: Standard object's metadata.
+
+|===

modules/images-configuration-file.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * openshift_images/image-configuration.adoc
+
+[id="images-configuration-file_{context}"]
+= Configuring image settings
+
+You can configure image registry settings by editing the
+`image.config.openshift.io/cluster` resource.
+
+.Procedure
+
+* Edit the `image.config.openshift.io/cluster` resource:
++
+----
+$ oc edit image.config.openshift.io/cluster
+----
++
+The following is an example `image.config.openshift.io/cluster` resource:
++
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Image<1>
+metadata:
+  annotations:
+    release.openshift.io/create-only: "true"
+  creationTimestamp: "2019-05-17T13:44:26Z"
+  generation: 1
+  name: cluster
+  resourceVersion: "8302"
+  selfLink: /apis/config.openshift.io/v1/images/cluster
+  uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
+spec:
+  allowedRegistriesForImport:<2>
+    - domainName: quay.io
+      insecure: false
+  additionalTrustedCA:<3>
+    name: myconfigmap
+  registrySources:<4>
+    insecureRegistries:<5>
+    - insecure.com
+    blockedRegistries:<6>
+    - untrusted.com
+status:
+  internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
+----
+<1> `Image`: Holds cluster-wide information about how to handle images. The
+canonical, and only valid name is `cluster`.
+<2> `allowedRegistriesForImport`: Limits the container image registries from which
+normal users may import images. Set this list to the registries that you trust
+to contain valid images, and that you want applications to be able to
+import from. Users with permission to create images or `ImageStreamMappings`
+from the API are not affected by this policy. Typically only cluster
+administrators will have the appropriate permissions.
+<3> `additionalTrustedCA`: A reference to a ConfigMap containing additional CAs that
+should be trusted during `ImageStream import`, `pod image pull`,
+`openshift-image-registry pullthrough`, and builds. The namespace for this ConfigMap is
+`openshift-config`. The format of the ConfigMap is to use the registry hostname
+as the key, and the base64-encoded certificate as the value, for each additional
+registry CA to trust.
+<4> `registrySources`: Contains configuration that determines how the container
+runtime should treat individual registries when accessing images for builds and
+pods. For instance, whether or not to allow insecure access. It does not contain
+configuration for the internal cluster registry.
+<5> `insecureRegistries`: Registries which do not have a valid TLS certificate or
+only support HTTP connections.
+<6> `blockedRegistries`: Blacklisted for image pull and push actions. All other
+registries are allowed.

modules/images-configuration-parameters.adoc

@@ -0,0 +1,82 @@
+// Module included in the following assemblies:
+//
+// * openshift_images/image-configuration.adoc
+
+[id="images-configuration-parameters_{context}"]
+= Image controller configuration parameters
+
+The `image.config.openshift.io/cluster` resource offers the following
+configuration parameters.
+
+[cols="3a,8a",options="header"]
+|===
+|Parameter |Description
+
+|`Image`
+|Holds cluster-wide information about how to handle images. The canonical, and
+only valid name is `cluster`.
+
+`spec`: Holds user-settable values for configuration. You can edit the `spec`
+subsection.
+
+`status`: Holds observed values from the cluster.
+
+|`ImageSpec`
+|`allowedRegistriesForImport`: Limits the container image registries from which
+normal users may import images. Set this list to the registries that you trust
+to contain valid images, and that you want applications to be able to
+import from. Users with permission to create images or `ImageStreamMappings`
+from the API are not affected by this policy. Typically only cluster
+administrators will have the appropriate permissions.
+
+`additionalTrustedCA`: A reference to a ConfigMap containing additional CAs that
+should be trusted during `ImageStream import`, `pod image pull`,
+`openshift-image-registry pullthrough`, and builds.
+
+The namespace for this ConfigMap is `openshift-config`. The format of the
+ConfigMap is to use the registry hostname as the key, and the base64-encoded
+certificate as the value, for each additional registry CA to trust.
+
+`registrySources`: Contains configuration that determines how the container
+runtime should treat individual registries when accessing images for builds and
+pods. For instance, whether or not to allow insecure access. It does not contain
+configuration for the internal cluster registry.
+
+|`ImageStatus`
+|`internalRegistryHostname`: Set by the Image Registry Operator, which controls
+the `internalRegistryHostname`. It sets the hostname for the default internal
+image registry. The value must be in `hostname[:port]` format. For backward
+compatibility, you can still use the `OPENSHIFT_DEFAULT_REGISTRY` environment
+variable, but this setting overrides the environment variable.
+
+`externalRegistryHostnames`: Provides the hostnames for the default external
+image registry. The external hostname should be set only when the image registry
+is exposed externally. The first value is used in `publicDockerImageRepository`
+field in ImageStreams. The value must be in `hostname[:port]` format.
+
+|`RegistryLocation`
+|Contains a location of the registry specified by the registry domain name.
+The domain name might include wildcards.
+
+`domainName`: Specifies a domain name for the registry. In case the registry uses a
+non-standard (80 or 443) port, the port should be included in the domain name
+as well.
+
+`insecure`: Insecure indicates whether the registry is secure or insecure.
+By default, if not otherwise specified, the registry is assumed to be secure.
+
+|`RegistrySources`
+|Holds cluster-wide information about how to handle the registries config.
+
+`insecureRegistries`: Registries which do not have a valid TLS certificate or
+only support HTTP connections.
+
+`blockedRegistries`: Blacklisted for image pull and push actions. All other
+registries are allowed.
+
+`allowedRegistries`: Whitelisted for image pull and push actions. All other
+registries are blocked.
+
+Only one of `blockedRegistries` or `allowedRegistries` may be set
+
+|===

openshift_images/image-configuration.adoc

@@ -0,0 +1,11 @@
+[id="image-configuration"]
+= Image configuration resources
+include::modules/common-attributes.adoc[]
+:context: image-configuration
+toc::[]
+
+Use the following procedure to configure image registries.
+
+include::modules/images-configuration-parameters.adoc[leveloffset=+1]
+
+include::modules/images-configuration-file.adoc[leveloffset=+1]