openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-06 15:46:57 +01:00
Code Issues Releases Activity

Add build inputs modules

Browse Source
This commit is contained in:
bmcelvee
2018-11-16 14:39:58 -05:00
parent 05040bd71f
commit faaf12a7fc
29 changed files with 1498 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
builds/creating-build-inputs.adoc
View File

@@ -1,36 +1,18 @@
// This assembly is included in the following assemblies:
//
// <List assemblies here, each on a new line>
//
//* assembly/builds
// This assembly can be included from other assemblies using the following
// include statement:
// The following line is necessary to allow assemblies be included in other
// assemblies. It restores the `context` variable to its previous state.
:parent-context-of-creating-build-inputs: {context}
// The file name and the ID are based on the assembly title.
// For example:
// * file name: assembly_my-assembly-a.adoc
// * ID: [id='assembly_my-assembly-a_{context}']
// * Title: = My assembly A
//
// The ID is used as an anchor for linking to the module.
// Avoid changing it after the module has been published
// to ensure existing links are not broken.
//
// In order for the assembly to be reusable in other assemblies in a guide,
// include {context} in the ID: [id='a-collection-of-modules_{context}'].
//
// If the assembly covers a task, start the title with a verb in the gerund
// form, such as Creating or Configuring.
// The `context` attribute enables module reuse. Every module's ID
// includes {context}, which ensures that the module has a unique ID even if
// it is reused multiple times in a guide.
:context: creating-build-inputs
[id='creating-build-inputs_{context}']
= Creating Build Inputs
= Creating build inputs
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:
toc::[]
// The following block is rendered only if the `internal` variable is set.
// The table shows various metadata useful when editing this file.
@@ -54,35 +36,70 @@ YES/NO
|===
endif::[]
This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. Can include more than one paragraph. Consider using the information from the user story.
[id='prerequisites-{context}']
== Prerequisites
* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
* You can also link to other modules or assemblies the user must follow before starting this assembly.
* Delete the section title and bullets if the assembly has no prerequisites.
Use the following sections for an overview of build inputs, and instructions on
how to use inputs to provide source content for builds to operate on.
// The following include statements pull in the module files that comprise
// the assembly. Include any combination of concept, procedure, or reference
// modules required to cover the user story. You can also include other
// assemblies.
Include modules here.
include::modules/builds-define-build-inputs.adoc[leveloffset=+1]
include::modules/define-build-inputs.adoc[leveloffset=+1]
include::modules/builds-dockerfile-source.adoc[leveloffset=+1]
// [leveloffset=+1] ensures that when a module starts with a level-1 heading
// (= Heading), the heading will be interpreted as a level-2 heading
// (== Heading) in the assembly.
include::modules/builds-image-source.adoc[leveloffset=+1]
include::modules/builds-source-code.adoc[leveloffset=+1]
include::modules/builds-using-proxy-git-cloning.adoc[leveloffset=+2]
include::modules/builds-adding-source-clone-secrets.adoc[leveloffset=+2]
include::modules/builds-automatically-add-source-clone-secrets.adoc[leveloffset=+3]
include::modules/builds-manually-add-source-clone-secrets.adoc[leveloffset=+3]
include::modules/builds-gitconfig-file.adoc[leveloffset=+3]
include::modules/builds-gitconfig-file-secured-git.adoc[leveloffset=+3]
include::modules/builds-source-secret-basic-auth.adoc[leveloffset=+3]
include::modules/builds-source-secret-ssh-key-auth.adoc[leveloffset=+3]
include::modules/builds-source-secret-trusted-ca.adoc[leveloffset=+3]
include::modules/builds-source-secret-combinations.adoc[leveloffset=+3]
include::modules/builds-source-secret-combinations-ssh-gitconfig.adoc[leveloffset=+4]
include::modules/builds-source-secret-combinations-gitconfig-ca.adoc[leveloffset=+4]
include::modules/builds-source-secret-combinations-basic-auth-ca.adoc[leveloffset=+4]
include::modules/builds-source-secret-combinations-basic-auth-gitconfig.adoc[leveloffset=+4]
include::modules/builds-source-secret-combinations-basic-auth-gitconfig-ca.adoc[leveloffset=+4]
include::modules/builds-binary-source.adoc[leveloffset=+1]
include::modules/builds-input-secrets-configmaps.adoc[leveloffset=+1]
include::modules/builds-adding-input-secrets-configmaps.adoc[leveloffset=+2]
include::modules/builds-source-to-image.adoc[leveloffset=+2]
include::modules/builds-docker-strategy.adoc[leveloffset=+2]
include::modules/builds-custom-strategy.adoc[leveloffset=+2]
include::modules/builds-using-external-artifacts.adoc[leveloffset=+1]
include::modules/builds-docker-credentials-private-registries.adoc[leveloffset=+1]
[id='related-information-{context}']
== Related information
* A bulleted list of links to other material closely related to the contents of the concept module.
* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
// The following line is necessary to allow assemblies be included in other
// assemblies. It restores the `context` variable to its previous state.
:context: {parent-context-of-creating-build-inputs}
ifdef::context[:parent-context: {context}]

104
modules/builds-adding-input-secrets-configmaps.adoc Normal file
View File

