Skip to content
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.

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

Added file tutorials/01-intro.md #302

Closed
wants to merge 1 commit into from

Conversation

@ipbabble
Copy link
Contributor

commented Oct 29, 2017

Added a basic introduction to buildah tutorial

Topics covered:
buildah from a base
briefly describes containers/storage and containers/image
buildah run
buildah from scratch
installing packages and files to a scratch image
buildah push and running a buildah built container in docker
buildah bud

@ipbabble

This comment has been minimized.

Copy link
Contributor Author

commented Oct 29, 2017

I'm not sure what to do. I noticed that I had placed the DCO in such a place that it got moved to the PR name. I went back and did a git amend on the commit comments and made sure the DCO was in the body of the comment. I did a push force and it still fails on the DCO? Any tips?

@TomSweeneyRedHat

This comment has been minimized.

Copy link
Collaborator

commented Oct 30, 2017

Did you do a 'git commit --amend -s' and then do the git push? As long as your ~/.gitconfig has your name/email values in it, the signature should come for free.

@nalind

This comment has been minimized.

Copy link
Collaborator

commented Oct 30, 2017

The (github: ipbabble) at the end of the Signed-off-by: line prevents it from being recognized by the regular expression used by the DCO check (^Signed-off-by: ([^<]+) <([^<>@]+@[^<>]+)>$).

@ipbabble

This comment has been minimized.

Copy link
Contributor Author

commented Oct 30, 2017

@ipbabble

This comment has been minimized.

Copy link
Contributor Author

commented Oct 30, 2017

@ipbabble ipbabble changed the title Signed-off-by: William Henry <whenry@redhat.com> (github: ipbabble) Added file tutorials/01-intro.md Oct 30, 2017
@ipbabble

This comment has been minimized.

Copy link
Contributor Author

commented Oct 30, 2017

This build seems to be failing for some other reasons. IS the build broken?

@rhatdan

This comment has been minimized.

Copy link
Member

commented Oct 30, 2017

bot retest

@rhatdan

This comment has been minimized.

Copy link
Member

commented Oct 30, 2017

@rh-atomic-bot

This comment has been minimized.

Copy link
Collaborator

commented Oct 30, 2017

⌛️ Testing commit 1ac85ef with merge 686b8e4...

rh-atomic-bot added a commit that referenced this pull request Oct 30, 2017
Signed-off-by: William Henry <whenry@redhat.com>

A basic introduction to buildah tutorial

Topics covered:
buildah from a base
briefly describes containers/storage and containers/image
buildah run
buildah from scratch
installing packages and files to a scratch image
buildah push and running a buildah built container in docker
buildah bud

Signed-off-by: William Henry <whenry@redhat.com>

Closes: #302
Approved by: rhatdan
@TomSweeneyRedHat

This comment has been minimized.

Copy link
Collaborator

commented Oct 30, 2017

This is failing in the rpm-build, looks to be the same issue as we're seeing in the logo PR #299. I don't believe it's an issue with this submit, but something funky in the build space.

#   Running scriptlet: glibc-2.25-10.fc26.x86_64                            93/93BDB1539 Build signature doesn't match environment
# go-compilers-golang-compiler-1-11.fc26.x86_64 was supposed to be installed but is not!
@rh-atomic-bot

This comment has been minimized.

Copy link
Collaborator

commented Oct 30, 2017

💔 Test failed - status-papr

@ipbabble

This comment has been minimized.

Copy link
Contributor Author

commented Oct 30, 2017

@TomSweeneyRedHat Yeah I noticed that and thought it was probably the same as #299. Because when you were telling me to look at 299 I was thinking "but that failed". I see this is failing in the Red Hat CI and not Travis CI. So some sort of access to some build rpms (?)

# Buildah Tutorial 1
## Building OCI container images

