Skip to content

Commit d0870dd

Browse files
kcbimontekcbimonte
committed
docx: container image guides complete
Signed-off-by: Kevin Bimonte <[email protected]>
1 parent 16af877 commit d0870dd

File tree

3 files changed

+184
-3
lines changed

3 files changed

+184
-3
lines changed

‎base.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,6 @@ exclude_docs: |
3636
libs/**/*.md
3737
libs/examples/apps
3838
libs/examples/terraform
39-
libs/examples/Dockerfiles
4039
libs/examples/misc
4140
libs/examples/LICENSE
4241

‎docs/docs/how-to/container-image-guides/build-push.md‎

Lines changed: 144 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,161 @@
22
title: Building and Pushing an Image
33
---
44

5+
In this guide we are going to show how to build and publish container images using
6+
the [oci-build task](https://github.com/concourse/oci-build-task)
7+
and [registry-image resource](https://github.com/concourse/registry-image-resource). This guide assumes you understand
8+
how to build container images with [Dockerfile's](https://docs.docker.com/engine/reference/builder/) and publish
9+
to [Docker Hub](https://hub.docker.com/) or another image registry using the docker cli.
10+
11+
!!! note
12+
13+
This is one way of building and pushing images. There are many other ways to accomplish this same task in Concourse.
14+
15+
First we need a Dockerfile. You can store this in your own repo or reference
16+
the [github.com/concourse/examples](https://github.com/concourse/examples) repo. The rest of this post assumes you use
17+
the examples repo. All files in this blog post can be found in the examples repo.
18+
519
## The Dockerfile
620

21+
The `Dockerfile`:
22+
23+
```dockerfile linenums="1" title="Dockerfile"
24+
--8<-- "libs/examples/Dockerfiles/simple/Dockerfile"
25+
```
26+
27+
The `stanger` text file:
28+
29+
```text linenums="1" title="stranger"
30+
--8<-- "libs/examples/Dockerfiles/simple/stranger"
31+
```
32+
733
## Defining Pipeline Resources
834

35+
Now we can start building out our pipeline. Let's declare our [Resources](../../resources/index.md) first. We will need
36+
one resource to pull in the repo where our Dockerfile is located, and a second resource pointing to where we want to
37+
push the built container image to.
38+
39+
There are some [Variables](../../../examples/pipeline-vars.md#variables) in this file that we will fill out when setting
40+
the pipeline.
41+
42+
```yaml linenums="1" title="build-push.yml"
43+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml::20"
44+
```
45+
946
## Create the Job
1047

48+
Next we will create a [job](../../jobs.md) that will build and push our container image.
49+
50+
To build the job we will need to pull in the repo where the `Dockerfile` is.
51+
52+
[//]: # (@formatter:off)
53+
```yaml linenums="1" title="build-push.yml"
54+
resources: ... # omitting resource section from above
55+
56+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml:22:25"
57+
```
58+
[//]: # (@formatter:on)
59+
1160
## Build the Image
1261

62+
The second step in our job will build the container image.
63+
64+
To build the container image we are going to use the [oci-build-task](https://github.com/concourse/oci-build-task). The
65+
oci-build-task is a container image that is meant to be used in a Concourse [task](../../tasks.md) to build other
66+
container images. Check out the [`README.md`](https://github.com/concourse/oci-build-task/blob/master/README.md) in the
67+
repo for more details on how to configure and use the oci-build-task in more complex build scenarios.
68+
69+
[//]: # (@formatter:off)
70+
```yaml linenums="1" title="build-push.yml"
71+
resources: ... # omitting resource section from above
72+
73+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml:22:35"
74+
```
75+
[//]: # (@formatter:on)
76+
77+
Next we will add [concourse-examples](https://github.com/concourse/examples) as an [
78+
`input`](../../tasks.md#task-config-schema) to the build task to ensure the artifact from the [
79+
`get` step](../../steps/get.md) (where our `Dockerfile` is fetched) is mounted in our `build-image` step.
80+
81+
[//]: # (@formatter:off)
82+
```yaml linenums="1" title="build-push.yml"
83+
resources: ... # omitting resource section from above
84+
85+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml:22:37"
86+
```
87+
[//]: # (@formatter:on)
88+
89+
The oci-build-task [outputs the built container image](https://github.com/concourse/oci-build-task#outputs) in a
90+
directory called `image`. Let's add image as an output of our task so we can publish it in a later step.
91+
92+
[//]: # (@formatter:off)
93+
```yaml linenums="1" title="build-push.yml"
94+
resources: ... # omitting resource section from above
95+
96+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml:22:39"
97+
```
98+
[//]: # (@formatter:on)
99+
13100
## Defining the Build Context
14101

102+
Next we need to tell the `oci-build-task` what
103+
the [build context](https://docs.docker.com/engine/reference/commandline/build/) of our `Dockerfile` is.
104+
The [README](https://github.com/concourse/oci-build-task) goes over a few other methods of creating your build context.
105+
We are going to use the simplest use-case. By specifying `CONTEXT` the `oci-build-task` assumes a `Dockerfile` and its
106+
build context are in the same directory.
107+
108+
[//]: # (@formatter:off)
109+
```yaml linenums="1" title="build-push.yml"
110+
resources: ... # omitting resource section from above
111+
112+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml:22:44"
113+
```
114+
[//]: # (@formatter:on)
115+
15116
## Publish the Container Image
16117

118+
To push the container image add a [`put` step](../../steps/put.md) to our job plan and tell the registry-image resource
119+
where the tarball of the container image is.
120+
121+
The `put` step will push the container image using the information defined previously in the
122+
resource's [source](../../resources/index.md#resource-schema).
123+
124+
[//]: # (@formatter:off)
125+
```yaml linenums="1" title="build-push.yml"
126+
resources: ... # omitting resource section from above
127+
128+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml:22:47"
129+
```
130+
[//]: # (@formatter:on)
131+
17132
## The Entire Pipeline
18133

19-
## Further Readings
134+
Putting all the pieces together, here is our pipeline that builds and pushes a container image.
135+
136+
```yaml linenums="1" title="build-push.yml"
137+
--8<-- "libs/examples/pipelines/build-and-push-simple-image.yml"
138+
```
139+
140+
You can set the pipeline with the following fly command, updating the variable values with real values the pipeline can
141+
use to run.
142+
143+
```shell
144+
fly -t <target> set-pipeline -p build-and-push-image \
145+
-c ./examples/pipelines/build-and-push-simple-image.yml \
146+
--var image-repo-name=<repo-name> \
147+
--var registry-username=<user> \
148+
--var registry-password=<password>
149+
```
150+
151+
## Further Readings
152+
153+
Understanding what the build context is important when building container images. You can
154+
read [Dockerfile Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#understand-build-context)
155+
for more details about build contexts.
156+
157+
The [inputs section](https://github.com/concourse/oci-build-task#inputs) of the oci-build-task's `README` has examples
158+
on how to create a build context with multiple inputs and other complex build scenarios.
159+
160+
Read the `README`'s in the [oci-build-task](https://github.com/concourse/oci-build-task)
161+
and [registry-image resource](https://github.com/concourse/registry-image-resource/) to learn more about their other
162+
configuration options.

‎docs/docs/how-to/container-image-guides/build-use.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,45 @@
22
title: Building an Image and Using it in a Task
33
---
44

5+
This guide will show you how to build and use an image within one [job](../../jobs.md) without pushing the image to an
6+
external image registry like Docker Hub.
7+
58
## Build The Image
69

7-
## Use the Image
10+
To avoid repeating ourselves we're going to use the pipeline made in the other
11+
guide [Building and Pushing an Image](build-push.md). We will start with the pipeline from
12+
the [Defining the Build Context](build-push.md#defining-the-build-context) section.
13+
14+
We will add the `UNPACK_ROOTFS` parameter to the task. This parameter tells
15+
the [oci-build-task](https://github.com/concourse/oci-build-task) to include the image in a special format that
16+
Concourse's container runtime uses.
17+
18+
!!! note
19+
20+
In the future this may not be necessary if Concourse starts using the OCI image format.
21+
22+
```yaml linenums="1" title="build-and-use-image.yml"
23+
--8<-- "libs/examples/pipelines/build-and-use-image.yml::33"
24+
```
25+
26+
The above pipeline will build a container image and also output it in Concourse's rootfs image format.
27+
28+
## Use the Image
29+
30+
Next we want to add a second task to this job which will use the image generated from the first task as its container
31+
image. To use the image from the previous step add the top-level `image` key to the [`task` step](../../steps/task.md).
32+
33+
[//]: # (@formatter:off)
34+
```yaml linenums="1" title="build-push.yml"
35+
resources: ... # omitting resource section from above
36+
37+
--8<-- "libs/examples/pipelines/build-and-use-image.yml:11:"
38+
```
39+
[//]: # (@formatter:on)
40+
41+
You can set the pipeline with the following fly command.
42+
43+
```shell
44+
fly -t <target> set-pipeline -p build-and-use-image \
45+
-c ./build-and-use-image.yml
46+
```

0 commit comments

Comments
 (0)