@@ -0,0 +1,104 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-adding-input-secrets-configmaps.adoc[leveloffset=+1]
[id='builds-adding-input-secrets-configmaps-{context}']
= Adding input secrets and ConfigMaps
In some scenarios, build operations require credentials or other configuration
data to access dependent resources, but it is undesirable for that information
to be placed in source control. You can define _input secrets_ and _input
ConfigMaps_ for this purpose.
.Prerequisites
*
.Procedure
To add an input secret and/or ConfigMap to an existing `BuildConfig`:
. Create the ConfigMap, if it does not exist:
+
----
$ oc create configmap settings-mvn \
--from-file=settings.xml=<path/to/settings.xml>
----
+
This creates a new ConfigMap named *_settings-mvn_*, which contains the
plain text content of the *_settings.xml_* file.
. Create the secret, if it does not exist:
+
----
$ oc create secret generic secret-mvn \
--from-file=id_rsa=<path/to/.ssh/id_rsa>
----
+
This creates a new secret named *_secret-mvn_*, which contains the base64
encoded content of the *_id_rsa_* private key.
. Add the ConfigMap and secret to the `source` section in the existing
`BuildConfig`:
+
[source,yaml]
----
source:
git:
uri: https://github.com/wildfly/quickstart.git
contextDir: helloworld
configMaps:
- configMap:
name: settings-mvn
secrets:
- secret:
name: secret-mvn
----
To include the secret and ConfigMap in a new `BuildConfig`, run the following
command:
----
$ oc new-build \
openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \
--context-dir helloworld --build-secret “secret-mvn” \
--build-config-map "settings-mvn"
----
During the build, the *_settings.xml_* and *_id_rsa_* files are copied into the
directory where the source code is located. In {product-title} S2I builder
images, this is the image working directory, which is set using the `WORKDIR`
instruction in the *_Dockerfile_*. If you want to specify another directory,
add a `destinationDir` to the definition:
[source,yaml]
----
source:
git:
uri: https://github.com/wildfly/quickstart.git
contextDir: helloworld
configMaps:
- configMap:
name: settings-mvn
destinationDir: ".m2"
secrets:
- secret:
name: secret-mvn
destinationDir: ".ssh"
----
You can also specify the destination directory when creating a new
`BuildConfig`:
----
$ oc new-build \
openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \
--context-dir helloworld --build-secret “secret-mvn:.ssh” \
--build-config-map "settings-mvn:.m2"
----
In both cases, the *_settings.xml_* file is added to the *_./.m2_* directory of the
build environment, and the *_id_rsa_* key is added to the *_./.ssh_* directory.

57
modules/builds-adding-source-clone-secrets.adoc Normal file
View File

@@ -0,0 +1,57 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-adding-source-clone-secrets.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='adding-source-clone-secrets-{context}']
= Adding Source Clone Secrets
Builder pods require access to any Git repositories defined as source for a
build. Source clone secrets are used to provide the builder pod with access it
would not normally have access to, such as private repositories or repositories
with self-signed or untrusted SSL certificates.
.Prerequisites
* The following source clone secret configurations are supported.
** .gitconfig File
** Basic Authentication
** SSH Key Authentication
** Trusted Certificate Authorities
[NOTE]
====
You can also use combinations of these configurations
to meet your specific needs.
====
.Procedure
Builds are run with the *builder* service account, which must have access to any
source clone secrets used.
* Run the following command to grant access:
----
$ oc secrets link builder mysecret
----
[NOTE]
====
Limiting secrets to only the service accounts that reference them is disabled by
default. This means that if `serviceAccountConfig.limitSecretReferences` is set
to `false` (the default setting) in the master configuration file, linking
secrets to a service is not required.
====
.Additional resources
* Link to Source Secrets Combinations

101
modules/builds-automatically-add-source-clone-secrets.adoc Normal file
View File

@@ -0,0 +1,101 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
// assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-automatically-add-source-clone-secrets.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='build-auto-add-source-clone-secrets-{context}']
= Automatically Adding a Source Clone Secret to a Build Configuration
When a `BuildConfig` is created, {product-title} can automatically populate its
source clone secret reference. This behavior allows the resulting `Builds` to
automatically use the credentials stored in the referenced `Secret` to
authenticate to a remote Git repository, without requiring further
configuration.
To use this functionality, a `Secret` containing the Git repository credentials
must exist in the namespace in which the `BuildConfig` is later created.
This `Secret` must additionally include one or more annotations prefixed with
`build.openshift.io/source-secret-match-uri-`. The value of each of these
annotations is a URI pattern, defined as follows. When a `BuildConfig` is created
without a source clone secret reference and its Git source URI matches a URI
pattern in a `Secret` annotation, {product-title} will automatically insert a
reference to that `Secret` in the `BuildConfig`.
.Prerequisites
A URI pattern must consist of:
- a valid scheme (`*://`, `git://`, `http://`, `https://` or `ssh://`).
- a host (`\*` or a valid hostname or IP address optionally preceded by `*.`).
- a path (`/\*` or `/` followed by any characters optionally including `*`
characters).
In all of the above, a `*` character is interpreted as a wildcard.
[IMPORTANT]
====
URI patterns must match Git source URIs which are conformant to
link:https://www.ietf.org/rfc/rfc3986.txt[RFC3986]. Do not include a
username (or password) component in a URI pattern.
For example, if you use
`ssh://git@bitbucket.atlassian.com:7999/ATLASSIAN/jira.git` for a git repository
URL, the source secret must be specified as
`pass:c[ssh://bitbucket.atlassian.com:7999/*]` (and not
`pass:c[ssh://git@bitbucket.atlassian.com:7999/*]`).
[source, bash]
----
$ oc annotate secret mysecret \
'build.openshift.io/source-secret-match-uri-1=ssh://bitbucket.atlassian.com:7999/*'
----
====
.Procedure
If multiple `Secrets` match the Git URI of a particular `BuildConfig`,
{product-title} will select the secret with the longest match. This allows for
basic overriding, as in the following example.
The following fragment shows two partial source clone secrets, the first
matching any server in the domain `mycorp.com` accessed by HTTPS, and the second
overriding access to servers `mydev1.mycorp.com` and `mydev2.mycorp.com`:
[source,yaml]
----
kind: Secret
apiVersion: v1
metadata:
name: matches-all-corporate-servers-https-only
annotations:
build.openshift.io/source-secret-match-uri-1: https://*.mycorp.com/*
data:
...
kind: Secret
apiVersion: v1
metadata:
name: override-for-my-dev-servers-https-only
annotations:
build.openshift.io/source-secret-match-uri-1: https://mydev1.mycorp.com/*
build.openshift.io/source-secret-match-uri-2: https://mydev2.mycorp.com/*
data:
...
----
* Add a `build.openshift.io/source-secret-match-uri-` annotation to a pre-existing
secret using:
----
$ oc annotate secret mysecret \
'build.openshift.io/source-secret-match-uri-1=https://*.mycorp.com/*'
----