The purpose of this tutorial is to demonstrate how buildah can be used to build container images compliant with the [Open Container Initiative](https://www.opencontainers.org/) (OCI) [image specification](https://github.com/opencontainers/image-spec). Images can be built from existing images, from scratch, and using Dockerfiles. OCI images built using the buildah command line tool (CLI) and the underlying OCI based technologies (e.g. [containers/image](https://github.com/containers/image) and [containers/storage](https://github.com/containers/storage)) are portable and can therefore run in a docker environment.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

@nalind, is the last bit of this true? I thought we were still hung up wating for #187 to be fully functional in a docker environment?

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 30, 2017

Author Contributor

@TomSweeneyRedHat I actually demonstrate it. Now if there are other portability/compatibility issues then we can mention them but for now and for this tutorial the Buildah image can be pushed to docker-daemon and I can run it from there.

This comment has been minimized.

Copy link
@nalind

nalind Oct 30, 2017

Collaborator

#187's mainly about adapting to changes in containers/image that modify how it uses containers/storage to better handle reading of images. An effect of those changes is that tools like skopeo can reliably read images from disk, making buildah's "commit" and "push" logic much simpler. But even without that, the images we produce should be usable.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 30, 2017

Author Contributor

And is.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

Hmm, I will have to play with that some more. I thought it was broken the last time I tried and I'd put a blog on hold due to that. Thanks for the 411.

# Buildah Tutorial 1
## Building OCI container images

The purpose of this tutorial is to demonstrate how buildah can be used to build container images compliant with the [Open Container Initiative](https://www.opencontainers.org/) (OCI) [image specification](https://github.com/opencontainers/image-spec). Images can be built from existing images, from scratch, and using Dockerfiles. OCI images built using the buildah command line tool (CLI) and the underlying OCI based technologies (e.g. [containers/image](https://github.com/containers/image) and [containers/storage](https://github.com/containers/storage)) are portable and can therefore run in a docker environment.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

bulidah to Buildah except for command invocations.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

Done throughout.


Of course you can always just run `buildah from fedora` and then list the containers to see the container name. As mentioned previously it will be fedora-working-container in this case.

See the name:

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

Fragment and a bit confusing, at least to me. Perhaps. "To see the name of the container that we stored in the shell variable:"

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

Done compromise:

It is not required to assign a shell variable. Running buildah from fedora is sufficient. It just helps simplify commands later. To see the name of the container that we stored in the shell variable:

echo $container

buildah run $container -- dnf install java

The `--` syntax basically says: no more `buildah run` command options after this point. It is required if the command we specify includes command line options which are not meant for buildah.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

perhaps: " ... after this point. Instead run the commands following the -- in the container's shell itself.". Or something to that effect.

Or perhaps add to the last line ".. meant for Buildah." to ".. meant for Build but rather to be run in the container's shell."

Mainly want to get the notion across as to where those commands are run.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

Done:

The -- syntax basically tells Buildah: there are no more buildah run command options after this point. The options after this point or for inside the containers shell.


One of the advantages of using `buildah` to build OCI compliant container images is that you can easily build a container image from scratch and therefore exclude unnecessary packages from your image. E.g. most final container images for production probably don't need a package manager like `dnf`.

Let's build a container from scratch. The special "image" name scratch tells buildah to create an empty container:

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

IDK if you want to get into nits or not, but the container is not completely empty. It has a practically negligible amount of meta data stored in it so it will have enough smarts to start up. Practically immeasurable.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

I think this is useful. I've made an appropriate change.


scratchmnt=$(buildah mount $newcontainer)

By echoing `$scratchmnt` we can see the path for the overlay image.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

Will the folks you're targeting know what an "overlay image" is? Should you add something like: "...overlay image." to
"...overlay image which links you directly to the containers root file system."

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

or "which gives you a link directly" I think I like that better.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

Done

dnf -y install docker
systemctl start docker

Let's copy that image from where and how containers/storage stores it to where and how the docker daemon stores its images, so that we can run it using docker. We can achieve this using `buildah push`. This copies the image to docker's repository area which is located under `/var/lib/docker`. Docker's repository is managed by the docker daemon. This needs to be explicitly stated by telling buildah to push to the docker repository protocol using `docker-daemon:`.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

I'd suggest droping "where and how" to "where"

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

Do you want to mention that docker needs to be started first? Personally I'm on the fence, but thought I'd throw it by you.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

If nothing else, it might be a good point to point out that docker requires a big-fat-daemon and buildah does not.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

s/where and how/where/ done.
I mentioned and gave the instructions on starting docker above.
I added the daemon comparison:
Notice that Docker requires a daemon process (that's quite big) in order to run any client commands. Buildah has no daemon requirement.


## Using Dockerfiles with buildah

What if you have been using docker for while and have some existing Dockerfiles. Not a problem. `buildah` can build images using a Dockerfile. The `build-using-dockerfile`, or `bud` for short, takes a Dockefile as input and produces an OCI image.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

nit "for while" to "for a whlie"

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

done

# Run the httpd
CMD ["/usr/sbin/httpd", "-DFOREGROUND"]

Now run `buildah bud` with the name of the Dockerfile and the image name (fedora-httpd):

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

You probably know, but you could have dropped the -f Dockerfile and just goine with 'buildah bud -t fedora-httpd .' I think most folks how are familiar with Docker might think they can't still use that syntax with Buildah if you use the below example.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

I did not know. Done.


buildah bud -f Dockerfile -t fedora-httpd

You will see all the steps of the Dockerfile executing. Afterwards `buildah images` will show you the new image. Now we need to create the container and test it with `buildah run` it:

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

suggest: drop the it before the colon.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

done


You will see the standard apache webpage.

Why not try and modify the Dockerfile. Do not install httpd, but instead ADD the runecho.sh file and have it run as the CMD.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

Summation? Might be nice to add some pointers where they can get more info, thank them for their time, hope they'll contribute, etc., etc., etc.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 30, 2017

Author Contributor

Ack. Again I don't think that's needed right away. Can I (or you) add it later as a patch to this file or does it need to be there now? Also that would be important for the public blog - so it needs to be done for that for sure.

Or I can fix it now while the build is still broken and resubmit. But I'll need help on the git process. I'm sure it's more than just a git commit --amend -s ... I.e. come checkout, change and commit on my branch. (?)

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 30, 2017

Collaborator

I'll send my super secret set of git commands to you in email. Hopefully they'll ease the pain.

This comment has been minimized.

Copy link
@ipbabble

ipbabble Oct 31, 2017

Author Contributor

Added a Congratulations section.

This comment has been minimized.

Copy link
@TomSweeneyRedHat
@TomSweeneyRedHat

This comment has been minimized.

Copy link
Collaborator

commented Oct 30, 2017

My comments are all nits. I'm fine with merging as is with the provisio of touchups in a follow on PR. I know @ipbabble has been having fun with git. Build issues are not related to this PR.

@TomSweeneyRedHat

This comment has been minimized.

Copy link
Collaborator

commented Oct 30, 2017

@rh-atomic-bot, retest this please

A basic introduction to buildah tutorial

Topics covered:
buildah from a base
briefly describes containers/storage and containers/image
buildah run
buildah from scratch
installing packages and files to a scratch image
buildah push and running a buildah built container in docker
buildah bud

Signed-off-by: William Henry <whenry@redhat.com>
@ipbabble

This comment has been minimized.

Copy link
Contributor Author

commented Oct 31, 2017

Woohoo! Finally all tests passed.

@rhatdan

This comment has been minimized.

Copy link
Member

commented Oct 31, 2017

LGTM

@rhatdan

This comment has been minimized.

Copy link
Member

commented Oct 31, 2017

@rh-atomic-bot

This comment has been minimized.

Copy link
Collaborator

commented Oct 31, 2017

📌 Commit 69d3e43 has been approved by rhatdan

@rh-atomic-bot

This comment has been minimized.

Copy link
Collaborator

commented Oct 31, 2017

⌛️ Testing commit 69d3e43 with merge 79663fe...

Copy link
Collaborator

left a comment

Looks really good William. Found a few typos and have a question for @rhatdan. I also did the tutorial itself and have a couple of comments based on that.


buildah run $container bash

Notice we get a new shell prompt because we are running a bash shell inside of the container. It should be noted that `buildah run` is not intended for running production containers. It is for helping debug during the build process.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

I'm a little concerned that seeing the "not intended for running production containers" line will turn people off right here. @rhatdan, thoughts on how to talk about that here? Perhaps adding a CRI-O reference somewhere in the introductory section, then add a "that's a job for CRI-O" or some such here?


buildah run $container -- dnf install java

The `--` syntax basically tells Buildah: there are no more `buildah run` command options after this point. The options after this point or for inside the containers shell. It is required if the command we specify includes command line options which are not meant for Buildah.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

"or for inside" to "are for inside"


The `--` syntax basically tells Buildah: there are no more `buildah run` command options after this point. The options after this point or for inside the containers shell. It is required if the command we specify includes command line options which are not meant for Buildah.

Now running `buildah run $container java` will show that Java has been installed. It will return the `Usage`:

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

maybe "return the standard Java Usage output." ?


buildah containers

Its container name is working-container by default. And it's stored in the `$newcontainer` variable. Notice the image name (IMAGE NAME) is "scratch". This just indicates that there is no real image yet. i.e. It is containers/storage but there is no representation in containers/image. So when we run:

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

I'd suggest "default. And" to "default and"


buildah containers

Its container name is working-container by default. And it's stored in the `$newcontainer` variable. Notice the image name (IMAGE NAME) is "scratch". This just indicates that there is no real image yet. i.e. It is containers/storage but there is no representation in containers/image. So when we run:

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

Since you're directing the reader to "Notice the image name" would it make sense to have an example output listed here? I know they're supposed to be following along on their computer and I'm sitting on the fence for the need of the example. So thought I'd throw it past you to mull over.


or, because `buildah bud` defaults to Dockerfile:

buildah bud -t fedora-httpd

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

need a period at the end here. "buildah bud -t fedora-httpd ." FWIW. I usually add a "(Note the period at the end of this buildah bud example). " or some such just to draw attention to it more.


Notice we get a new shell prompt because we are running a bash shell inside of the container. It should be noted that `buildah run` is not intended for running production containers. It is for helping debug during the build process.

Let's try running something else:

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

Unless the person thought to exit out of the container, they'd still be in the container at this point when you try to run java. You might want to make an explicit note to exit the container.


Lets try installing it using:

buildah run $container -- dnf install java

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

do you want to include '-y' in the dnf command here?


buildah images

We don't see the image listed. There is no image. It is an empty container.

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

If you follow the example, there's a 'docker.io/library/fedora:latest' image listed. Perhaps it might be nice to add a step prior showing how to remove image (buildah rmi {image}) and/or change "no image" to something like "no corresponding scratch image".

Let's try it out (showing the prompt in this example to demonstrate the difference):

# buildah run $newcontainer bash
bash-4.4# cd /usr/bin

This comment has been minimized.

Copy link
@TomSweeneyRedHat

TomSweeneyRedHat Oct 31, 2017

Collaborator

suggest adding a 'bash-4.4# ls' line after this one just to show off some more.

@rh-atomic-bot

This comment has been minimized.

Copy link
Collaborator

commented Oct 31, 2017

☀️ Test successful - status-papr
Approved by: rhatdan
Pushing 79663fe to master...

nalind pushed a commit that referenced this pull request Apr 2, 2018
cleanup network stack as well as storage when container shuts down.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.