Bug 1288488 - [DOCS] Document s2i builder details
[DOCS] Document s2i builder details
Status: NEW
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation (Show other bugs)
Unspecified Unspecified
medium Severity low
: ---
: ---
Assigned To: Gaurav Nelson
Wenjing Zheng
Vikram Goyal
Depends On:
  Show dependency treegraph
Reported: 2015-12-04 06:40 EST by Thien-Thi Nguyen
Modified: 2017-12-23 19:32 EST (History)
5 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed:
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description Thien-Thi Nguyen 2015-12-04 06:40:01 EST
What happens precisely during a Python s2i build?  How about for Ruby?  (etc)
Originally: https://github.com/openshift/openshift-docs/issues/1283
Comment 3 Thien-Thi Nguyen 2015-12-04 08:04:45 EST
In terms of source code, it looks like we want to look at:

- origin/pkg/generate/source/detector.go
- source-to-image/pkg/build/strategies/layered/layered.go

to describe how a particular "platform" is detected and how its constituent files (e.g., requirements.txt for Python) are processed.

This reference documentation should either be centralized in the main overview:

- https://docs.openshift.org/latest/using_images/s2i_images/index.html

or added to each image's overview, with the main overview describing the general detection / processing scheme.
Comment 4 Rodolfo Carvalho 2015-12-04 09:49:29 EST
@Thien-Thi, that's not what I had in mind originally.

The starting point is documenting that the Python image will automatically install project dependencies from a requirements.txt or setup.py.

It should be documented here: https://docs.openshift.org/latest/using_images/s2i_images/python.html

And the code you want to look at is here: https://github.com/openshift/sti-python/blob/master/3.4/s2i/bin/assemble

Next, look at the assemble scripts for other images and document what they are able to do, what input they consume and how.

This is not about detecting what platform to use. No Go code involved...
Comment 5 Thien-Thi Nguyen 2016-03-22 11:00:19 EDT
Hi Rodolfo,

I see Python-specific build details (i.e., `requirements.txt` and `setup.py`) are documented in:


but that there is no (direct) link from:


to it.  So, how about we add one in the latter page's Overview?  I think the word "dependencies" would be the best place.  (I'd make an analogous change w/ the other languages.)  WDYT?
Comment 6 Rodolfo Carvalho 2016-03-22 11:52:52 EDT
It's a "coincidence" that language detection relies on files that I mentioned in https://github.com/openshift/openshift-docs/issues/1283.

The original point is to document, in a high level, what an s2i builder does.

On the OpenShift/Source-To-Image side, there's the git cloning of a repository, then the files are streamed into a container, without the .git dir, etc etc.
Then the assemble script is executed:

For Python, as an example:

It will do several steps, rely on env vars, etc.

What I miss is documentation explaining how your code gets from a Git repository into a final image, and what else has happened as part of the build (download and install dependencies, etc).

Most of it is language/builder-image independent, while some is specific to each builder image, like each language has a different package management solution, a different way to list dependencies, and so on.

We can chat face-to-face tomorrow or any other time for further clarification.
Comment 7 Thien-Thi Nguyen 2016-04-04 11:31:57 EDT
Related: https://trello.com/c/WpdJNDz7
Comment 8 Rodolfo Carvalho 2016-04-04 12:10:27 EDT
@Thien-Thi the Trello link above refers to new/proposed functionality.
The relationship with this BZ is that documentation produced out of this BZ would require updates in the future with that card implemented, do you agree?

We may want to cross reference -- add a link to this BZ in that card. If you don't have access to that, I can add the link there pointing here.
Comment 9 Thien-Thi Nguyen 2016-04-04 13:19:18 EDT
Hi Rodolfo,

(In reply to Rodolfo Carvalho from comment #8)
> [...] new/proposed functionality.  The relationship with this BZ
> is that documentation produced out of this BZ would require
> updates in the future with that card implemented, do you agree?

Thanks for the clarification.  It sounds like you're saying that
card has no immediate relevance to this BZ, although in the
future, work that goes into this BZ will need to be modified once
the work for that card lands.

> We may want to [xref]

Good idea.  Done.

By the way, thanks for the interview the other day.  Here are my
notes from the session (additions/corrections welcome):

* explain flow:
*** input: code + builder image
*** builder image:
***** explicitly defined
***** auto-detected via ‘oc new-app’ (plan: link)
*** LANG-image provided assemble script capabilities
***** general flow
***** hooks for each LANG -- e.g., check requirements.txt (Python), etc
***** DOES NOT handle non-LANG-modules (cannot use yum, reason: not root)
*** user can provide assemble script

Note You need to log in before you can comment on or make changes to this bug.