79
modules/builds-binary-source.adoc Normal file
View File

@@ -0,0 +1,79 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-binary-source.adoc[leveloffset=+1]
[id='builds-binary-source-{context}']
= Binary (local) source
Streaming content from a local file system to the builder is
called a `Binary` type build. The corresponding value of
`BuildConfig.spec.source.type` is `Binary` for such builds.
This source type is unique in that it is leveraged solely based on your use of
the `oc start-build`.
[NOTE]
====
Binary type builds require content to be streamed from the local file system, so
automatically triggering a binary type build (e.g. via an image change trigger)
is not possible, because the binary files cannot be provided. Similarly, you
cannot launch binary type builds from the web console.
====
To utilize binary builds, invoke `oc start-build` with one of these options:
* `--from-file`: The contents of the file you specify are sent as a binary stream
to the builder. You can also specify a URL to a file. Then, the builder stores
the data in a file with the same name at the top of the build context.
* `--from-dir` and `--from-repo`: The contents are archived and sent as a binary
stream to the builder. Then, the builder extracts the contents of the archive
within the build context directory. With `--from-dir`, you can also specify
a URL to an archive, which will be extracted.
* `--from-archive`: The archive you specify is sent to the builder, where it is
extracted within the build context directory. This option
behaves the same as `--from-dir`; an archive is created on your host first,
whenever the argument to these options is a directory.
In each of the previously listed cases:
* If your `BuildConfig` already has a `Binary` source type defined, it will
effectively be ignored and replaced by what the client sends.
* If your `BuildConfig` has a `Git` source type defined, it is dynamically
disabled, since `Binary` and `Git` are mutually exclusive, and the data in
the binary stream provided to the builder takes precedence.
Instead of a file name, you can pass a URL with HTTP or HTTPS schema to
`--from-file` and `--from-archive`. When using `--from-file` with a URL, the
name of the file in the builder image is determined by the `Content-Disposition`
header sent by the web server, or the last component of the URL path if the
header is not present. No form of authentication is supported and it is not
possible to use custom TLS certificate or disable certificate validation.
When using `oc new-build --binary=true`, the command ensures that the
restrictions associated with binary builds are enforced. The resulting
`BuildConfig` will have a source type of `Binary`, meaning that the only
valid way to run a build for this `BuildConfig` is to use `oc
start-build` with one of the `--from` options to provide the requisite binary
data.
ifndef::openshift-online[]
The `dockerfile` and `contextDir` source options have
special meaning with binary builds.
`dockerfile` can be used with any binary build source. If `dockerfile` is
used and the binary stream is an archive, its contents serve as a replacement
Dockerfile to any Dockerfile in the archive. If `dockerfile` is used with the
`--from-file` argument, and the file argument is named `dockerfile`, the value
from `dockerfile` replaces the value from the binary stream.
endif::[]
In the case of the binary stream encapsulating extracted archive content, the
value of the `contextDir` field is interpreted as a subdirectory within the
archive, and, if valid, the builder changes into that subdirectory before
executing the build.

33
modules/builds-custom-strategy.adoc Normal file
View File

@@ -0,0 +1,33 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-custom-strategy.adoc[leveloffset=+1]
[id='builds-custom-strategy-{context}']
= Custom strategy
//[NOTE]
//====
//Do not build in Online.
//====
When using a `Custom` strategy, all the defined input secrets and ConfigMaps
are available inside the builder container in the *_/var/run/secrets/openshift.io/build_*
directory. The custom build image is responsible for using these secrets
and ConfigMaps appropriately. The `Custom` strategy also allows secrets to be
defined as described in Custom Strategy Options.
//[NOTE]
//====
//Add module above?
//====
There is no technical difference between existing strategy secrets and the input
secrets. However, your builder image might distinguish between them and use them
differently, based on your build use case.
The input secrets are always mounted into the
*_/var/run/secrets/openshift.io/build_* directory or your builder can parse the
`$BUILD` environment variable, which includes the full build object.

101
modules/builds-define-build-inputs.adoc Normal file
View File

