Description of the Build Process
This document describes the process used to build images using OSBS. It sums up how different components of the system communicate to achieve the result.
This document mentions several components that communicate with each other:
- user runs
osbs buildor a Python process calls
- osbs-client determines the base layer for the image it's building; let's call base layer BL and the image that's being built IM.
- osbs-client determines name of Openshift's BuildConfig to use and makes sure no other build is running for it (only one build for a given
BuildConfigis allowed to be running at a time).
- osbs-client updates Openshift's
BuildConfigvalues for current build of IM. Most importantly, it makes sure that:
ImageStreamfor BL is in triggers. This ensures that when BL is rebuilt, IM is rebuilt as well.
is_autorebuildlabel is set to
"false", so that atomic-reactor knows that this is a build executed by user.
BuildConfig's source git ref names the git branch the build is from
bump_releaseconfiguration names the branch's commit the initial build is from
stop_autorebuild_if_disabledconfiguration names the config file where autorebuilds are enabled/disabled, see OSBS repo configuration file
- osbs-client starts the Openshift build from
- Openshift spawns a new build container that contains atomic-reactor inside.
CheckAndSetRebuildPluginis run. This determines whether the build is an automatically triggered autorebuild by examining
is_autorebuildlabel. If this is autorebuild, then TODO. If this is not autorebuild, then the
is_autorebuildlabel of the
BuildConfigis set to
"true". This is done in order to ensure that all subsequent builds (except user-executed builds) are marked as autorebuild.
- atomic-reactor builds the image.
- Assuming the build is successful, atomic-reactor pushes the built image into registry and runs post-build plugins. These can vary depending on configuration, but usually it means pushing image to Pulp or so.
ImportImagePluginis run, which checks whether ImageStream for IM exists. If not, it creates it. Then, either way, it imports newly built IM into the
ImageStream. If there are already some other images that use IM as their base image, they get rebuilt.
docker registry v2 API (current workflow)
Since in v2 there is no file-like representation of an image, you can transport image only via registry protocol.
In order to create a v2 form, you need an instance of distribution registry. Once you push the built image there, it's up to you, if you want to move the v2 image into pulp registry. That process is called sync.
- upstream docker registry — can be configured with
registry_uri = registry.example.com
if registry requires authentication, a dockercfg should be stored in the secret:
registry_secret = dockercfg_secret
- for backwards compatibility reasons, it is possible to suffix
registry_uri = registry.example.com/v2
Configuration of pulp registry where images should be synced can be done via:
pulp_sync_registry_name = stage-pulp
If this is not specified, value of
pulp_registry_name is used.
About v1 builds
OSBS no longer supports v1 builds.
OSBS Repo Configuration File
OSBS repo config file is a file that resides in the top level of built Git repo. It is currently not mandatory. The default name is
[autorebuild] section is supported and
enabled argument inside that. The
enabled argument is a boolean, recognized values are 0, false, 1 and true (case insensitive). For example:
enabled is true by default (e.g. if the file is not present or the value is not set in the config file).