diff --git a/_topic_map.yml b/_topic_map.yml index 4424371f42..d950c774f7 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/builds/build-configuration.adoc b/builds/build-configuration.adoc new file mode 100644 index 0000000000..ba353d6898 --- /dev/null +++ b/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] diff --git a/modules/builds-configuration-file.adoc b/modules/builds-configuration-file.adoc new file mode 100644 index 0000000000..d460bef1d0 --- /dev/null +++ b/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. diff --git a/modules/builds-configuration-parameters.adoc b/modules/builds-configuration-parameters.adoc new file mode 100644 index 0000000000..2a5ad8acf2 --- /dev/null +++ b/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. + +|=== diff --git a/modules/images-configuration-file.adoc b/modules/images-configuration-file.adoc new file mode 100644 index 0000000000..2614ed2f1d --- /dev/null +++ b/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. diff --git a/modules/images-configuration-parameters.adoc b/modules/images-configuration-parameters.adoc new file mode 100644 index 0000000000..2d2ea597ba --- /dev/null +++ b/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 + +|=== diff --git a/openshift_images/image-configuration.adoc b/openshift_images/image-configuration.adoc new file mode 100644 index 0000000000..f267bbe85d --- /dev/null +++ b/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]