@@ -0,0 +1,101 @@
// Module included in the following assemblies:
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-define-build-inputs.adoc[leveloffset=+1]
[id="define-build-inputs_{context}"]
= Define build inputs
A _build input_ provides source content for builds to operate on. You can use the
following _build inputs_ to provide sources in {product-title}, listed in order
of precedence:
ifndef::openshift-online[]
* Inline Dockerfile definitions
endif::[]
* Content extracted from existing images
* Git repositories
* Binary (Local) inputs
* Input secrets
* External artifacts
ifdef::openshift-online[]
[IMPORTANT]
====
The Docker build strategy is not supported in {product-title}. Therefore, inline
Dockerfile definitions are not accepted.
====
endif::[]
You can combine multiple inputs in a single build.
ifndef::openshift-online[]
However, as the inline
Dockerfile takes precedence, it can overwrite any other file named Dockerfile
provided by another input.
endif::[]
Binary (local) input and Git repositories are mutually
exclusive inputs.
You can use input secrets when you do not want certain resources or credentials
used during a build to be available in the final application image produced by
the build, or want to consume a value that is defined in a Secret resource.
External artifacts can be used to pull in additional files that are not available
as one of the other build input types.
When you run a build:
. A working directory is constructed and all input content is placed in the
working directory. For example, the input Git repository is cloned into the
working directory, and files specified from input images are copied into the
working directory using the target path.
. The build process changes directories into the `contextDir`, if one is
defined.
ifndef::openshift-online[]
. The inline Dockerfile, if any, is written to the current directory.
endif::[]
. The content from the current directory is provided to the build process
for reference by the
ifndef::openshift-online[]
Dockerfile, custom builder logic, or
endif::[]
*_assemble_* script. This means any input content that resides outside the
`contextDir` will be ignored by the build.
The following example of a source definition includes multiple input types and
an explanation of how they are combined. For more details on how each input type
is defined, see the specific sections for each input type.
[source,yaml]
----
source:
git:
uri: https://github.com/openshift/ruby-hello-world.git <1>
images:
- from:
kind: ImageStreamTag
name: myinputimage:latest
namespace: mynamespace
paths:
- destinationDir: app/dir/injected/dir <2>
sourcePath: /usr/lib/somefile.jar
contextDir: "app/dir" <3>
ifndef::openshift-online[]
dockerfile: "FROM centos:7\nRUN yum install -y httpd" <4>
endif::[]
----
<1> The repository to be cloned into the working directory for the build.
<2> *_/usr/lib/somefile.jar_* from `myinputimage` will be stored in *_<workingdir>/app/dir/injected/dir_*.
<3> The working directory for the build will become *_<original_workingdir>/app/dir_*.
ifndef::openshift-online[]
<4> A Dockerfile with this content will be created in *_<original_workingdir>/app/dir_*, overwriting any existing file with that name.
endif::[]
. Additional resources
* A bulleted list of links to other material closely related to the contents of the concept module.
* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

117
modules/builds-docker-credentials-private-registries.adoc Normal file
View File

@@ -0,0 +1,117 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-docker-credentials-private-registries.adoc[leveloffset=+1]
[id='builds-docker-credentials-private-registries-{context}']
= Using Docker credentials for private registries
You can supply builds with a *_.docker/config.json_* file with valid credentials
for private container registries. This allows you to push the output image into a
private container image registry or pull a builder image from the private container image registry
that requires authentication.
[NOTE]
====
For the {product-title} container image registry, this is not required because secrets
are generated automatically for you by {product-title}.
====
The *_.docker/config.json_* file is found in your home directory by default and
has the following format:
[source,yaml]
----
auths:
https://index.docker.io/v1/: <1>
auth: "YWRfbGzhcGU6R2labnRib21ifTE=" <2>
email: "user@example.com" <3>
----
<1> URL of the registry.
<2> Encrypted password.
<3> Email address for the login.
You can define multiple container image registry entries in this file. Alternatively, you
can also add authentication entries to this file by running the `docker login`
command. The file will be created if it does not exist.
Kubernetes provides `Secret` objects, which can be used to store configuration
and passwords.
.Prerequisites
* *_.docker/config.json_* file
.Procedure
. Create the secret from your local *_.docker/config.json_* file:
+
----
$ oc create secret generic dockerhub \
--from-file=.dockerconfigjson=<path/to/.docker/config.json> \
--type=kubernetes.io/dockerconfigjson
----
+
This generates a JSON specification of the secret named `dockerhub` and
creates the object.
. Once the secret is created, add it to the builder service account. Each build is
run with the `builder` role, so you must give it access your secret with the
following command:
+
----
$ oc secrets link builder dockerhub
----
. Add a `pushSecret` field into the `output` section of the `BuildConfig` and
set it to the name of the `secret` that you created, which in the above example
is `dockerhub`:
+
[source,yaml]
----
spec:
output:
to:
kind: "DockerImage"
name: "private.registry.com/org/private-image:latest"
pushSecret:
name: "dockerhub"
----
+
You can use the `oc set build-secret` command to set the push secret on
the build configuration:
+
----
$ oc set build-secret --push bc/sample-build dockerhub
----
. Pull the builder container image from a private container image registry by specifying the
`pullSecret` field, which is part of the build strategy definition:
+
[source,yaml]
----
strategy:
sourceStrategy:
from:
kind: "DockerImage"
name: "docker.io/user/private_repository"
pullSecret:
name: "dockerhub"
----
+
You can use the `oc set build-secret` command to set the pull secret on
the build configuration:
+
----
$ oc set build-secret --pull bc/sample-build dockerhub
----
ifndef::openshift-online[]
[NOTE]
====
This example uses `pullSecret` in a Source build, but it is also applicable
in Docker and Custom builds.
====
endif::[]

54
modules/builds-docker-strategy.adoc Normal file
View File

@@ -0,0 +1,54 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-docker-strategy.adoc[leveloffset=+1]
[id='builds-docker-strategy-{context}']
= Docker strategy
//[NOTE]
//====
//Do not build in Online. May be irrelevant for 4.0.
//====
When using a `Docker` strategy, you can add all defined input secrets into your
container image using the
link:https://docs.docker.com/engine/reference/builder/#add[`ADD`] and
link:https://docs.docker.com/engine/reference/builder/#copy[`COPY` instructions] in
your *_Dockerfile_*.
If you do not specify the `destinationDir` for a secret, then the files will be
copied into the same directory in which the *_Dockerfile_* is located. If you
specify a relative path as `destinationDir`, then the secrets will be copied
into that directory, relative to your *_Dockerfile_* location. This makes the
secret files available to the Docker build operation as part of the context
directory used during the build.
.Example of a Dockerfile referencing secret and ConfigMap data
====
----
FROM centos/ruby-22-centos7
USER root
COPY ./secret-dir /secrets
COPY ./config /
# Create a shell script that will output secrets and ConfigMaps when the image is run
RUN echo '#!/bin/sh' > /input_report.sh
RUN echo '(test -f /secrets/secret1 && echo -n "secret1=" && cat /secrets/secret1)' >> /input_report.sh
RUN echo '(test -f /config && echo -n "relative-configMap=" && cat /config)' >> /input_report.sh
RUN chmod 755 /input_report.sh
CMD ["/bin/sh", "-c", "/input_report.sh"]
----
====
[NOTE]
====
Users should normally remove their input secrets from the final application image
so that the secrets are not present in the container running from that image.
However, the secrets will still exist in the image itself in the layer where
they were added. This removal should be part of the *_Dockerfile_* itself.
====

