diff --git a/dev_guide/builds.adoc b/dev_guide/builds.adoc index 842da714cc60..d42979b6e560 100644 --- a/dev_guide/builds.adoc +++ b/dev_guide/builds.adoc @@ -6,13 +6,13 @@ :experimental: :toc: macro :toc-title: +:prewrap!: toc::[] == Overview -A link:../architecture/core_concepts/builds_and_image_streams.html#builds[build] -is a process of creating runnable images to be used on OpenShift. There are -three build strategies: +A link:../architecture/core_concepts/builds_and_image_streams.html#builds[build] is a process of creating +runnable images to be used on OpenShift. There are three build strategies: - link:../architecture/core_concepts/builds_and_image_streams.html#source-build[Source-To-Image] - link:../architecture/core_concepts/builds_and_image_streams.html#docker-build[Docker] @@ -20,11 +20,11 @@ three build strategies: == Defining a buildConfig -A `*buildConfig*` describes a single build definition and a set of -link:#build-triggers[triggers] for when a new build should be created. +A `*buildConfig*` describes a single build definition and a +set of link:#triggers[triggers] for when a new build should be created. -A buildConfig is a REST object, which can be used in a POST to the API server to -create a new instance. The following configuration results in a new build +A `*buildConfig*` is a REST object, which can be used in a POST to the API server to +create a new instance. The following example `*buildConfig*` results in a new build every time a Docker image tag or the source code changes: ==== @@ -80,19 +80,24 @@ every time a Docker image tag or the source code changes: } ---- -<1> This specification will create a new buildConfig named ruby-sample-build. -<2> You can specify a list of triggers, which causes a new build to be created. -The `*ImageChange*` trigger creates a new build each time the Docker image specified in the `*strategy.from*` field changes. The `*Github*` and `*Generic*` triggers starts the build when a callback is made from the GitHub or other source code repository hosting service, indicating change in the source code specified in `*source*` section. -<3> The `*source*` section defines the source code repository location. You can provide additional options, such as `*sourceSecret*` or `*contextDir*` here. -<4> The `*strategy*` section describes the build strategy used to execute the build. You can specify `*Source*`, `*Docker*` and `*Custom*` strategies here. This specification uses the `*ruby-20-centos7*` Docker image that Source-To-Image will use for the application build. -<5> After the Docker image is successfully built, it will be pushed into the repository described in the `*output*` section. +<1> This specification will create a new `*buildConfig*` named +*ruby-sample-build*. +<2> You can specify a list of link:#build-triggers[triggers], which cause a new build to be created. +<3> The `*Source*` section defines the source code repository location. You can +provide additional options, such as `*sourceSecret*` or `*contextDir*` here. +<4> The `*strategy*` section describes the build strategy used to execute the +build. You can specify `*Source*`, `*Docker*` and `*Custom*` strategies here. +This above example uses the `*ruby-20-centos7*` Docker image that +Source-To-Image will use for the application build. +<5> After the Docker image is successfully built, it will be pushed into the +repository described in the `*output*` section. ==== -== Defining an incremental buildConfig -The Source-To-Image (S2I) strategy provides an option to perform incremental builds, -which means it will reuse artifacts from previously built image. To create an incremental -build one needs to create a BuildConfig as previously explained, but with a slight -modification in strategy definition as presented below: +== Defining an Incremental buildConfig +The Source-To-Image (S2I) strategy provides an option to perform incremental +builds, which means it will reuse artifacts from previously-built images. To +create an incremental build, create a `*buildConfig*`, but with a modification in +strategy definition: ==== @@ -112,57 +117,58 @@ modification in strategy definition as presented below: } ---- -<1> You need to specify an image that supports incremental builds. Note that the S2I -images provided by the OpenShift do not implement artifact reuse, so setting `incremental` - to `true` will have no effect on Builds using those builder images. - +<1> Specify an image that supports incremental builds. The S2I images provided +by OpenShift do not implement artifact reuse, so setting `incremental` to +`true` will have no effect on Builds using those builder images. <2> This flag controls whether an incremental build is attempted. If the builder -image does not support incremental builds, the build will still succeed but you +image does not support incremental builds, the build will still succeed, but you will get a log message stating the incremental build was not successful because of a missing `save-artifacts` script. ==== -NOTE: For information on how to create a builder image supporting incremental builds see link:../creating_images/s2i.html[creating images guide]. +[NOTE] +For information on how to create a builder image supporting incremental builds +see the link:../creating_images/s2i.html[creating images guide]. == Starting a Build -You can manually invoke a build using the following command: +Manually invoke a build using the following command: -**** -`$ oc start-build __` -**** +---- +$ oc start-build +---- -A build can be re-run using the `--from-build` flag: +Re-run a build using the `--from-build` flag: -**** -`$ oc start-build --from-build=__` -**** +---- +$ oc start-build --from-build= +---- Specify the `--follow` flag to stream the build's logs in stdout: -**** -`$ oc start-build __ --follow` -**** +---- +$ oc start-build --follow +---- == Canceling a Build -You can manually cancel a build using the following command: +Manually cancel a build using the following command: -**** -`$ oc cancel-build __` -**** +---- +$ oc cancel-build +---- == Accessing Build Logs To allow access to build logs, use the following command: -**** -`$ oc build-logs __` -**** +---- +$ oc build-logs +---- *Source Build Logs* -link:../architecture/core_concepts/builds_and_image_streams.html#source-build[Source builds] by default -show full output of the *_assemble_* script and all subsequent errors. -To enable more verbose output, you can pass the `*BUILD_LOGLEVEL*` -environment variable as part of the `*sourceStrategy*` in BuildConfig: +By default, link:../architecture/core_concepts/builds_and_image_streams.html#builds[source +builds] show full output of the *_assemble_* script and all subsequent errors. +To enable more verbose output, pass the `*BUILD_LOGLEVEL*` environment variable +as part of the `*sourceStrategy*` in a `*buildConfig*`: ==== @@ -190,7 +196,7 @@ If both `--loglevel` and `BUILD_LOGLEVEL` are specified, `BUILD_LOGLEVEL` takes Available log levels for Source builds are as follows: [horizontal] -Level 0:: Produces output from containers running the *_assemble_* script and all encountered errors. This is the default. +Level 0:: Produces output from containers running the *_assemble_* script and all encountered errors. This is the default. Level 1:: Produces basic information about the executed process. Level 2:: Produces very detailed information about the executed process. Level 3:: Produces very detailed information about the executed process, and a listing of the archive contents. @@ -198,9 +204,9 @@ Level 5:: Produces everything mentioned on previous levels and additionally prov == Source Code The source code location is one of the required parameters for the -`*BuildConfig*`. The build uses this location and fetches the source code that +`*buildConfig*`. The build uses this location and fetches the source code that is later built. The source code location definition is part of the -`*parameters*` section in the `*BuildConfig*`: +`*parameters*` section in the `*buildConfig*`: ==== @@ -217,12 +223,11 @@ is later built. The source code location definition is part of the ---- <1> The `*type*` field describes which SCM is used to fetch your source code. -<2> In this example, the `*git*` field contains the URI to the remote Git -repository where your source code lives. It might optionally specify the `*ref*` -field if you want to check out a specific Git reference. A valid `*ref*` can be -a SHA1 tag or a branch name. +<2> 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. <3> The `*contextDir*` field allows you to override the default location inside -the source code repository, where the build looks for the application source +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. ==== @@ -231,16 +236,17 @@ default location (the root folder) using this field. == Source Environment There are two ways to make environment variables available to the -link:../architecture/core_concepts/builds_and_image_streams.html#source-build[Source -build] process and resulting \image: link:#environment-files[environment files] -and link:#buildconfig-environment[BuildConfig environment] values. +link:../architecture/core_concepts/builds_and_image_streams.html#builds[source build] +process and resulting \image: link:#environment-files[environment files] and +link:#buildconfig-environment[buildConfig environment] values. === Environment files -Source build enables you to set environment values (one per line) -inside your application, by specifying them in a *_.sti/environment_* file in the -source repository. The environment variables specified in this file are present during +Source build enables you to set environment values (one per line) inside your +application, by specifying them in a *_.sti/environment_* file in the source +repository. The environment variables specified in this file are present during the build process and in the final docker image. The complete list of supported -environment variables is available in the documentation for each image. +environment variables is available in the +link:../using_images/overview.html[documentation] for each image. If you provide a *_.sti/environment_* file in your source repository, S2I reads this file during the build. This allows customization of the build behavior as @@ -253,14 +259,14 @@ build. In addition to builds, the specified environment variables are also available in the running application itself. For example, you can add -`*RAILS_ENV=development*` in the *_.sti/environment_* file to cause the Rails -application to be started in `development` mode instead of `production`. +`*RAILS_ENV=development*` to the *_.sti/environment_* file to cause the Rails +application to start in `development` mode instead of `production`. === BuildConfig Environment -You can add environment variables to the SourceStrategy definition of the BuildConfig. -Environment variables defined there will be visible during the *_assemble_* script -execution and will be defined in the output image, making them also available to -the *_run_* script and application code. +You can add environment variables to the `*sourceStrategy*` definition of the +`*buildConfig*`. Defined environment variables are visible during the *_assemble_* +script execution and will be defined in the output image, making them also +available to the *_run_* script and application code. For example disabling assets compilation for your Rails application: @@ -282,9 +288,9 @@ For example disabling assets compilation for your Rails application: ==== == Build Triggers -When defining a `*BuildConfig*`, you can define triggers to control the -circumstances in which a build should be run for the `*BuildConfig*`. There are two -types of triggers available: +When defining a `*buildConfig*`, you can define triggers to control the +circumstances in which the `*buildConfig*` should be run. There are two types of +triggers available: * link:#webhook-triggers[Webhook] * link:#image-change-triggers[Image change] @@ -296,12 +302,12 @@ https://developer.github.com/webhooks/[GitHub webhooks] or Generic webhooks. *GitHub Webhooks* -https://developer.github.com/webhooks/creating/[GitHub webhooks] can handle the -call made by GitHub when a repository is updated. When defining the trigger, you -must specify a *secret* as part of the URL you supply to GitHub when -configuring the webhook. The *secret* ensures that only you and your -repository can trigger the build. The following example is a trigger definition -JSON within the `*BuildConfig*`: +https://developer.github.com/webhooks/creating/[GitHub webhooks] handle the call +made by GitHub when a repository is updated. When defining the trigger, you must +specify a link:../dev_guide/secrets.html[`*secret*`] as part of the URL you supply +to GitHub when configuring the webhook. The `*secret*` ensures that only you and +your repository can trigger the build. The following example is a trigger +definition JSON within the `*buildConfig*`: ==== @@ -318,22 +324,22 @@ JSON within the `*BuildConfig*`: The payload URL is returned as the GitHub Webhook URL by the `describe` command (see link:#describe-buildconfig[below]), and is structured as follows: -**** -`http://__/osapi/v1/namespaces/__/buildconfigs/__/webhooks/__/github` -**** +---- +http:///osapi/v1/namespaces//buildconfigs//webhooks//github +---- *Generic Webhooks* Generic webhooks can be invoked from any system capable of making a web -request. As with a GitHub webhook, you must specify a *secret* when defining the -trigger, and the caller must provide this *secret* to trigger the build. The -following is an example trigger definition JSON within the `*BuildConfig*`: +request. As with a GitHub webhook, you must specify a `*secret*` when defining the +trigger, and the caller must provide this `*secret*` to trigger the build. The +following is an example trigger definition JSON within the `*buildConfig*`: ==== ---- { - "type": "Generic", + "type": "generic", "generic": { "secret": "secret101" } @@ -344,9 +350,9 @@ following is an example trigger definition JSON within the `*BuildConfig*`: To set up the caller, supply the calling system with the URL of the generic webhook endpoint for your build: -**** -`http://__/osapi/v1/namespaces/__/buildconfigs/__/webhooks/__/generic` -**** +---- +http:///osapi/v1/namespaces//buildconfigs//webhooks//generic +---- The endpoint can accept an optional payload with the following format: @@ -379,9 +385,9 @@ The endpoint can accept an optional payload with the following format: Use the following command to display the webhook URLs associated with a build configuration: -**** -`oc describe buildConfig __` -**** +---- +$ oc describe buildConfig +---- If the above command does not display any webhook URLs, then no webhook trigger is defined for that build configuration. @@ -395,7 +401,7 @@ latest RHEL base image. Configuring an image change trigger requires the following actions: -1. Define an `*ImageStream*` that points to the upstream image you want to +. Define an `*ImageStream*` that points to the upstream image you want to trigger on: + ==== @@ -416,8 +422,7 @@ located at `__/__/ruby-20-centos7`. The `__` is defined as a service with the name `docker-registry` running in OpenShift. -2. Define a build with a strategy that consumes the image stream; for -example: +. Define a build with a strategy that consumes the image stream: + ==== @@ -436,25 +441,26 @@ example: ---- ==== + -In this case, the Source strategy definition is consuming the `latest` tag of the -ImageStream named `ruby-20-centos7` located within this namespace. +In this case, the `*sourceStrategy*` definition is consuming the `latest` tag of +the ImageStream named `ruby-20-centos7` located within this namespace. -3. Define an image change trigger: +. Define an image change trigger: + ==== ---- { - "type": "ImageChange" + "type": "imageChange", + "imageChange": {} } ---- ==== + -This defines an image change trigger which monitors `*ImageStream*` and `*Tag*` defined -by the Strategy's From field. When a change occurs, a new build is triggered -and is supplied with an immutable Docker tag that points to the new image that -was just created. This new image will be used by the Strategy when it executes -for the build. For example, the resulting build will be: +This defines an image change trigger that monitors the `*ImageStream*` and +`*Tag*` as defined by the Strategy's *From* field. When a change occurs, a new +build is triggered and is supplied with an immutable Docker tag that points to +the new image that was just created. This new image will be used by the Strategy +when it executes for the build. For example, the resulting build will be: ==== @@ -474,30 +480,29 @@ for the build. For example, the resulting build will be: ==== This ensures that the triggered build uses the new image that was just pushed to -the repository, and the build can be re-run any time with exactly the same -inputs. +the repository, and the build can be re-run any time with the same inputs. -In addition to setting the image field for all `*Strategy*` types, for custom builds, -the `OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE` environment variable is checked. If it does -not exist, then it is created with the immutable image reference. If it does exist -then it is updated with the immutable image reference. +In addition to setting the image field for all `*Strategy*` types, for custom +builds, the `OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE` environment variable is checked. +If it does not exist, then it is created with the immutable image reference. If +it does exist then it is updated with the immutable image reference. If a build is triggered due to a webhook trigger or manual request, the build that is created uses the `*immutableid*` resolved from the -`*ImageStream*` referenced by the `*Strategy*`. This ensures that builds +`*ImageStream*` referenced by the `*Strategy*`. This ensures that builds are performed using consistent image tags for ease of reproduction. [#using-docker-credentials-for-pushing-and-pulling-images] == Using Docker Credentials for Pushing and Pulling Images -You must supply the `.dockercfg` file with valid Docker Registry credentials in -order to push the output image into a private Docker Registry or pull the -builder image from the private Docker Registry that requires authentication. -For the OpenShift Docker Registry, you don't have to do this because the Secrets -are generated automatically for you by OpenShift. +Supply the `.dockercfg` file with valid Docker Registry credentials in order to +push the output image into a private Docker Registry or pull the builder image +from the private Docker Registry that requires authentication. For the OpenShift +Docker Registry, you don't have to do this because `*secrets*` are generated +automatically for you by OpenShift. -The *_.dockercfg_* JSON file exists in your home directory by default and has the -following format: +The *_.dockercfg_* JSON file is found in your home directory by default and has +the following format: ==== @@ -517,36 +522,33 @@ following format: You can define multiple Docker 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 the https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[Secret] -resource, which is used to store your configuration and passwords. - -To create the `*Secret*` resource from your local `.dockercfg` file, you can run -following command: +command. The file will be created if it does not exist. Kubernetes provides +https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[`*secret*`], +which are used to store your configuration and passwords. +. Create the `*secret*` from your local `.dockercfg` file: ++ ==== ---- $ oc secrets new dockerhub ~/.dockercfg ---- ==== ++ +This generates a JSON specification of the `*secret*` named *dockerhub* and +creates the object. -This command generates JSON specification of the Secret resource named -'dockerhub' and creates the object. - -Once you have created your Secret, it must be added to the builder service account -in order to be used. - +. Once the `*secret*` is created, add it to the builder service account: ++ ==== ---- $ oc secrets add serviceaccount/builder secrets/dockerhub ---- ==== -Once you have the `*Secret*` created, you can 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*`: - +. 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*: ++ ==== ---- @@ -565,7 +567,7 @@ that you created, which in the above example is `*dockerhub*`: ---- ==== -To pull the builder Docker image from a private Docker registry specify the +. Pull the builder Docker image from a private Docker registry by specifying the `PullSecret` field, which is part of the build strategy definition: ==== @@ -591,10 +593,10 @@ To pull the builder Docker image from a private Docker registry specify the [#using-private-repositories-for-builds] == Using Private Repositories for Builds -You must supply valid credentials to build an application from a private repository. +Supply valid credentials to build an application from a private repository. Currently, only SSH key based authentication is supported. The repository keys are located in the `$HOME/.ssh/` directory, and are named `id_dsa.pub`, -`id_ecdsa.pub`, `id_ed25519.pub` or `id_rsa.pub` by default. Generate SSH key +`id_ecdsa.pub`, `id_ed25519.pub`, or `id_rsa.pub` by default. Generate SSH key credentials with the following command: ==== @@ -604,18 +606,25 @@ $ ssh-keygen -t rsa -C "your_email@example.com" ---- ==== -As a result, two files will be created: the public key (as explained above) and a -corresponding private key (one of `id_dsa`, `id_ecdsa`, `id_ed25519` or -`id_rsa`). With both of these in place you should consult your source control -management (SCM) system's manual on how to upload the public key. The private -key will be used to access your private repository. +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 will be used to access your private repository. -The -https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[Secret] -resource is used to store your keys. Create the `*Secret*` first before using -the SSH key to access the private repository. The `*data*` field for the -`*Secret*` object must contain your private key with the value set to the -base64-encoded content of that file: +A link:dev_guide/secrets[`*secret*`] +is used to store your keys. + +. Create the `*secret*` first before using the SSH key to access the private +repository: ++ +==== +---- +$ osc create -f secret.json +---- +==== + +. The `*data*` field for the `*secret*` must contain your private key with the +value set to the base64-encoded content of that file: ==== @@ -625,9 +634,9 @@ $ base64 -w 0 $HOME/.ssh/id_rsa ---- ==== -Copy the value returned from the above command and place it into the +. Copy the value returned from the above command and place it into the `ssh-privatekey` field in `*_secret.json_*` file: - ++ ==== ---- @@ -645,9 +654,8 @@ Copy the value returned from the above command and place it into the ---- ==== -Then, create the `*Secret*` from the *_secret.json_* file using the following -command: - +. Create a second `*secret*` for Docker from the *_secret.json_* file: ++ ==== ---- @@ -655,10 +663,10 @@ $ oc create -f secret.json ---- ==== -Add a `SourceSecret` field into the `Source` section inside the `BuildConfig` -and set it to the name of the `*Secret*` that you created, in this case -`*scmsecret*`: - +. Add a `*sourceSecret*` field into the `*Source*` section inside the +buildConfig and set it to the name of the `*secret*` that you created, in this +case `*scmsecret*`: ++ ==== ---- @@ -676,7 +684,7 @@ and set it to the name of the `*Secret*` that you created, in this case }, "source": { "git": { - "uri": "git@repository.com:user/app.git" + "uri": "git@repository.com:user/app.git" <1> }, "sourceSecret": { "name": "scmsecret" @@ -695,8 +703,6 @@ and set it to the name of the `*Secret*` that you created, in this case } ---- ==== - -[NOTE] -==== -The URL of private repository is usually in the form `git@example.com:username/repository` +<1> The URL of private repository is usually in the form +`git@example.com:/` ====