Skip to content

Defining a buildConfig #444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adellape merged 1 commit into from
Jun 9, 2015
Merged

Defining a buildConfig #444

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
295 changes: 16 additions & 279 deletions architecture/core_objects/builds.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,75 +15,12 @@ A build is the end result of transforming input parameters, typically source cod
For a list of build commands, see the
link:../../dev_guide/builds.html[Developer's Guide].

== BuildConfig
The `BuildConfig` object is the definition of the entire build process, and is dictated by link:../../dev_guide/builds.html#build-triggers[build triggers]:

====
----
apiVersion: v1beta3
kind: BuildConfig
metadata:
labels:
name: ruby-sample-build
template: application-template-stibuild
name: ruby-sample-build
namespace: ruby
resourceVersion: "7246"
selfLink: /osapi/v1beta3/namespaces/ruby/buildconfigs/ruby-sample-build
uid: 9c3d9693-0822-11e5-9deb-080027c5bfa9
spec:
output: <1>
to:
kind: ImageStreamTag
name: origin-ruby-sample:latest
resources: {} <2>
source: <3>
git:
uri: git://github.com/openshift/ruby-hello-world.git
type: Git
strategy: <4>
sourceStrategy:
from:
kind: ImageStreamTag
name: ruby-20-centos7:latest
incremental: true
type: Source
triggers:
- github: <5>
secret: secret101
type: github
- generic: <6>
secret: secret101
type: generic
- imageChange: <7>
lastTriggeredImageID: openshift/ruby-20-centos7:latest
type: imageChange

----
<1> *output* describes the resulting ImageStream source to which the
image should be pushed.
<2> *resources* describes the resource limits (cpu, memory) that should be used
by pods that run a build.
<3> *source* describes the SCM used to locate the sources. Currently only
supports Git.
<4> *strategy* describes which build type is invoked along with build type
specific details.
<5> *gitHub* triggers are Github-specific webhooks that specify which repository
changes, such as a new commit, should invoke a new build. This trigger is
specific to the GitHub API.
<6> *generic* triggers are similar to GitHub webhooks in that they invoke a new
build when notified, but different in that the payload is slightly different
than GitHub's.
<7> *imageChange* triggers define a trigger which is invoked upon availability
of a new image in the specified ImageStream.
====

== Build Strategies

There are three available link:openshift_model.html#build-strategies[build strategies]:

* link:#docker-build[Docker build]
* link:#sti-build[STI build]
* link:#source-build[Source-to-Image build]
* link:#custom-build[Custom build]

The resulting object depends on the builder used to create the image.
Expand All @@ -92,31 +29,31 @@ The resulting object depends on the builder used to create the image.
=== Docker Build
Docker builds invoke the plain https://docs.docker.com/reference/commandline/cli/#build[docker build command], and therefore expect a repository with a *_Dockerfile_* and all required directories.

[#sti-build]
=== STI Build
link:../../creating_images/sti.html[Source-to-image (STI)] is a tool for
[#source-build]
=== Source-to-Image Build
link:../../creating_images/sti.html[Source-to-Image (S2I)] is a tool for
building reproducible Docker images. It produces ready-to-run images by
injecting a user source into a docker image and assembling a new docker image.
The new image incorporates the base image and built source, and is ready to use
with the `docker run` command. STI supports incremental builds, which re-use
with the `docker run` command. S2I supports incremental builds, which re-use
previously downloaded dependencies, previously built artifacts, etc.

The advantages of STI include:
The advantages of S2I include:

[horizontal]
Image flexibility:: STI scripts can be written to layer application code onto
Image flexibility:: S2I scripts can be written to layer application code onto
almost any existing Docker image, taking advantage of the existing ecosystem.
Note that, currently, STI relies on `tar` to inject application
Note that, currently, S2I relies on `tar` to inject application
source, so the image needs to be able to process tarred content.

Speed:: With STI, the assemble process can perform a large number of complex
Speed:: With S2I, the assemble process can perform a large number of complex
operations without creating a new layer at each step, resulting in a fast
process. In addition, STI scripts can be written to re-use artifacts stored in a
process. In addition, S2I scripts can be written to re-use artifacts stored in a
previous version of the application image rather than having to download or
build them each time the build is run.

Patchability:: STI allows you to rebuild the application consistently if an
underlying image needs a patch due to a security issue
Patchability:: S2I allows you to rebuild the application consistently if an
underlying image needs a patch due to a security issue.

Operational efficiency:: By restricting build operations instead of allowing
arbitrary actions, such as in a *_Dockerfile_*, the PaaS operator can avoid
Expand All @@ -125,14 +62,14 @@ accidental or intentional abuses of the build system.
Operational security:: Building an arbitrary *_Dockerfile_* exposes the host
system to root privilege escalation. This can be exploited by a malicious user
because the entire docker build process is run as a user with docker privileges.
STI restricts the operations performed as a root user, and can run the scripts
as an individual user.
S2I restricts the operations performed as a root user, and can run the scripts
as an non-root user.

User efficiency:: STI prevents developers from performing arbitrary `yum
User efficiency:: S2I prevents developers from performing arbitrary `yum
install` type operations during their application build, which results in slow
development iteration.

Ecosystem:: STI encourages a shared ecosystem of images where you can leverage
Ecosystem:: S2I encourages a shared ecosystem of images where you can leverage
best practices for your applications.

[#custom-build]
Expand All @@ -141,203 +78,3 @@ Custom builds allow developers to define the specific builder image responsible
for the entire build process. The custom builder image is a plain Docker image
with embedded build process logic, such as building RPMs or building base Docker
images.

[#using-docker-credentials-for-pushing-and-pulling-images]
== Using Docker Credentials for Pushing and Pulling Images

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.

The *_.dockercfg_* JSON file exists in your home directory by default and has
following format:

====

----
{
"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 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:

====
----
$ openshift ex bundle-secret dockerhub ~/.dockercfg | oc create -f -
----
====

This command generates JSON specification of the Secret resource named
'dockerhub'. Then this resource is passed to the standard input of `*oc create*`
command.

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*`:

====
----
"parameters": {
"output": {
"to": {
"name": "private-image"
},
"pushSecret":{
"name":"dockerhub"
}
}
}
----
====

Pull the builder Docker image from a private Docker registry by specifying the
`PullSecret` field, which is part of the build strategy definition:

====
----
{
"strategy": {
"sourceStrategy": {
"from": {
"kind": "DockerImage",
"name": "docker.io/user/private_repository"
},
"pullSecret": {
"name": "dockerhub"
},
},
"type": "Source"
}
}
----
====

[#using-private-repositories-for-builds]
== Using Private Repositories for Builds

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
credentials with the following command:

====

----
$ ssh-keygen -t rsa -C "your_email@example.com"
----
====

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.

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:

====

----
$ base64 -w 0 $HOME/.ssh/id_rsa
6yJodHRwc1ovL2zuZGV4LmRvY21lci5aby92MS8iOnsiYXV0aCI6ImJXWnZhblJwYXpwdVoybGxkR2d4TUE9PSIsImVtYWlsIj8ibWlAbWlmby5zayJ9fQ==
----
====

Copy the value returned from the above command and place it into the
`ssh-privatekey` field in `*_secret.json_*` file:

====

----
{
"apiVersion": "v1beta3",
"kind": "Secret",
"metadata": {
"name": "scmsecret"
},
"data": {
"ssh-privatekey": "6yJodHRwc1ovL2zuZGV4LmRvY21lci5aby92MS8iOnsiYXV0aCI6ImJXWnZhblJwYXpwdVoybGxkR2d4TUE9PSIsImVtYWlsIj8ibWlAbWlmby5zayJ9fQ=="
}
}

----
====

Then, create the `*Secret*` from the *_secret.json_* file using the following
command:

====
----
$ 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*`:

====

----
{
"apiVersion": "v1beta3",
"kind": "BuildConfig",
"metadata": {
"name": "sample-build",
},
"parameters": {
"output": {
"to": {
"name": "sample-image"
}
},
"source": {
"git": {
"uri": "git@repository.com:user/app.git"
},
"sourceSecret": {
"name": "scmsecret"
},
"type": "Git"
},
"strategy": {
"sourceStrategy": {
"from": {
"kind": "ImageStreamTag",
"name": "python-33-centos7:latest"
}
},
"type": "Source"
}
}
----
====

[NOTE]
====
The URL of private repository is usually in the form `git@example.com:username/repository`
====
2 changes: 1 addition & 1 deletion architecture/core_objects/openshift_model.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ https://docs.docker.com/reference/commandline/cli/#build[Docker build].

*Source-to-Image (STI) Build* [[source-to-image]]

link:builds.html#sti-build[STI builds] are a replacement for the OpenShift
link:builds.html#source-build[STI builds] are a replacement for the OpenShift
v2-like developer experience. The developer specifies the repository where their
project is located and a builder image, which defines the language and framework
used for writing their application. STI then assembles a new image which runs
Expand Down
2 changes: 1 addition & 1 deletion creating_images/sti.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
toc::[]

== Overview
link:../architecture/core_objects/builds.html#sti-build[Source-to-Image (STI)]
link:../architecture/core_objects/builds.html#source-build[Source-to-Image (STI)]
is a framework that makes it easy to write images that take application source
code as an input and produce a new image that runs the assembled application as
output.
Expand Down
Loading