28
modules/builds-dockerfile-source.adoc Normal file
View File

@@ -0,0 +1,28 @@
// Module included in the following assemblies:
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-dockerfile-source.adoc[leveloffset=+1]
[id="dockerfile-source_{context}"]
= Dockerfile source
When you supply a `dockerfile` value, the content of this field
is written to disk as a file named *_Dockerfile_*. This is
done after other input sources are processed, so if the input
source repository contains a *_Dockerfile_* in the root directory,
it will be overwritten with this content.
The source definition is part of the `spec` section in the `BuildConfig`:
[source,yaml]
----
source:
dockerfile: "FROM centos:7\nRUN yum install -y httpd" <1>
----
<1> The `dockerfile` field contains an inline Dockerfile that will be built.
. Additional resources
* The typical use for this field is to provide a `Dockerfile` to a
Docker strategy build.

73
modules/builds-gitconfig-file-secured-git.adoc Normal file
View File

@@ -0,0 +1,73 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-gitconfig-file-secured-git.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='source-secrets-gitconfig-file-for-secured-git-{context}']
= .gitconfig file for secured Git
If your Git server is secured with two-way SSL and user name with password,
you must add the certificate files to your source build and add references to
the certificate files in the *_.gitconfig_* file.
.Prerequisites
* Git credentials
.Procedure
Add the certificate files to your source build and add references to
the certificate files in the *_.gitconfig_* file.
. Add the *_client.crt_*, *_cacert.crt_*, and *_client.key_* files to the
*_/var/run/secrets/openshift.io/source/_* folder in the application
source code.
. In the *_.gitconfig_* file for the server, add the `[http]` section
shown in the following example:
+
----
# cat .gitconfig
[user]
name = <name>
email = <email>
[http]
sslVerify = false
sslCert = /var/run/secrets/openshift.io/source/client.crt
sslKey = /var/run/secrets/openshift.io/source/client.key
sslCaInfo = /var/run/secrets/openshift.io/source/cacert.crt
----
. Create the secret:
+
----
$ oc create secret generic <secret_name> \
--from-literal=username=<user_name> \ <1>
--from-literal=password=<password> \ <2>
--from-file=.gitconfig=.gitconfig \
--from-file=client.crt=/var/run/secrets/openshift.io/source/client.crt \
--from-file=cacert.crt=/var/run/secrets/openshift.io/source/cacert.crt \
--from-file=client.key=/var/run/secrets/openshift.io/source/client.key
----
<1> The user's Git user name.
<2> The password for this user.
[IMPORTANT]
====
To avoid having to enter your password again, be sure to specify the S2I image in
your builds. However, if you cannot clone the repository, you still need to
specify your user name and password to promote the build.
====
. Additional resources
* *_/var/run/secrets/openshift.io/source/_* folder in the application
source code.

39
modules/builds-gitconfig-file.adoc Normal file
View File

@@ -0,0 +1,39 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
// assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-gitconfig-file.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='source-secrets-gitconfig-file-{context}']
= .gitconfig file
If the cloning of your application is dependent on a *_.gitconfig_* file,
then you can create a secret that contains it. Add
it to the builder service account and then your `BuildConfig`.
.Procedure
* To create a secret from a *_.gitconfig_* file:
----
$ oc create secret generic <secret_name> --from-file=<path/to/.gitconfig>
----
[NOTE]
====
SSL verification can be turned off if `sslVerify=false` is set for the `http`
section in your *_.gitconfig_* file:
----
[http]
sslVerify=false
----
====

70
modules/builds-image-source.adoc Normal file
View File

@@ -0,0 +1,70 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-image-source.adoc[leveloffset=+1]
[id="image-source_{context}"]
= Image source
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 image stream tags 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.
The source path can be any absolute path within the image specified. The
destination must be a relative directory path. At build time, the image will be
loaded and the indicated files and directories will be copied into the context
directory of the build process. This is the same directory into which the source
repository content (if any) is cloned. If the source path ends in *_/._* then
the content of the directory will be copied, but the directory itself will not
be created at the destination.
Image inputs are specified in the `source` definition of the `BuildConfig`:
[source,yaml]
----
source:
git:
uri: https://github.com/openshift/ruby-hello-world.git
images: <1>
- from: <2>
kind: ImageStreamTag
name: myinputimage:latest
namespace: mynamespace
paths: <3>
- destinationDir: injected/dir <4>
sourcePath: /usr/lib/somefile.jar <5>
- from:
kind: ImageStreamTag
name: myotherinputimage:latest
namespace: myothernamespace
pullSecret: mysecret <6>
paths:
- destinationDir: injected/dir
sourcePath: /usr/lib/somefile.jar
----
<1> An array of one or more input images and files.
<2> A reference to the image containing the files to be copied.
<3> An array of source/destination paths.
<4> The directory relative to the build root where the build process can access the file.
<5> The location of the file to be copied out of the referenced image.
<6> An optional secret provided if credentials are needed to access the input image.
ifndef::openshift-online[]
[NOTE]
====
This feature is not supported for builds using the Custom Strategy.
====
endif::[]
. Additional resources
* Link to Custom Strategy
ifndef::openshift-online[]
* Link to Image Stream Tags
endif::[]

30
modules/builds-input-secrets-configmaps.adoc Normal file
View File

@@ -0,0 +1,30 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-input-secrets-configmaps.adoc[leveloffset=+1]
[id='builds-input-secrets-configmaps-{context}']
= Input Secrets and ConfigMaps
In some scenarios, build operations require credentials or other configuration
data to access dependent resources, but it is undesirable for that information
to be placed in source control. You can define _input secrets_ and _input
ConfigMaps_ for this purpose.
For example, when building a Java application with Maven, you can set up a
private mirror of Maven Central or JCenter that is accessed by private keys.
In order to download libraries from that private mirror, you have to supply the
following:
. A *_settings.xml_* file configured with the mirror's URL and connection
settings.
. A private key referenced in the settings file, such as *_~/.ssh/id_rsa_*.
For security reasons, you do not want to expose your credentials in the
application image.
This example describes a Java application, but you can use the same approach
for adding SSL certificates into the *_/etc/ssl/certs_* directory, API keys or
tokens, license files, and more.

57
modules/builds-manually-add-source-clone-secrets.adoc Normal file
View File

@@ -0,0 +1,57 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
// assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-manually-add-source-clone-secrets.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='manually-add-source-clone-secrets-{context}']
= Manually Adding a Source Clone Secrets
Source clone secrets can be added manually to a build configuration by adding a
`sourceSecret` field to the `source` section inside the `BuildConfig` and
setting it to the name of the `secret` that you created (`basicsecret`, in this
example).
[source,yaml]
----
apiVersion: "v1"
kind: "BuildConfig"
metadata:
name: "sample-build"
spec:
output:
to:
kind: "ImageStreamTag"
name: "sample-image:latest"
source:
git:
uri: "https://github.com/user/app.git"
sourceSecret:
name: "basicsecret"
strategy:
sourceStrategy:
from:
kind: "ImageStreamTag"
name: "python-33-centos7:latest"
----
.Procedure
You can also use the `oc set build-secret` command to set the source clone
secret on an existing build configuration.
* To set the source clone secret on an existing build configuration, run:
----
$ oc set build-secret --source bc/sample-build basicsecret
----
. Additional resources
* Defining Secrets in the BuildConfig provides more information on this topic.

51
modules/builds-source-code.adoc Normal file
View File

@@ -0,0 +1,51 @@
// Module included in the following assemblies:
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-code.adoc[leveloffset=+1]
[id="source-code_{context}"]
= Git source
When specified, source code is fetched from the supplied location.
ifndef::openshift-online[]
If you supply an inline Dockerfile, it overwrites the *_Dockerfile_*
(if any) in the `contextDir` of the Git repository.
endif::[]
The source definition is part of the `spec` section in the `BuildConfig`:
[source,yaml]
----
source:
git: <1>
uri: "https://github.com/openshift/ruby-hello-world"
ref: "master"
contextDir: "app/dir" <2>
ifndef::openshift-online[]
dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" <3>
endif::[]
----
<1> The `git` field contains the URI to the remote Git repository of the
source code. Optionally, specify the `ref` field to check out a specific Git
reference. A valid `ref` can be a SHA1 tag or a branch name.
<2> The `contextDir` field allows you to override the default location inside
the source code repository where the build looks for the application source
code. If your application exists inside a sub-directory, you can override the
default location (the root folder) using this field.
ifndef::openshift-online[]
<3> If the optional `dockerfile` field is provided, it should be a string
containing a Dockerfile that overwrites any Dockerfile that may exist in the
source repository.
endif::[]
If the `ref` field denotes a pull request, the system will use a `git fetch` operation
and then checkout `FETCH_HEAD`.
When no `ref` value is provided, {product-title} performs a shallow clone
(`--depth=1`). In this case, only the files associated with the most recent
commit on the default branch (typically `master`) are downloaded. This results
in repositories downloading faster, but without the full commit history. To
perform a full `git clone` of the default branch of a specified repository, set
`ref` to the name of the default branch (for example `master`).

43
modules/builds-source-secret-basic-auth.adoc Normal file
View File

@@ -0,0 +1,43 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-basic-auth.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='source-secrets-basic-auth-{context}']
= Source code basic authentication
Basic authentication requires either a combination of `--username` and
`--password`, or a `token` to authenticate against the SCM server.
. Prerequisites
* User name and password to access the private repository.
.Procedure
. Create the `secret` first before using the user name and password to access the
private repository:
----
$ oc create secret generic <secret_name> \
--from-literal=username=<user_name> \
--from-literal=password=<password> \
--type=kubernetes.io/basic-auth
----
. Create a basic authentication secret with a token:
----
$ oc create secret generic <secret_name> \
--from-literal=password=<token> \
--type=kubernetes.io/basic-auth
----

29
modules/builds-source-secret-combinations-basic-auth-ca.adoc Normal file
View File

@@ -0,0 +1,29 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-combinations-basic-auth-ca.adoc[leveloffset=+1]
[id='builds-source-secret-combinations-basic-auth-ca-{context}']
= Create a basic authentication secret with a CA certificate
You can combine the different methods for creating source clone secrets for your
specific needs, such as a secret that combines a basic authentication and CA certificate.
.Prerequisites
* Basic authentication credentials
* CA certificate
.Procedure
* Create a basic authentication secret with a CA certificate
----
$ oc create secret generic <secret_name> \
--from-literal=username=<user_name> \
--from-literal=password=<password> \
--from-file=ca-cert=</path/to/file> \
--type=kubernetes.io/basic-auth
----

32
modules/builds-source-secret-combinations-basic-auth-gitconfig-ca.adoc Normal file
View File

@@ -0,0 +1,32 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-combinations-basic-auth-gitconfig-ca.adoc[leveloffset=+1]
[id='builds-source-secret-combinations-basic-auth-gitconfig-ca-{context}']
= Create a basic authentication secret with a *_.gitconfig_* file and CA certificate
You can combine the different methods for creating source clone secrets for your
specific needs, such as a secret that combines a basic authentication, *_.gitconfig_* file,
and CA certificate.
.Prerequisites
* Basic authentication credentials
* *_.gitconfig_* file
* CA certificate
.Procedure
* Create a basic authentication secret with a *_.gitconfig_* file and CA certificate
----
$ oc create secret generic <secret_name> \
--from-literal=username=<user_name> \
--from-literal=password=<password> \
--from-file=</path/to/.gitconfig> \
--from-file=ca-cert=</path/to/file> \
--type=kubernetes.io/basic-auth
----

29
modules/builds-source-secret-combinations-basic-auth-gitconfig.adoc Normal file
View File

@@ -0,0 +1,29 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-combinations-basic-auth-gitconfig.adoc[leveloffset=+1]
[id='builds-source-secret-combinations-basic-auth-gitconfig-{context}']
= Create a basic authentication secret with a *_.gitconfig_* file
You can combine the different methods for creating source clone secrets for your
specific needs, such as a secret that combines a basic authentication and *_.gitconfig_* file.
.Prerequisites
* Basic authentication credentials
* *_.gitconfig_* file
.Procedure
* Create a basic authentication secret with a *_.gitconfig_* file
----
$ oc create secret generic <secret_name> \
--from-literal=username=<user_name> \
--from-literal=password=<password> \
--from-file=</path/to/.gitconfig> \
--type=kubernetes.io/basic-auth
----

27
modules/builds-source-secret-combinations-gitconfig-ca.adoc Normal file
View File

@@ -0,0 +1,27 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-combinations-gitconfig-ca.adoc[leveloffset=+1]
[id='builds-source-secret-combinations-gitconfig-ca-{context}']
= Create a secret that combines a *_.gitconfig_* file and CA certificate
You can combine the different methods for creating source clone secrets for your
specific needs, such as a secret that combines a *_.gitconfig_* file and CA certificate.
.Prerequisites
* .gitconfig file
* CA certificate
.Procedure
* Create a secret that combines a *_.gitconfig_* file and CA certificate
----
$ oc create secret generic <secret_name> \
--from-file=ca.crt=<path/to/certificate> \
--from-file=<path/to/.gitconfig>
----

28
modules/builds-source-secret-combinations-ssh-gitconfig.adoc Normal file
View File

@@ -0,0 +1,28 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-combinations-ssh-gitconfig.adoc[leveloffset=+1]
[id='builds-source-secret-combinations-ssh-gitconfig-{context}']
= Create a SSH-based authentication secret with a *_.gitconfig_* file
You can combine the different methods for creating source clone secrets for your
specific needs, such as a SSH-based authentication secret with a *_.gitconfig_* file.
.Prerequisites
* SSH authentication
* .gitconfig file
.Procedure
* Create a SSH-based authentication secret with a *_.gitconfig_* file
----
$ oc create secret generic <secret_name> \
--from-file=ssh-privatekey=<path/to/ssh/private/key> \
--from-file=<path/to/.gitconfig> \
--type=kubernetes.io/ssh-auth
----

12
modules/builds-source-secret-combinations.adoc Normal file
View File

@@ -0,0 +1,12 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-combinations.adoc[leveloffset=+1]
[id='builds-source-secret-combinations-{context}']
= Source secret combinations
You can combine the different methods for creating source clone secrets for your
specific needs.

50
modules/builds-source-secret-ssh-key-auth.adoc Normal file
View File

@@ -0,0 +1,50 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-ssh-key-auth.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='source-secrets-ssh-key-auth-{context}']
= Source code SSH key authentication
The repository keys are usually located in the *_$HOME/.ssh/_* directory, and
are named `id_dsa.pub`, `id_ecdsa.pub`, `id_ed25519.pub`, or `id_rsa.pub` by
default.
. Prerequisites
* SSH key based authentication requires a private SSH key.
.Procedure
[NOTE]
====
Creating a passphrase for the SSH key prevents {product-title} from building.
When prompted for a passphrase, leave it blank.
====
Two files are created: the public key and a corresponding private key (one of
`id_dsa`, `id_ecdsa`, `id_ed25519`, or `id_rsa`). With both of these in place,
consult your source control management (SCM) system's manual on how to upload
the public key. The private key is used to access your private repository.
. Generate SSH key credentials:
----
$ ssh-keygen -t rsa -C "your_email@example.com"
----
. Before using the SSH key to access the private repository, create the secret:
----
$ oc create secret generic <secret_name> \
--from-file=ssh-privatekey=<path/to/ssh/private/key> \
--type=kubernetes.io/ssh-auth
----

43
modules/builds-source-secret-trusted-ca.adoc Normal file
View File

@@ -0,0 +1,43 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-secret-trusted-ca.adoc[leveloffset=+1]
// Base the file name and the ID on the module title. For example:
// * file name: doing-procedure-a.adoc
// * ID: [id='doing-procedure-a']
// * Title: = Doing procedure A
[id='source-secrets-trusted-ca-{context}']
= Source code trusted certificate authorities
The set of TLS certificate authorities (CA) that are trusted during a `git clone`
operation are built into the {product-title} infrastructure images. If your Git
server uses a self-signed certificate or one signed by an authority not trusted
by the image, you can create a secret that contains the certificate or disable
TLS verification.
If you create a secret for the `CA certificate`, {product-title} uses it to access
your Git server during the `git clone` operation. Using this method is
significantly more secure than disabling Git's SSL verification, which accepts
any TLS certificate that is presented.
.Procedure
* Create a secret with a CA certificate file.
.. If your CA uses Intermediate Certificate Authorities, combine the
certificates for all CAs in a *_ca.crt_* file. Run the following command:
+
----
$ cat intermediateCA.crt intermediateCA.crt rootCA.crt > ca.crt
----
.. Create the secret:
+
----
$ oc create secret generic mycert --from-file=ca.crt=</path/to/file> <1>
----
<1> You must use the key name *_ca.crt_*.

28
modules/builds-source-to-image.adoc Normal file
View File

@@ -0,0 +1,28 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-source-to-image.adoc[leveloffset=+1]
[id='builds-source-to-image-{context}']
= Source-to-image strategy
When using a `Source` strategy, all defined input secrets are copied to their
respective `destinationDir`. If you left `destinationDir` empty, then the
secrets are placed in the working directory of the builder image.
The same rule is used when a `destinationDir` is a relative path; the secrets
are placed in the paths that are relative to the image's working directory.
The final directory in the `destinationDir` path is created if it does not exist in the builder image.
All preceding directories in the `destinationDir` must exist, or an error will occur.
[NOTE]
====
Input secrets are added as world-writable (have `0666` permissions) and will
be truncated to size zero after executing the *_assemble_* script. This means
that the secret files will exist in the resulting image, but they will be empty
for security reasons.
Input ConfigMaps are not truncated after the *_assemble_* script completes.
====

70
modules/builds-using-external-artifacts.adoc Normal file
View File

@@ -0,0 +1,70 @@
// Module included in the following assemblies:
//
// * assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-using-external-artifacts.adoc[leveloffset=+1]
[id='builds-using-external-artifacts-{context}']
= External artifacts
It is not recommended to store binary files in a source repository. Therefore,
you may find it necessary to define a build which pulls additional files (such
as Java *_.jar_* dependencies) during the build process. How this is done
depends on the build strategy you are using.
For a `Source` build strategy, you must put appropriate shell commands into
the *_assemble_* script:
.*_.s2i/bin/assemble_* File
[source,bash]
----
#!/bin/sh
APP_VERSION=1.0
wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar
----
.*_.s2i/bin/run_* File
[source,bash]
----
#!/bin/sh
exec java -jar app.jar
----
[NOTE]
====
For more information on how to control which *_assemble_* and *_run_* script is
used by a Source build, see Overriding Builder Image Scripts.
====
ifndef::openshift-online[]
For a `Docker` build strategy, you must modify the *_Dockerfile_* and invoke
shell commands with the
link:https://docs.docker.com/engine/reference/builder/#run[`RUN` instruction]:
.Excerpt of *_Dockerfile_*
----
FROM jboss/base-jdk:8
ENV APP_VERSION 1.0
RUN wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar
EXPOSE 8080
CMD [ "java", "-jar", "app.jar" ]
----
endif::[]
In practice, you may want to use an environment variable for the file location
so that the specific file to be downloaded can be customized using an
environment variable defined on the `BuildConfig`, rather than updating the
ifndef::openshift-online[]
*_Dockerfile_* or
endif::[]
*_assemble_* script.
You can choose between different methods of defining environment variables:
* Using the *_.s2i/environment_* file] (only for a Source build strategy)
* Setting in `BuildConfig`
* Providing explicitly using `oc start-build --env` (only for builds that are triggered
manually)

48
modules/builds-using-proxy-git-cloning.adoc Normal file
View File

@@ -0,0 +1,48 @@
// Module included in the following assemblies:
//* assembly/builds
// This module can be included from assemblies using the following include statement:
// include::<path>/builds-using-proxy-git-cloning.adoc[leveloffset=+1]
[id="build-using-proxy-git-cloning_{context}"]
= Using a Proxy
If your Git repository can only be accessed using a proxy, you can define the
proxy to use in the `source` section of the `BuildConfig`. You can configure
both a HTTP and HTTPS proxy to use. Both fields are optional. Domains for which
no proxying should be performed can also be specified in the *NoProxy* field.
[NOTE]
====
Your source URI must use the HTTP or HTTPS protocol for this to work.
====
[source,yaml]
----
source:
git:
uri: "https://github.com/openshift/ruby-hello-world"
httpProxy: http://proxy.example.com
httpsProxy: https://proxy.example.com
noProxy: somedomain.com, otherdomain.com
----
ifdef::openshift-enterprise,openshift-origin[]
Cluster administrators can also configure a global proxy for Git cloning using Ansible.
endif::[]
[NOTE]
====
For Pipeline strategy builds, given the current restrictions with the Git
plug-in for Jenkins, any Git operations through the Git plug-in will not
leverage the HTTP or HTTPS proxy defined in the `BuildConfig`. The Git plug-in
only will use the proxy configured in the Jenkins UI at the Plugin Manager
panel. This proxy will then be used for all git interactions within Jenkins,
across all jobs.
====
. Additional resources
* You can find instructions on how to configure proxies through
the Jenkins UI at
link:https://wiki.jenkins-ci.org/display/JENKINS/JenkinsBehindProxy[JenkinsBehindProxy].

41
modules/define-build-inputs.adoc
View File

@@ -1,41 +0,0 @@
// Module included in the following assemblies:
//
// <List assemblies here, each on a new line>
// This module can be included from assemblies using the following include statement:
// include::<path>/define-build-inputs.adoc[leveloffset=+1]
// The file name and the ID are based on the module title. For example:
// * file name: my-concept-module-a.adoc
// * ID: [id='my-concept-module-a_{context}']
// * Title: = My concept module A
//
// The ID is used as an anchor for linking to the module. Avoid changing
// it after the module has been published to ensure existing links are not
// broken.
//
// The `context` attribute enables module reuse. Every module's ID includes
// {context}, which ensures that the module has a unique ID even if it is
// reused multiple times in a guide.
//
// In the title, include nouns that are used in the body text. This helps
// readers and search engines find information quickly.
// Do not start the title with a verb. See also _Wording of headings_
// in _The IBM Style Guide_.
[id="define-build-inputs_{context}"]
= Define Build Inputs
This paragraph is the concept module introduction and is only optional. Include it to provide a short overview of the module.
The contents of a concept module give the user descriptions and explanations needed to understand and use a product.
* Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
* Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
* Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
[discrete]
== Additional resources
* A bulleted list of links to other material closely related to the contents of the concept module.
* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].