├── .travis.yml ├── LICENSE ├── MAINTAINERS ├── Makefile ├── README.md ├── building └── building_index.adoc ├── containers.dict ├── creating ├── creating_index.adoc └── help.adoc ├── delivering └── delivering_index.adoc ├── general_guidance └── general_guidance_index.adoc ├── goals └── goals_index.adoc ├── images ├── interconnect_single.png ├── multi_node_single_container.png ├── simple_db.png ├── simple_db_containerized.png └── single_node_mult_containers.png ├── index.adoc ├── maintaining └── maintaining_index.adoc ├── mark_change.py ├── overview └── overview_index.adoc ├── planning ├── openshift_logs.png ├── planning_application_classes.adoc ├── planning_index.adoc ├── planning_scenarios_distributed_db.adoc ├── planning_scenarios_initialization.adoc ├── planning_scenarios_simple_db.adoc └── simple_db.odg ├── preface.adoc ├── scripts ├── COPYING └── layering_size.py ├── terminology └── terminology_index.adoc ├── testing └── testing_index.adoc └── toc.py /.travis.yml: -------------------------------------------------------------------------------- 1 | language: ruby 2 | 3 | sudo: false 4 | 5 | addons: 6 | apt: 7 | packages: 8 | - aspell 9 | - aspell-en 10 | 11 | rvm: 2.0.0 12 | 13 | install: 14 | - gem install asciidoctor 15 | 16 | script: 17 | - make check 18 | - make html 19 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | License 2 | 3 | THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. 4 | 5 | BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS. 6 | 7 | 1. Definitions 8 | 9 | "Collective Work" means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in unmodified form, along with one or more other contributions, constituting separate and independent works in themselves, are assembled into a collective whole. A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License. 10 | "Creative Commons Compatible License" means a license that is listed at https://creativecommons.org/compatiblelicenses that has been approved by Creative Commons as being essentially equivalent to this License, including, at a minimum, because that license: (i) contains terms that have the same purpose, meaning and effect as the License Elements of this License; and, (ii) explicitly permits the relicensing of derivatives of works made available under that license under this License or either a Creative Commons unported license or a Creative Commons jurisdiction license with the same License Elements as this License. 11 | "Derivative Work" means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment, condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes a Collective Work will not be considered a Derivative Work for the purpose of this License. For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered a Derivative Work for the purpose of this License. 12 | "License Elements" means the following high-level license attributes as selected by Licensor and indicated in the title of this License: Attribution, ShareAlike. 13 | "Licensor" means the individual, individuals, entity or entities that offers the Work under the terms of this License. 14 | "Original Author" means the individual, individuals, entity or entities who created the Work. 15 | "Work" means the copyrightable work of authorship offered under the terms of this License. 16 | "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation. 17 | 18 | 2. Fair Use Rights. Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws. 19 | 20 | 3. License Grant. Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below: 21 | 22 | to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works; 23 | to create and reproduce Derivative Works provided that any such Derivative Work, including any translation in any medium, takes reasonable steps to clearly label, demarcate or otherwise identify that changes were made to the original Work. For example, a translation could be marked "The original work was translated from English to Spanish," or a modification could indicate "The original work has been modified."; 24 | to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works; 25 | to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission Derivative Works. 26 | 27 | For the avoidance of doubt, where the Work is a musical composition: 28 | Performance Royalties Under Blanket Licenses. Licensor waives the exclusive right to collect, whether individually or, in the event that Licensor is a member of a performance rights society (e.g. ASCAP, BMI, SESAC), via that society, royalties for the public performance or public digital performance (e.g. webcast) of the Work. 29 | Mechanical Rights and Statutory Royalties. Licensor waives the exclusive right to collect, whether individually or via a music rights agency or designated agent (e.g. Harry Fox Agency), royalties for any phonorecord You create from the Work ("cover version") and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions). 30 | Webcasting Rights and Statutory Royalties. For the avoidance of doubt, where the Work is a sound recording, Licensor waives the exclusive right to collect, whether individually or via a performance-rights society (e.g. SoundExchange), royalties for the public digital performance (e.g. webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions). 31 | 32 | The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. All rights not expressly granted by Licensor are hereby reserved. 33 | 34 | 4. Restrictions. The license granted in Section 3 above is expressly made subject to and limited by the following restrictions: 35 | 36 | You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Work that restrict the terms of this License or the ability of a recipient of the Work to exercise of the rights granted to that recipient under the terms of the License. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. When You distribute, publicly display, publicly perform, or publicly digitally perform the Work, You may not impose any technological measures on the Work that restrict the ability of a recipient of the Work from You to exercise of the rights granted to that recipient under the terms of the License. This Section 4(a) applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License. If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any credit as required by Section 4(c), as requested. If You create a Derivative Work, upon notice from any Licensor You must, to the extent practicable, remove from the Derivative Work any credit as required by Section 4(c), as requested. 37 | You may distribute, publicly display, publicly perform, or publicly digitally perform a Derivative Work only under: (i) the terms of this License; (ii) a later version of this License with the same License Elements as this License; (iii) either the Creative Commons (Unported) license or a Creative Commons jurisdiction license (either this or a later license version) that contains the same License Elements as this License (e.g. Attribution-ShareAlike 3.0 (Unported)); (iv) a Creative Commons Compatible License. If you license the Derivative Work under one of the licenses mentioned in (iv), you must comply with the terms of that license. If you license the Derivative Work under the terms of any of the licenses mentioned in (i), (ii) or (iii) (the "Applicable License"), you must comply with the terms of the Applicable License generally and with the following provisions: (I) You must include a copy of, or the Uniform Resource Identifier for, the Applicable License with every copy or phonorecord of each Derivative Work You distribute, publicly display, publicly perform, or publicly digitally perform; (II) You may not offer or impose any terms on the Derivative Works that restrict the terms of the Applicable License or the ability of a recipient of the Work to exercise the rights granted to that recipient under the terms of the Applicable License; (III) You must keep intact all notices that refer to the Applicable License and to the disclaimer of warranties; and, (IV) when You distribute, publicly display, publicly perform, or publicly digitally perform the Work, You may not impose any technological measures on the Derivative Work that restrict the ability of a recipient of the Derivative Work from You to exercise the rights granted to that recipient under the terms of the Applicable License. This Section 4(b) applies to the Derivative Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Derivative Work itself to be made subject to the terms of the Applicable License. 38 | If You distribute, publicly display, publicly perform, or publicly digitally perform the Work (as defined in Section 1 above) or any Derivative Works (as defined in Section 1 above) or Collective Works (as defined in Section 1 above), You must, unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or (ii) if the Original Author and/or Licensor designate another party or parties (e.g. a sponsor institute, publishing entity, journal) for attribution ("Attribution Parties") in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; the title of the Work if supplied; to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and, consistent with Section 3(b) in the case of a Derivative Work, a credit identifying the use of the Work in the Derivative Work (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). The credit required by this Section 4(c) may be implemented in any reasonable manner; provided, however, that in the case of a Derivative Work or Collective Work, at a minimum such credit will appear, if a credit for all contributing authors of the Derivative Work or Collective Work appears, then as part of these credits and in a manner at least as prominent as the credits for the other contributing authors. For the avoidance of doubt, You may only use the credit required by this Section for the purpose of attribution in the manner set out above and, by exercising Your rights under this License, You may not implicitly or explicitly assert or imply any connection with, sponsorship or endorsement by the Original Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, without the separate, express prior written permission of the Original Author, Licensor and/or Attribution Parties. 39 | 40 | 5. Representations, Warranties and Disclaimer 41 | 42 | UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND ONLY TO THE EXTENT OF ANY RIGHTS HELD IN THE LICENSED WORK BY THE LICENSOR. THE LICENSOR MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MARKETABILITY, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. 43 | 44 | 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 45 | 46 | 7. Termination 47 | 48 | This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Derivative Works or Collective Works from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License. 49 | Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above. 50 | 51 | 8. Miscellaneous 52 | 53 | Each time You distribute or publicly digitally perform the Work (as defined in Section 1 above) or a Collective Work (as defined in Section 1 above), the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License. 54 | Each time You distribute or publicly digitally perform a Derivative Work, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License. 55 | If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. 56 | No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent. 57 | This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You. 58 | 59 | Creative Commons Notice 60 | 61 | Creative Commons is not a party to this License, and makes no warranty whatsoever in connection with the Work. Creative Commons will not be liable to You or any party on any legal theory for any damages whatsoever, including without limitation any general, special, incidental or consequential damages arising in connection to this license. Notwithstanding the foregoing two (2) sentences, if Creative Commons has expressly identified itself as the Licensor hereunder, it shall have all rights and obligations of Licensor. 62 | 63 | Except for the limited purpose of indicating to the public that the Work is licensed under the CCPL, Creative Commons does not authorize the use by either party of the trademark "Creative Commons" or any related trademark or logo of Creative Commons without the prior written consent of Creative Commons. Any permitted use will be in compliance with Creative Commons' then-current trademark usage guidelines, as may be published on its website or otherwise made available upon request from time to time. For the avoidance of doubt, this trademark restriction does not form part of this License. 64 | 65 | Creative Commons may be contacted at https://creativecommons.org/. 66 | 67 | -------------------------------------------------------------------------------- /MAINTAINERS: -------------------------------------------------------------------------------- 1 | Aaron Weitekamp (@aweiteka) 2 | Brent Baude 3 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | ifneq ($(COMMIT_ID),) 2 | DO_COMMIT_ID = '--commit=$(COMMIT_ID)' 3 | endif 4 | 5 | SHELL := /bin/bash 6 | LABS=index.adoc \ 7 | overview/overview_index.adoc \ 8 | terminology/terminology_index.adoc \ 9 | planning/planning_index.adoc \ 10 | creating/creating_index.adoc \ 11 | building/building_index.adoc \ 12 | testing/testing_index.adoc \ 13 | delivering/delivering_index.adoc 14 | 15 | ALL_ADOC_FILES := $(shell find . -type f -name '*.adoc') 16 | 17 | all: $(LABS) labs 18 | 19 | labs: $(LABS) 20 | asciidoctor -a linkcss -a stylesheet=http://www.projectatomic.io/stylesheets/application.css index.adoc 21 | #a2x -fpdf -dbook --fop --no-xmllint -v labs.asciidoc 22 | $(foreach lab,$(LABS), asciidoctor -a linkcss -a stylesheet=http://www.projectatomic.io/stylesheets/application.css $(lab);) 23 | 24 | html: 25 | # asciidoctor can only put a single HTML output 26 | # chunked output is close per upstream 27 | asciidoctor -d book -a linkcss -a stylesheet=http://www.projectatomic.io/stylesheets/application.css index.adoc 28 | 29 | plain-html: 30 | asciidoctor index.adoc 31 | 32 | publish: $(LABS) 33 | git branch -D gh-pages 34 | asciidoctor -a linkcss -a stylesheet=http://www.projectatomic.io/stylesheets/application.css index.adoc 35 | git checkout -b gh-pages 36 | git commit index.html -m "Update" 37 | git push origin gh-pages -f 38 | 39 | pdf: $(LABS) 40 | #a2x -fpdf -dbook --fop --no-xmllint -v index.adoc 41 | asciidoctor -r asciidoctor-pdf -b pdf -o container_best_practices.pdf index.adoc 42 | 43 | epub: $(LABS) $(SLIDES) 44 | a2x -fepub -dbook --no-xmllint -v index.adoc 45 | 46 | check: 47 | # Disabled for now 48 | #@for docsrc in $(ALL_ADOC_FILES); do \ 49 | # echo -n "Processing '$$docsrc' ..."; \ 50 | # cat $$docsrc | aspell -a --lang=en \ 51 | # --dont-backup \ 52 | # --personal=./containers.dict | grep -e '^&'; \ 53 | # [ "$$?" == "0" ] && exit 1 || echo ' no errors.'; \ 54 | #done 55 | echo "Disabled" 56 | 57 | toc: 58 | asciidoctor index.adoc 59 | python toc.py 60 | 61 | clean: 62 | find . -type f -name \*.html -exec rm -f {} \; 63 | find . -type f -name \*.pdf -exec rm -f {} \; 64 | find . -type f -name \*.epub -exec rm -f {} \; 65 | find . -type f -name \*.fo -exec rm -f {} \; 66 | find . -type f -name \*.xml -exec rm -f {} \; 67 | rm -fr output/ 68 | 69 | review: 70 | python mark_change.py ${ALL_ADOC_FILES} ${DO_COMMIT_ID} 71 | cd output && asciidoctor index.adoc 72 | 73 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Container Best Practices Guide 2 | [![Build Status](https://travis-ci.org/projectatomic/container-best-practices.svg?branch=master)](https://travis-ci.org/projectatomic/container-best-practices) [![Docs](https://img.shields.io/badge/docs-asciidoc-blue.svg)](http://docs.projectatomic.io/container-best-practices/) 3 | 4 | A collaborative project to document container-based application architecture, creation and management. The built version of this source can be viewed at http://docs.projectatomic.io/container-best-practices/ 5 | 6 | ## Contributing 7 | 8 | Please refer to the asciidoc user's guide: http://asciidoctor.org/docs/asciidoc-writers-guide/ 9 | 10 | Before submitting a pull request: 11 | 12 | 1. Compile the document, `make html` 13 | 1. run `make check` to spellcheck the documents. Update personal dictionary file `containers.dict` with any non-English words. 14 | 15 | ## Working with files 16 | 17 | ### Compile docs from a container 18 | 19 | Create local `index.html` file 20 | 21 | ``` 22 | sudo docker run --rm -it -v `pwd`:/documents/:Z asciidoctor/docker-asciidoctor make html 23 | ``` 24 | 25 | ### Clean up files 26 | 27 | ``` 28 | make clean 29 | ``` 30 | 31 | This removes all generated files. 32 | 33 | ### Publish 34 | 35 | ``` 36 | make publish 37 | ``` 38 | 39 | Github serves HTML documents from the `gh-pages` branch. This command will push to the branch. 40 | 41 | ### Spell check 42 | 43 | `aspell` is used to spell check the document. This is run in a [Travis job](https://travis-ci.org/projectatomic/container-best-practices) for all pull requests. Any non-English words should be added to `containers.dict` with your commit. Ensure `make check` passes. 44 | -------------------------------------------------------------------------------- /building/building_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[Building]] 3 | == Building Images 4 | :data-uri: 5 | :homepage https://github.com/projectatomic/container-best-practices: 6 | 7 | === Simple Build 8 | 9 | For building docker images, we must first have the docker daemon installed and running: 10 | [source,shell] 11 | ---- 12 | #> dnf install -y docker 13 | #> systemctl start docker 14 | ---- 15 | 16 | Then we can download an image that we'll use as a base of our image. Let's use something we trust, for example Red Hat Enterprise Linux 7: 17 | [source,shell] 18 | ---- 19 | #> docker pull rhel7 20 | ---- 21 | 22 | Then, one way to create an image, is to simply layer your content on top of the running container. Run the container, make your changes and use `docker commit` to "commit" your changes: 23 | 24 | [source,shell] 25 | ---- 26 | #> docker run -ti --name mycont rhel7 bash 27 | [root@a1eefecdacfa /]# echo Hello Dojo > /root/greeting 28 | [root@a1eefecdacfa /]# exit 29 | #> docker commit mycont 30 | 0bdcfc5ba0602197e2ac4609b8101dc8eaa0d8ab114f542ab6b2f15220d0ab22 31 | ---- 32 | 33 | However, this approach is not easily reproducible and is not ideal for more complicated scenarios. To ensure the build can be reproduce, use the Dockerfile instead. 34 | 35 | The following example results in the same output as the example before, except we can repeat it as many times we want and always get the same output. It also helps understanding the Docker itself more as a packaging format, than just a virtualization technology: 36 | 37 | [source,shell] 38 | ---- 39 | #> cat Dockerfile 40 | FROM rhel7 41 | RUN echo Hello Dojo > /root/greeting 42 | 43 | #> docker build . 44 | ---- 45 | 46 | //TBD: === Using a Build Service 47 | //TBD: === Build Strategies in OpenShift 48 | 49 | === Build Environment 50 | A build environment should have the following characteristics 51 | 52 | - is secure by limiting direct access to the build environment 53 | - limits access to configure and trigger builds 54 | - limits access to build sources 55 | - limits access to base images, those images referenced in the `FROM` line of a Dockerfile 56 | - provides access to build logs 57 | - provides some type of a pipeline or workflow, integrating with external services to trigger builds, report results, etc. 58 | - provides a way to test built images 59 | - provides a way to reproduce builds 60 | - provides a secure registry to store builds 61 | - provides a mechanism to promote tested builds 62 | - shares the same kernel as the target production runtime environment 63 | 64 | A build environment that meets these requirements is difficult to create from scratch. An automation engine like Jenkins is essential to managing a complex pipeline. While a virtual machine-based solution could be created, it is recommended that a dedicated, purpose-built platform such as OpenShift be used. 65 | 66 | //TBD: === Triggering Builds 67 | 68 | 69 | 70 | 71 | -------------------------------------------------------------------------------- /containers.dict: -------------------------------------------------------------------------------- 1 | personal_ws-1.1 en 125 2 | runtime 3 | utils 4 | scl 5 | rsyslog 6 | tbd 7 | migrate 8 | golang 9 | epel 10 | optimizations 11 | setopt 12 | sysconfig 13 | SPCs 14 | uninstall 15 | adoc 16 | mongodb 17 | CMD 18 | CLI 19 | version 20 | TCP 21 | strace 22 | install 23 | uptime 24 | linter 25 | push 26 | hg 27 | AWS 28 | openshift 29 | OpenShift 30 | redhat 31 | changelog 32 | multi 33 | io 34 | IP 35 | spc 36 | XYZ 37 | host 38 | tsflags 39 | md 40 | logrotate 41 | toclevels 42 | run 43 | setuptools 44 | natively 45 | scan 46 | localtime 47 | REPO 48 | systemd 49 | verify 50 | dockerfile 51 | og 52 | microservice 53 | toc 54 | metadata 55 | HTTPS 56 | bzr 57 | vcs 58 | sti 59 | middleware 60 | cpuguy 61 | sosreport 62 | chmod 63 | deployable 64 | rwx 65 | info 66 | cvs 67 | mount 68 | top 69 | asciidoc 70 | rhel 71 | images 72 | svn 73 | py 74 | diff 75 | ENV 76 | lifecycle 77 | init 78 | Kubernetes 79 | zdover 80 | BZComponent 81 | dockerfiles 82 | VM 83 | centosplus 84 | catalogize 85 | microservices 86 | Amazon 87 | uri 88 | authoritive 89 | gettext 90 | git 91 | url 92 | Tweedie 93 | filesystem 94 | enablerepo 95 | devel 96 | unmount 97 | rsyslogd 98 | usr 99 | mysql 100 | MySQL 101 | pid 102 | AEP 103 | entrypoint 104 | syslog 105 | bindmount 106 | LABELs 107 | workflows 108 | CentOS 109 | sudo 110 | pki 111 | nss 112 | leveloffset 113 | rpmkeys 114 | nodocs 115 | iproute 116 | OSE 117 | XYZimage 118 | OpenStack 119 | github 120 | GitHub 121 | bugzilla 122 | stop 123 | subcommands 124 | myscript 125 | chown 126 | update 127 | -------------------------------------------------------------------------------- /creating/creating_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[create]] 3 | == Creating Images 4 | :data-uri: 5 | :toc: 6 | :toclevels 4: 7 | :homepage https://github.com/projectatomic/container-best-practices: 8 | 9 | The base unit of creating an image is the Dockerfile itself. This section 10 | focuses on the instructions that make up a Dockerfile. 11 | 12 | This chapter will not cover every Dockerfile instruction available but instead 13 | will focus on specific ones that we want to re-enforce to those who develop 14 | Dockerfiles. Docker has published a 15 | link:https://docs.docker.com/engine/reference/builder/[reference guide] already 16 | covering each of the Dockerfile instructions. In addition, upstream docker has a nice description of https://docs.docker.com/engine/articles/dockerfile_best-practices/[best practices] for Dockerfiles. It 17 | describes the various instructions that can be used to compose a Dockerfile and their best usage. Familiarize yourself with these 18 | recommendations. 19 | 20 | === Creating Base Images 21 | 22 | ==== Choosing Base Image 23 | 24 | Images that have no parent are called base images. Docker images usually have their own root filesystem with an operating system installed. So when you want to create a new image, it either has to be based on an image that actually provides an operating system or you will need to create this layer in your image. The only difference to this are super minimal images that instead of an operating system provide only a single binary as described later in the text. 25 | There is a wide variety of base images already available on Docker Hub, so the simplest solution is to use one from there. Here are a few things that should help you determine which base image will fit your needs: 26 | 27 | * Linux distribution - Your personal preference and experience will play an important role in choosing one distribution over another. However, you should consider whether your containerized application requires specific libraries or tools from a specific system. 28 | 29 | * Image size - Base images usually contain a minimal operating system with a set of tools needed for basic operations. To preserve your environment small and efficient, size should also be taken into account when picking the right base image. The size varies; you can take advantage of super small base images, such as 2MB busybox, or use a standard minimal operating system, such as Fedora or CentOS that are up to 200MB in size. 30 | 31 | * Updates - Not all community images are necessarily rebuilt on a regular basis or when security vulnerabilities are addressed. You should therefore consider using base images from "official repositories" on Docker Hub, and confirm their update policy in advance. 32 | 33 | ==== Creating Base Image 34 | 35 | Once you've considered all options and decided to create your own base image, the process will mostly depend on the distribution you chose. Note that the major distributions have their source files available on GitHub so you still might want to consider creating an issue or opening a pull request to suggest a change in the feature set or any adjustment. 36 | https://docs.docker.com/engine/userguide/eng-image/baseimages/[Docker documentation] suggests two approaches to creating a base image: using tar and building an image "FROM scratch". 37 | 38 | ===== Using tar 39 | 40 | Using the tar tool is a simple way how to build a base image. As a prerequisite, you will need to set up a directory structure for chroot with all items that you wish to be part of the base image. There are various tools that might help you with this, for example _debootstrap_ for Debian systems or _supermin_ for RPM-based systems. 41 | 42 | Once you have your chroot directory ready, it is as simple as running: 43 | 44 | ``` 45 | # tar -C -c . | docker import - 46 | ``` 47 | 48 | Note that docker provides a set of scripts for base image creation that take advantage of tar: https://github.com/docker/docker/tree/master/contrib[https://github.com/docker/docker/tree/master/contrib]. Popular distributions then use their own build systems that usually also utilizes tar. For example Fedora's https://fedoraproject.org/wiki/Koji/BuildingImages?rd=Koji/KojiLiveCDHowTo#Building_Disk_Images[koji]. 49 | 50 | ===== FROM scratch 51 | 52 | "scratch" is a special repository in the Docker Hub registry, created using an empty tarball. It is not meant to be pulled or run, and at any such an attempt you will most likely encounter this message: _'scratch' is a reserved name_. 53 | Using scratch is ideal for creating extremely minimal images, for example for containerizing single binaries. An example is available from https://docs.docker.com/engine/userguide/eng-image/baseimages/[Docker documentation]. 54 | scratch is also very handy for creating standard distribution base images. But as with tar, you'll first need to prepare a directory structure for chroot. After that, just add the directory in your Dockerfile as follows: 55 | 56 | ``` 57 | FROM scratch 58 | ADD / 59 | CMD ["/bin/bash"] 60 | ``` 61 | // TBD: === Creating Layered Images 62 | 63 | === Creating System Images 64 | 65 | The need for a container service to be started promptly before the Docker service starts supplies the requirements of a system container. The Open-vm-tools container is a system container utilizing runc as the runtime engine. 66 | 67 | A system container normally starts as a regular Docker container: 68 | [source,shell] 69 | ---- 70 | FROM rhel7:7.4-ondeck 71 | 72 | LABEL summary="The open-vm-tools guest agent" \ 73 | io.k8s.description="The open-vm-tools agent is providing information about the virtual machine and allows to restart / shutdown the machine via VMware products. This image is intended to be used with virtual machines running Red Hat Enterprise Linux Atomic Host." \ 74 | name="rhel/open-vm-tools" \ 75 | version="7.4" \ 76 | com.redhat.component="open-vm-tools-docker" \ 77 | maintainer="davis phillips " 78 | 79 | ENV SYSTEMD_IGNORE_CHROOT=1 80 | 81 | RUN yum-config-manager --enable rhel-7-server-rpms || : 82 | RUN yum -y --setopt=tsflags=nodocs install file open-vm-tools perl net-tools iproute systemd 83 | RUN yum clean all 84 | 85 | COPY tmpfiles.template service.template config.json.template /exports/ 86 | COPY init.sh /usr/bin/ 87 | 88 | LABEL run="docker run --privileged -v /proc/:/hostproc/ -v /sys/fs/cgroup:/sys/fs/cgroup -v /var/log:/var/log -v /run/systemd:/run/systemd -v /sysroot:/sysroot -v=/var/lib/sss/pipes/:/var/lib/sss/pipes/:rw -v /etc/passwd:/etc/passwd -v /etc/shadow:/etc/shadow -v /tmp:/tmp:rw -v /etc/sysconfig:/etc/sysconfig:rw -v /etc/resolv.conf:/etc/resolv.conf:rw -v /etc/nsswitch.conf:/etc/nsswitch.conf:rw -v /etc/hosts:/etc/hosts:rw -v /etc/hostname:/etc/hostname:rw -v /etc/localtime:/etc/localtime:rw -v /etc/adjtime:/etc/adjtime --env container=docker --net=host --pid=host IMAGE" 89 | 90 | CMD /usr/bin/vmtoolsd 91 | ---- 92 | 93 | Note, the following line: 94 | 95 | [source,shell] 96 | ---- 97 | COPY tmpfiles.template service.template config.json.template /exports/ 98 | ---- 99 | 100 | This line sets up to stage the systems container. The important components for this are service.template and config.json.template. The service.template is the systemd unit template for when the systems container is installed via atomic install. 101 | 102 | [source,shell] 103 | ---- 104 | [Unit] 105 | Description=Service for virtual machines hosted on VMware 106 | Documentation=http://github.com/vmware/open-vm-tools 107 | ConditionVirtualization=vmware 108 | 109 | [Service] 110 | ExecStartPre=/bin/bash -c 'systemctl import-environment' 111 | ExecStartPre=/bin/bash -c 'export -p > /tmp/open-vm-tools-bash-env' 112 | ExecStart=$EXEC_START 113 | ExecStop=$EXEC_STOP 114 | WorkingDirectory=$DESTDIR 115 | 116 | [Install] 117 | WantedBy=multi-user.target 118 | ---- 119 | 120 | The config.json.template is similar to the Docker run label or line. Below shows the environment variables, bind mounts and the command to execute "/usr/bin/init.sh" 121 | 122 | [source,shell] 123 | ---- 124 | { 125 | "ociVersion": "1.0.0", 126 | "platform": { 127 | "os": "linux", 128 | "arch": "amd64" 129 | }, 130 | "process": { 131 | "terminal": false, 132 | "user": {}, 133 | "args": [ 134 | "/usr/bin/init.sh" 135 | ], 136 | "env": [ 137 | "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", 138 | "TERM=xterm", 139 | "NAME=open-vm-tools", 140 | "SYSTEMD_IGNORE_CHROOT=1" 141 | ], 142 | ... 143 | omitted 144 | "mounts": [ 145 | { 146 | "destination": "/run/systemd", 147 | "type": "bind", 148 | "source": "/run/systemd", 149 | "options": [ 150 | "rw", 151 | "rbind", 152 | "rprivate" 153 | ] 154 | }, 155 | ... 156 | omitted 157 | ---- 158 | 159 | Often times, executing a single command via the container is not enough. The above command init.sh stages the container environment and ensures both VGAuthService and vmtoolsd is executed inside the container. 160 | 161 | [source,shell] 162 | ---- 163 | #!/bin/sh 164 | source /tmp/open-vm-tools-bash-env 165 | 166 | COMMAND=/usr/local/bin/vmware-toolbox-cmd 167 | if [ ! -e $COMMAND ] 168 | then 169 | echo 'runc exec -t open-vm-tools vmware-toolbox-cmd "$@"' > /usr/local/bin/vmware-toolbox-cmd 170 | chmod +x /usr/local/bin/vmware-toolbox-cmd 171 | fi 172 | exec /usr/bin/VGAuthService -s & 173 | exec /usr/bin/vmtoolsd 174 | ---- 175 | 176 | Here are the commands to execute via the atomic CLI to install and convert a system container. Provided we have already built the open-vm-tools container from the Dockerfile listed above. 177 | 178 | [source,shell] 179 | ---- 180 | atomic pull --storage=ostree docker:open-vm-tools 181 | atomic install --system open-vm-tools 182 | systemctl start open-vm-tools 183 | ---- 184 | 185 | Similarly, we can pull this container from the Red Hat registry and install it in the same fashion. 186 | [source,shell] 187 | ---- 188 | atomic pull --storage ostree registry.access.redhat.com/rhel7/open-vm-tools 189 | atomic install --system registry.access.redhat.com/rhel7/open-vm-tools 190 | systemctl start open-vm-tools 191 | ---- 192 | 193 | The atomic install command installs the systemd unit file from the container from its /exports/ directory and sets the service to enable. The systemctl command below that starts the service immediately instead of awaiting a reboot. 194 | 195 | More examples of system containers can be found https://github.com/projectatomic/atomic-system-containers[here]. This includes the open-vm-tools example for CentOS. 196 | 197 | // ==== Creating Component or Application Images 198 | 199 | [[creating_concise]] 200 | === Small and Concise Images 201 | 202 | It is preferable to create small and concise images whenever possible. This can 203 | be highly dependent on the application you are containerizing, but there are 204 | techniques to help you accomplish this. The following sections cover these 205 | techniques. 206 | 207 | ==== Chaining Commands 208 | 209 | In general, having fewer layers improves readability. Commands that are chained together become a part of the 210 | same layer. To reduce the number of layers, chain commands together. Find a balance, though, between a large 211 | number of layers (and a great many commands), and a small number of layers (and obscurity caused by brevity). 212 | 213 | A new layer is created for every new instruction defined. This does not necessarily mean that one instruction 214 | should be associated with only one command or definition. 215 | 216 | Ensure transparency and provide a good overview of the content of each layer by grouping related operations 217 | together so that they together constitute a single layer. Consider this snippet: 218 | 219 | ``` 220 | RUN dnf install -y --setopt=tsflags=nodocs \ 221 | httpd vim && \ 222 | systemctl enable httpd && \ 223 | dnf clean all 224 | ``` 225 | 226 | Each command that is related to the installation and configuration of `httpd` is grouped together 227 | as a part of the same layer. This meaningful grouping of operations keeps the number of layers low 228 | while keeping the easy legibility of the layers high. 229 | 230 | However, even this snippet can be improved. 231 | Can you spot which issues does it suffer from? 232 | 233 | - Although most commands will span only one line, the `dnf` command spans two lines, so it is difficult to spot where it starts and where it ends. 234 | + 235 | This can be mitigated by ensuring that every new command begins with `&&` at the beginning. 236 | As of year 2018, the trend of breaking lines before the binary operator is slowly gaining ground, as https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator[PEP8] has recently adopted this policy. 237 | 238 | - The first and last commands of the block are special. 239 | + 240 | If you would like to prepend or append a one-line command to the block, you will have to edit two lines - one that you are adding and the first or last commands. 241 | The first command is on the same line as the `RUN` directive, whereas the last command lacks the trailing backslash. 242 | + 243 | Editing a line with a command that that you don't want to change presents a risk of introducing a bug, and you also obscure the line's history. 244 | This can be mitigated by having both the first and last commands `true` - they don't do anything. 245 | 246 | Therefore, an improved snipped would look like 247 | 248 | .Chained Dockerfile instruction 249 | ``` 250 | RUN true \ 251 | && dnf install -y --setopt=tsflags=nodocs \ 252 | httpd vim \ 253 | && systemctl enable httpd \ 254 | && dnf clean all \ 255 | && true 256 | ``` 257 | 258 | Additional benefits include easy split and merge of multiple `RUN` sections. 259 | If such section installs build dependencies of a package, clones source code, configures it, compiles it and finally installs it, it may be a time-consuming operation. 260 | And if the compilation fails at a late stage due to bad configuration, you may want to quickly iterate between the configuration and compilation phase. 261 | 262 | Therefore, you will want to split the `RUN` section in two - the dependency installation and source clone in one layer, and the rest (starting with configuration) in another layer. 263 | If you adhere to the style proposed here, you will split a section by inserting two lines right before the configuration step. 264 | After you get the configuration right, you remove those lines without any hassle. 265 | 266 | ===== Using Double Ampersands (&&) vs Semi-colons (;) 267 | 268 | In the RUN instruction of Dockerfiles, it is common to string together multiple commands for efficiency. Stringing 269 | commands together in the RUN instructions are typically done with ampersands or semi-colons. However, you should 270 | consider the implications of each and their usage. The following examples illustrate the difference between those two https://unix.stackexchange.com/questions/88850/precedence-of-the-shell-logical-operators[patterns known to shell programmers]. 271 | 272 | .Using semi-colons as instruction conjunctions 273 | ``` 274 | RUN do_1; do_2 275 | ``` 276 | 277 | This sort of conjunction will be evaluated into do_1 and then do_2. However, using the double 278 | ampersands results in a different evaluation. 279 | 280 | .Using double ampersands as conjunctions 281 | ``` 282 | RUN do_1 && do_2 283 | ``` 284 | 285 | The ampersands change the resulting evaluation into do_1 and then do_2 _only if do_1 was successful_. 286 | 287 | The use of the double ampersands as conjunctions is a better practice in Dockerfiles because 288 | it ensures that your instructions are completed or the build will fail. If the build were to continue 289 | and you had not closely monitored the build (or its results), then the image may not be exactly 290 | as you desired. This is particularly true with automated build systems where you will want any 291 | failure to result in the failure of the build itself. 292 | 293 | There are certainly use cases where semi-colons might be preferred and possibly should be used. 294 | Nevertheless, the possible result of an incomplete image should be carefully considered. 295 | 296 | ==== Clearing Packaging Caches and Temporary Package Downloads 297 | 298 | Package managers can typically generate lots of metadata and also store downloaded content into a cache of 299 | sorts. To keep images and layers as small as possible, you should consider clearing out these caches of downloaded 300 | content. Note how the following example ends with _yum -y clean all_ which removes deletable yum content. 301 | 302 | .A singular RUN instruction performing multiple commands 303 | ``` 304 | RUN true \ 305 | && yum install -y epel-release \ 306 | && rpmkeys --import file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7 \ 307 | && yum install -y --setopt=tsflags=nodocs bind-utils gettext iproute\ 308 | v8314 mongodb24-mongodb mongodb24 \ 309 | && yum -y clean all \ 310 | && true 311 | ``` 312 | 313 | There are several package managers beyond yum that should be of note: dnf, rvm, gems, cpan, pip. Most of these 314 | managers have some form of a clean-up command that will handle excess cache created while performing their package management duties. 315 | 316 | Below are examples pictured for dnf and rvm: 317 | 318 | .dnf cleanup example 319 | ``` 320 | RUN true \ 321 | && rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm \ 322 | && dnf -y install nodejs tar sudo git-all memcached postgresql-devel postgresql-server \ 323 | libxml2-devel libxslt-devel patch gcc-c++ openssl-devel gnupg curl which \ 324 | && dnf clean all \ 325 | && true 326 | ``` 327 | 328 | .Ruby (rvm) cleanup example 329 | ``` 330 | RUN true \ 331 | && /usr/bin/curl -sSL https://rvm.io/mpapis.asc | gpg2 --import - \ 332 | && /usr/bin/curl -sSL https://get.rvm.io | rvm_tar_command=tar bash -s stable \ 333 | && source /etc/profile.d/rvm.sh \ 334 | && echo "gem: --no-ri --no-rdoc --no-document" > ~/.gemrc \ 335 | && /bin/bash -l -c "rvm requirements && rvm install ruby 2.2.4 && rvm use 2.2.4 --default \ 336 | && gem install bundler rake \ 337 | && gem install nokogiri --use-system-libraries \ 338 | && rvm cleanup all && yum clean all && rvm disk-usage all" \ 339 | && true 340 | ``` 341 | 342 | In the above example, notice the `yum clean all` command called after rvm; this is because some package managers like rvm rely on others (like yum 343 | in this case) to help perform their duties. Make sure to examine your container's layers sizes to help determine where you can 344 | eliminate excess size and keep its footprint size to a minimum. 345 | 346 | Here is a listing of some package managers and the applicable cleanup commands: 347 | 348 | .Package Managers 349 | [cols="2*", options"header"] 350 | |=== 351 | |Package Manager 352 | |Cleanup Command 353 | 354 | |yum 355 | |yum clean all 356 | 357 | |dnf 358 | |dnf clean all 359 | 360 | |rvm 361 | |rvm cleanup all 362 | 363 | |gem 364 | |gem cleanup 365 | 366 | |cpan 367 | |rm -rf ~/.cpan/{build,sources}/* 368 | 369 | |pip 370 | |rm -rf ~/.cache/pip/* 371 | 372 | |apt-get 373 | |apt-get clean 374 | 375 | |=== 376 | 377 | ===== Clearing Package Cache and Squashing 378 | 379 | If you squash your images after manual building or as part of an automated build process, it is not necessary to clean cache in every single relevant instruction/layer as the intermediate layers affect the previous ones in this case. 380 | 381 | Simple example Dockerfiles below would both produce the same image if they were squashed: 382 | 383 | .Cache cleanup in a separate instruction 384 | ``` 385 | FROM fedora 386 | RUN dnf install -y mariadb 387 | RUN dnf install -y wordpress 388 | RUN dnf clean all 389 | ``` 390 | 391 | .Cache cleanup chained with the install command 392 | ``` 393 | FROM fedora 394 | RUN dnf install -y mariadb wordpress && dnf clean all 395 | 396 | ``` 397 | However, without squashing, the first image would contain additional files and would be bigger than the second one: 398 | 399 | .Size comparison 400 | ``` 401 | # docker images 402 | REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 403 | example separate 54870d73715f 21 seconds ago 537.7 MB 404 | example chained 6a6156547888 About a minute ago 377.9 MB 405 | 406 | ``` 407 | 408 | Therefore, it is a good practice to write Dockerfiles in a way so that others can use it as a valid reference and are always able to reproduce the build. To ensure this, you should **clean cache in every layer** where applicable. In general, you should always aim to create images that are small and concise regardless of whether the final image is squashed or not. 409 | 410 | Read more about suqashing and its repercussions in the link:#squashing[Squashing layers] section. 411 | 412 | ==== Removing Unnecessary Packages 413 | 414 | In some cases, your image can end up with several packages that are not necessary to support the runtime of your 415 | application. A good example is when you actually build your application from source during the build of the image 416 | itself. Typically, when you build an application, you will pull in development (-devel) packages as well as 417 | toolchain-based packages like make and gcc. Once your application is built, you may no longer need these packages 418 | for runtime depending on how your application links to libraries. 419 | 420 | Depending on your application and which packages you added to your image, you might need to iteratively attempt to 421 | remove packages checking to make sure your application still works. One suggestion would be to remove big parts of the 422 | toolchain. And then use your package manager's command to clean up unused packages. In the case of dnf, you can 423 | remove unneeded packages like so: 424 | 425 | .Removing unnecessary packages with dnf 426 | ``` 427 | # dnf autoremove 428 | ``` 429 | 430 | You should run this command in an interactive shell (docker run -it --rm /bin/bash) initially so you can 431 | get a feel for which packages will be removed. One upside to doing so is that you can then test run your application 432 | from the interactive shell to make sure it still works. 433 | 434 | ==== Removing Documentation 435 | Another technique for reducing the image size is by limiting the documentation being installed. If you package manager supports such a thing and you have no expectations for users to use a shell to interact with your image, this might significantly reduce the size of your image. 436 | 437 | Yum has an optional flag to not install documentation. The following example shows how to set the flag. 438 | 439 | ---- 440 | RUN yum install -y mysql --setopt=tsflags=nodocs 441 | ---- 442 | 443 | Note that the `nodocs` flag is used in some base images, for example CentOS and Fedora, and this setting gets 444 | inherited by the child layers. This can cause problems in case you decide to include the documentation in one of your layered images. 445 | 446 | In this case, if you wish to have the documentation installed for **packages from your single layer only**, you have to 447 | empty the **tsflags** option as follows: 448 | 449 | ---- 450 | RUN yum -y install docker --setopt=tsflags='' 451 | ---- 452 | 453 | If you wish to have the documentation installed for **packages from your single layer and the parent layers**, you need 454 | to reinstall the packages with the empty **tsflags** option as follow: 455 | 456 | ---- 457 | RUN yum -y reinstall "*" --setopt-tsflags='' && yum install docker --setopt-tsflags='' 458 | ---- 459 | 460 | In case you need to have documentation included for **every package from every single parent or child layer**, 461 | the */etc/yum.conf* file needs to be edited as follows: 462 | 463 | ---- 464 | RUN [ -e /etc/yum.conf ] && sed -i '/tsflags=nodocs/d' /etc/yum.conf || true 465 | RUN yum -y reinstall "*" 466 | RUN yum -y install 467 | ---- 468 | 469 | [[squashing]] 470 | ==== Squashing Layers 471 | 472 | Each instruction you create in your Dockerfile results in a new image layer being created. Each layer brings additional 473 | data that are not always part of the resulting image. For example, if you add a file in one layer, but remove it in 474 | another layer later, the final image's size will include the added file size in a form of a special "whiteout" file 475 | although you removed it. In addition, every layer contains separate metadata that add up to the overall image size as 476 | well. So what are the benefits of squashing? 477 | 478 | * **Performance** - Since all layers are copy-on-write file systems, it will take longer to build the final container 479 | from many layers. Squashing helps reduce the build time. 480 | 481 | * **Image size** - Similarly, since an image is actually a collection of other images, the final image size is the sum of the sizes of component images. With squashing, you can prevent these unwanted size additions. 482 | 483 | * **Organization** - Squashing also helps you control the structure of an image, reduce the number of layers and organize images logically. 484 | 485 | However, Docker does not yet support squashing natively, so you will have to work around it by using alternative 486 | approaches, some of which are listed below. 487 | 488 | ===== Experimental --squash Flag 489 | As of version 1.13, Docker supports the `--squash` flag that enabled the squashing functionality. This is currently only available in experimental mode. 490 | 491 | ===== docker save 492 | 493 | You can use `docker save` to squash all the layers of your image into a single layer. The _save_ command 494 | was intended for this use, so this happens to be a side effect of the process. This approach, 495 | however, is not very practical for sharing as the user will be able to only download 496 | the whole content and cannot take advantage the caching. Note that the base image layer will be included 497 | as well and might be several hundreds of megabytes in size. 498 | 499 | [[squash_tools]] 500 | ===== Custom Tools 501 | 502 | You will surely find a lot of utilities on the internet that facilitate layer squashing. 503 | We recommend taking advantage of Marek Goldmann's https://github.com/goldmann/docker-squash[docker-squash], which 504 | automates layer squashing, is kept up-to-date and has been tested by the community. 505 | 506 | 507 | ===== Repercussions of Squashing 508 | 509 | * When you squash an image, you will lose the history together with the metadata accompanying the layers. 510 | * Without the metadata, users building an image from a layered image that has been squashed are losing the idea that it happened. 511 | * Similarly, if you decide to include the parent layer from which your image is built into the resulting squashed image, you ultimately prevent others from seeing that this happened. 512 | 513 | Look at the mongodb example: 514 | 515 | ``` 516 | # docker images openshift/mongodb-24-centos7 517 | REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 518 | docker.io/openshift/mongodb-24-centos7 latest d7c0c18b0ae4 16 hours ago 593.3 MB 519 | ``` 520 | 521 | Without squashing, you can see the complete history and how each of the layers occupies space. 522 | 523 | ``` 524 | # docker history docker.io/openshift/mongodb-24-centos7:latest 525 | IMAGE CREATED CREATED BY SIZE COMMENT 526 | d7c0c18b0ae4 About an hour ago /bin/sh -c #(nop) CMD ["run-mongod"] 0 B 527 | 63e2ba112add About an hour ago /bin/sh -c #(nop) ENTRYPOINT &{["container-en 0 B 528 | ca996db9c281 About an hour ago /bin/sh -c #(nop) USER [184] 0 B 529 | 8593b9473058 About an hour ago /bin/sh -c #(nop) VOLUME [/var/lib/mongodb/da 0 B 530 | 5eca88b7872d About an hour ago /bin/sh -c touch /etc/mongod.conf && chown mo 0 B 531 | 9439db8f40ad About an hour ago /bin/sh -c #(nop) ADD dir:f38635e83f0e6943cd3 17.29 kB 532 | 12c60945cbac About an hour ago /bin/sh -c #(nop) ENV BASH_ENV=/usr/share/con 0 B 533 | e6073f9a949f About an hour ago /bin/sh -c #(nop) ENV CONTAINER_SCRIPTS_PATH= 0 B 534 | 619bf2ae5ed8 About an hour ago /bin/sh -c yum install -y centos-release-scl 342.6 MB 535 | ab5deeccfe21 About an hour ago /bin/sh -c #(nop) EXPOSE 27017/tcp 0 B 536 | 584ded9dcbca About an hour ago /bin/sh -c #(nop) LABEL io.k8s.description=Mo 0 B 537 | 17e3bcd28e07 About an hour ago /bin/sh -c #(nop) ENV MONGODB_VERSION=2.6 HOM 0 B 538 | 807a1e9c5a7b 16 hours ago /bin/sh -c #(nop) MAINTAINER SoftwareCollecti 0 B 539 | 28e524afdd05 10 days ago /bin/sh -c #(nop) CMD ["/bin/bash"] 0 B 540 | 044c0f15c4d9 10 days ago /bin/sh -c #(nop) LABEL name=CentOS Base Imag 0 B 541 | 2ebc6e0c744d 10 days ago /bin/sh -c #(nop) ADD file:6dd89087d4d418ca0c 196.7 MB 542 | fa5be2806d4c 7 months ago /bin/sh -c #(nop) MAINTAINER The CentOS Proje 0 B 543 | 544 | ``` 545 | See how the history and size changes after squashing all layers in a single one (using the script link:#squash_tools[above]): 546 | 547 | ``` 548 | # docker history docker.io/openshift/mongodb-24-centos7:squashed 549 | IMAGE CREATED CREATED BY SIZE COMMENT 550 | 90036ed9bd1d 58 minutes ago 522.1 MB 551 | 552 | ``` 553 | 554 | * One of the biggest benefits of using layers is the posibility to reuse them. Images are usually squashed into a single big layer, which does not allow for pushing partial updates in individual layers; instead, the whole image needs to be pushed into the registry upon a change. The same applies to pulling the image from the registry. 555 | * Some users might rely on suqashing when it comes to sensitive data. Be cautios because squashing is not meant to "hide" content. Even though squashing removes intermediate layers from the final image, information about secrets used in those layers will stay in the build cache. 556 | 557 | === Labels 558 | 559 | Labels in Dockerfiles serve as a useful way to organize and document metadata used to describe an image. Some labels are only descriptive 560 | by nature, like _name_ whereas others, like _RUN_ can be used to describe action-oriented metadata. Labels are often leveraged by applications, like 561 | https://github.com/projectatomic/atomic[atomic] or https://github.com/openshift[OpenShift], to help the image run as the author intended. Labels are primarily intended for descriptive purposes and can be viewed manually with the `docker inspect ` command. 562 | 563 | ==== When are Labels Required? 564 | 565 | Labels are never required per se unless your build system or lifecycle management process requires them. 566 | However, the use of labels is highly recommended for a number of reasons: 567 | 568 | * As mentioned above, many container related tools can use the label metadata in meaningful ways often 569 | contributing to a better user experience. 570 | * The label metadata is always visible when inspecting the image. Therein, users can at least see the 571 | metadata even if their tooling does not make specific use of it. For example, the RUN label basically 572 | documents how you, as the author of the Dockerfile, expect this image to be run. 573 | 574 | ==== Descriptive Labels 575 | 576 | The descriptive labels usually are alpha-numeric strings used to describe some aspect of the image itself. Examples, might be 577 | the version and release labels which could theoretically just be integer based. 578 | The following table describes labels that are meant to be purely descriptive in nature. 579 | 580 | .Descriptive labels 581 | [options="header,footer"] 582 | |=============================================== 583 | | Label | Description | Example 584 | | name | Name of the Image | _"rhel7/rsyslog"_ 585 | | version | Version of the image | _"7.2"_ 586 | | release | Release number of the image | _"12"_ 587 | | architecture | Architecture for the image | _"x86_64"_ 588 | | build-date | Date/Time image was built as https://tools.ietf.org/html/rfc3339[RFC 3339] date-time | _"2015-12-03T10:00:44.038585Z"_ 589 | | vendor | Owner of the image | _"Red Hat, Inc."_ 590 | | URL | URL with more information about the image | _TBD_ 591 | | Summary | Brief description of the image | _TBD_ 592 | | Description | Longer description of the image | _TBD_ 593 | | vcs-type | The type of version control used by the container source. Generally one of git, hg, svn, bzr, cvs | _"git"_ 594 | | vcs-url |URL of the version control repository | _TBD_ 595 | | vcs-ref | A 'reference' within the version control repository; e.g. a git commit, or a subversion branch | _"364a...92a"_ 596 | | authoritative-source-url | The authoritative location in which the image is published | _TBD_ 597 | | distribution-scope |Intended scope of distribution for image. Possible values are private, authoritive-source-only, restricted, or public | _private_ 598 | | changelog-url | URL of a page containing release notes for the image| _TBD_ 599 | |=============================================== 600 | 601 | ==== Action-Oriented Labels 602 | [[label_action]] 603 | Most action-oriented labels will be a used in the context of a docker command in order for the container to behave in a desired 604 | way. The following table describes the defined action-oriented labels. 605 | 606 | .Action-oriented labels 607 | [options="header,footer"] 608 | |=============================================== 609 | | Label | Description | Example 610 | | help | Command to run the help command of the image | _tbd_ 611 | | run | Command to run the image | _"docker run -d --privileged --name NAME --net=host --pid=host -v /etc/pki/rsyslog:/etc/pki/rsyslog -v /etc/rsyslog.conf:/etc/rsyslog.conf -v /etc/sysconfig/rsyslog:/etc/sysconfig/rsyslog -v /etc/rsyslog.d:/etc/rsyslog.d -v /var/log:/var/log -v /var/lib/rsyslog:/var/lib/rsyslog -v /run:/run -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -e IMAGE=IMAGE -e NAME=NAME --restart=always IMAGE /bin/rsyslog.sh"_ 612 | | uninstall | Command to uninstall the image | _"docker run --rm --privileged -v /:/host -e HOST=/host -e IMAGE=IMAGE -e NAME=NAME IMAGE /bin/uninstall.sh"_ 613 | | install | Command to install the image | _"docker run --rm --privileged -v /:/host -e HOST=/host -e IMAGE=IMAGE -e NAME=NAME IMAGE /bin/install.sh"_ 614 | | stop | Command to execute before stopping container | _tbd_ 615 | | debug | Command to run the image with debugging turned on | _tbd_ 616 | |=============================================== 617 | 618 | ==== Recommended Labels for your Project 619 | 620 | Labels are critical to properly identifying your image and influencing how it runs. For the purposes of 621 | identification, we recommend that you at least use the following labels: 622 | 623 | * name 624 | * version 625 | * release 626 | * architecture 627 | * vendor 628 | 629 | And for actionable labels, we recommend you use at least the following: 630 | 631 | * RUN 632 | * INSTALL 633 | * UNINSTALL 634 | 635 | These three are the most critical for ensuring that users run the image in the manner you wish. Furthermore, 636 | tools developed to read and act upon this meta data will work correctly. 637 | 638 | In the case that you provide a help file that does not follow the standard of a man page, then the HELP label would also 639 | be prudent. 640 | 641 | ==== Recommended Labels for your OpenShift Project 642 | 643 | Images that are meant to be run in OpenShift are recommended to contain a set of labels as seen in the https://docs.openshift.org/latest/creating_images/metadata.html[OpenShift Origin documentation]. The labels are namespaced in compliance with the https://docs.docker.com/engine/userguide/labels-custom-metadata/[Docker format]; that is _io.openshift_ for OpenShift and _io.k8s_ for Kubernetes. 644 | 645 | See the following example snippet from the https://github.com/openshift/s2i-ruby/blob/master/2.2/Dockerfile[s2i-ruby] image: 646 | 647 | ``` 648 | LABEL io.k8s.description="Platform for building and running Ruby 2.2 applications" \ 649 | io.k8s.display-name="Ruby 2.2" \ 650 | io.openshift.expose-services="8080:http" \ 651 | io.openshift.tags="builder,ruby,ruby22" 652 | 653 | ``` 654 | 655 | For a comprenehsive list of recommended labels you might want to consider for your projects, see the https://github.com/projectatomic/ContainerApplicationGenericLabels[Container Application Generic Labels] git repository. 656 | 657 | === Starting your Application 658 | 659 | Generally the CMD instruction in the Dockerfile is used by docker to start your application 660 | when the image or container is started. In the planning section, we provided some reasoning 661 | for choosing how to *_xref:planning_starting_application[start your application]_*. The following 662 | subsections will show how to implement each choice in your Dockerfile. 663 | 664 | ==== Calling the Binary Directly 665 | Being the simplest of the choices, you simply need to call the binary using the CMD instruction or 666 | define an ENTRYPOINT in your Dockerfile. 667 | 668 | ``` 669 | CMD ["/usr/bin/some_binary"] 670 | ``` 671 | 672 | ===== Using the CMD Instruction 673 | With CMD, you can identify the default command to run from the image, along with options you want to pass to it. 674 | If there is no ENTRYPOINT in the Dockerfile, the value of CMD is the command run by default when you start the 675 | container image. If there is an ENTRYPOINT in the Dockerfile, the ENTRYPOINT value is run as the command instead, 676 | with the value of CMD used as options to the ENTRYPOINT command. 677 | 678 | The CMD instruction can be overridden when you run the image. Any time you add an argument to the end of a docker run command, the CMD instruction inside the container is ignored. For example, when running `docker run -it myimage bash`, whatever command is set in the CMD instruction in your Dockerfile will be overrriden and _bash_ will be run instead. 679 | 680 | ===== Using the ENTRYPOINT Instruction 681 | Like CMD, the ENTRYPOINT instruction lets you define the command executed when you run the container image, but it 682 | cannot be overridden by arguments you put at the end of the `docker run` command. If your Dockerfile includes an 683 | ENTRYPOINT instruction and there is also a CMD instruction, any arguments on the CMD instruction line are passed to 684 | the command defined in the ENTRYPOINT line. 685 | 686 | This is the distinct advantage of the ENTRYPOINT instruction over the CMD instruction because the command being run 687 | is not overridden but it can be subsidized. Suppose you have an ENTRYPOINT instruction that displays two files. 688 | You could easily add an additional file to be displayed by adding it to the docker run command. 689 | 690 | You can override the ENTRYPOINT command by defining a new entrypoint with the `--entrypoint=""` option on the docker 691 | command line. 692 | 693 | [[creating_using_a_script]] 694 | 695 | ==== Using a Script 696 | Using a script to start an application is very similar to calling the binary directly. Again, you 697 | use the CMD instruction but instead of pointing at the binary you point at your script that was 698 | injected into the image. The _registry.access.redhat.com/rhel7/rsyslog_ image uses a script 699 | to start the rsyslogd application. Lets look at the two relevant instructions in its Dockerfile 700 | that make this happen. 701 | 702 | The following instruction injects our script (rsyslog.sh) into the image in the _bin_ dir. 703 | ``` 704 | ADD rsyslog.sh /bin/rsyslog.sh 705 | ``` 706 | 707 | The contents of the script are as follows: 708 | 709 | ``` 710 | #!/bin/sh 711 | # Wrapper to start rsyslog.d with appropriate sysconfig options 712 | 713 | echo $$ > /var/run/syslogd.pid 714 | 715 | source /etc/sysconfig/rsyslog 716 | exec /usr/sbin/rsyslogd -n $SYSLOGD_OPTIONS 717 | ``` 718 | 719 | Notice how the script does in fact handle environment variables by sourcing the _/etc/sysconfig/rsyslog_ 720 | file. And the CMD instruction simply calls the script. 721 | 722 | ``` 723 | CMD [ "/bin/rsyslog.sh" ] 724 | ``` 725 | 726 | ==== Displaying Usage Information 727 | 728 | It might not always be desired to start an application right away. In such a case, we can display usage information with a script instead. 729 | A good example are builder images that are used, as the name suggests, for building applications rather than being run standalone. 730 | Let's take link:https://github.com/openshift/s2i-python[s2i-python] as an example: 731 | 732 | ``` 733 | $ docker run docker.io/centos/python-35-centos7 734 | This is a S2I python-3.5 centos base image: 735 | To use it, install S2I: https://github.com/openshift/source-to-image 736 | 737 | Sample invocation: 738 | 739 | s2i build https://github.com/sclorg/s2i-python-container.git --context-dir=3.5/test/setup-test-app/ centos/python-35-centos7 python-sample-app 740 | 741 | 742 | You can then run the resulting image via: 743 | docker run -p 8080:8080 python-sample-app 744 | ``` 745 | 746 | The s2i-python image leverages the link:https://github.com/openshift/source-to-image[source-to-image] tool to build Python applications from the user's source code. Because the image usage is rather specific and requires user's input, providing the instructions by default is very convenient. 747 | 748 | So, just like the example in the previous section uses a script as _CMD_ input to run the application, the script in this example outputs valuable information about the image usage. 749 | 750 | If you would like to provide more information about your image or don't want to pass the usage information as the default command, consider including a link:#creating_help_file[help file] instead. 751 | 752 | [[creating_using_systemd]] 753 | ==== Using systemd Inside the Container 754 | 755 | Extending our example from link:#creating_using_a_script[starting an application with a script], the rsyslog 756 | image was started with a script. We could easily use systemd to start the application. To use systemd 757 | to start a service that has a unit file, we need to tell systemd to enable the service and then let the 758 | init process handle the rest. So instead of the ADD instruction used earlier, we would use a RUN 759 | instruction to enable the service. 760 | 761 | ``` 762 | RUN systemctl enable rsyslog 763 | ``` 764 | 765 | And then we need to change the CMD instruction to call _/usr/sbin/init_ to let systemd take over. 766 | 767 | ``` 768 | RUN /usr/sbin/init 769 | ``` 770 | 771 | ==== Using Systemd to Control Containers 772 | 773 | The control mechanism for most docker functions is done via the docker commands or something like 774 | the atomic application which simplifies the management of containers and images for users. But in 775 | a non-development environment, you may wish to treat your containers more like traditional services 776 | or applications. For example, you may wish to have your containers start in a specific order on 777 | boot-up. Or perhaps you wish to be able to restart (or recycle) a container because you have changed 778 | its configuration file. 779 | 780 | There are several approaches to these sorts of function. You can make sure a specific container 781 | always starts on boot-up using the `--restart` switch with the docker command line when you initially 782 | run the image. There are also orchestration platforms like Kubernetes that will allow you to determine the 783 | start up order of containers even when they are distributed. But in the case where all the containers 784 | reside on a single node, systemd might just be exactly the solution. Like with traditional services, 785 | systemd is capable of making sure services both start and in the order they are specified. Moreover, 786 | any issues with startup or the container are logged like any other system service. 787 | 788 | When using systemd to manage your containers, you are really using systemd to call docker commands (and 789 | subsequently the docker daemon) to perform the actions. Therefore, once you commit to using systemd 790 | to control a container, you will need to make sure that all start, stop, and restart actions are 791 | conducted with systemd. Failure to do so essentially decouples the docker daemon and systemd causing 792 | systemd to be out of sync. 793 | 794 | In review, systemd is a good solution for: 795 | 796 | * host system services such as agents and long-running services 797 | * logging via journald 798 | * service dependant management 799 | * traditional service management vis _systemctl_ 800 | * multi-container applications with dependencies on the same node 801 | 802 | 803 | The configuration file below is a sample service file that can be used and edited to control your image or 804 | container. In the [Unit] section, you can declare other services needed by your image including the cases where 805 | those services are also images. 806 | 807 | .Sample template for a systemd service file 808 | ``` 809 | [Unit] 810 | After=docker.service 811 | Requires=docker.service 812 | PartOf=docker.service 813 | After=[cite another service] 814 | Wants=[cite another service] 815 | 816 | [Service] 817 | EnvironmentFile=[path to configuration file] 818 | ExecStartPre=-[command to execute prior to starting] 819 | ExecStart=[command to execute for start] 820 | ExecStartPost=/usr/bin/sleep 10 821 | ExecStop=[command to execute for stop] 822 | Restart=always 823 | 824 | [Install] 825 | WantedBy=docker.service 826 | ``` 827 | 828 | In the [Service] section, you can also declare the actual commands that should be run prior to start, in the 829 | case of start, and in the case of stop. These commands can either be straight base commands or docker run (or stop) 830 | commands as well. Finally, if you are using a well made image that contains labels like STOP or RUN, you 831 | could also use the atomic command. For example, a start command could simply be: 832 | 833 | ``` 834 | atomic run 835 | ``` 836 | 837 | This works because the actual docker command to run that image is part of the image's metadata and atomic is 838 | capable of extracting it. 839 | 840 | The [Service] section also has an option for EnvironmentFile. In a traditional, non-containerized systemd service, 841 | this configuration file resides in _/etc/sysconfig/_. In the case of a containerized application, 842 | these configuration files are not always configurable and therefore do not reside on the host's filesystem. And 843 | in the case of where they are configurable, the EnvironmentFile is usually more important to how the service 844 | application is started. If you are link:#planning_use_systemd[starting the application] within an image 845 | with systemd, then systemd will use _/etc/sysconfig/_ within the image itself. 846 | 847 | For more information on writing unit files see link:https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System_Administrators_Guide/sect-Managing_Services_with_systemd-Unit_Files.html[Managing Systemd unit files]. 848 | 849 | // Help section 850 | 851 | [[creating_help_file]] 852 | === Creating a Help File 853 | include::help.adoc[] 854 | 855 | === Templated Dockerfile Creation 856 | 857 | Once you're a familiar with the essentials of Dockerfile creation, you might want to take advantage of existing templates so you don't have to write the files from scratch all over again. The following templates will aid you in the process: 858 | 859 | * link:https://github.com/container-images/container-image-template[Generic image template] 860 | * link:https://github.com/container-images/s2i-container-image-template[Template for creation of s2i builder images]. Read more about source-to-image link:#Builder_images[here]. 861 | 862 | If one of your goals is to have containers built on top of multiple different base images, instead of duplicating work on your Dockerfiles, you can use link:https://github.com/devexp-db/distgen/[Distgen], a tool that allows portable scripting for different Linux distributions. 863 | 864 | === The Dockerfile Linter 865 | 866 | ==== What Is the Linter? 867 | 868 | The Dockerfile-lint is a rule based link:https://en.wikipedia.org/wiki/Lint_(software)['linter'] for verifying Dockerfiles. The rules are used to check file syntax and best practice options for things such as: 869 | 870 | * Was yum clean up evoked after a package installation? 871 | * In the RUN section did the writer link commands via semicolons or double ampersands? 872 | 873 | These are determined by the rules author and are typically defined by best practices and writer requirements. The input rules are defined via a set of link:http://www.yaml.org/[yaml files]. 874 | 875 | At the time of this writing, there are a number of templates from base to automated build configurations. 876 | 877 | ==== Where do I Get the Linter and How do I Install it? 878 | 879 | There are two iterations of the linter. 880 | 881 | * The CLI version of the project is available here: 882 | link:https://github.com/projectatomic/dockerfile_lint[Dockerfile_lint] 883 | * The online version of the project is available here: 884 | link:https://access.redhat.com/labs/linterfordockerfile/#/[Online linter] 885 | 886 | For the next section, we will assume that the CLI version of the linter will be installed manually via link:https://docs.npmjs.com/[npm] using the following commands: 887 | 888 | ``` 889 | git clone https://github.com/projectatomic/dockerfile_lint/ 890 | cd dockerfile_lint 891 | npm install 892 | ``` 893 | ==== Where do I Get the Templates? 894 | 895 | ===== Built-in Templates 896 | In the config directory, there are two base ruleset files. If the dockerfile_lint is executed without -r these are the base rules used. 897 | 898 | * dockerfile_lint/config/default_rules.yaml 899 | 900 | * dockerfile_lint/config/base_rules.yaml 901 | 902 | ===== Additional Types of Templates 903 | 904 | In the sample_rules directory there are some included templates for OpenShift and an example base template. 905 | 906 | * Basic rules - dockerfile_lint/sample_rules/basic_rules.yaml 907 | 908 | This set of rules is a basic catchall of your typical Dockerfile. Things such as yum cache clean up and command execution etiquette are checked. These are the rules we will be referencing below. 909 | 910 | * OpenShift Template - dockerfile_lint/sample_rules/openshift.yaml 911 | 912 | In addition to testing the semantics of the basic template from above, The OpenShift template checks for some link:https://docs.openshift.org/latest/creating_images/metadata.html#defining-image-metadata[required OpenShift labels] specific to its use. 913 | 914 | ==== How do I Read and Customize the Templates? 915 | 916 | The filename of the basic template is included in the command above: sample_rules/basic_rules.yaml 917 | 918 | The rules are implemented using regular expressions matched on instruction of the Dockerfile. The rule file has 3 sections: a *profile* section, a *line rule* section and a *required instructions* section. 919 | 920 | ===== Profile Section 921 | 922 | The profile section gives information about the rule file. This is the name identifier and description for the profile. This information should help users to identify an applicable template. 923 | ``` 924 | profile: 925 | name: "Default" 926 | description: "Default Profile. Checks basic syntax." 927 | includes: 928 | - recommended_label_rules.yaml 929 | ``` 930 | An excerpt from the rules shows how includes are defined: 931 | 932 | ``` 933 | includes: 934 | - recommended_label_rules.yaml 935 | ``` 936 | The include section allows for chaining rulesets of multiple sources. In the above example the recommended_label_rules.yaml is processed in addition to its source. 937 | 938 | ===== Line Rule Section 939 | 940 | This section contains rules match on a given instruction in the Dockerfile. The line rules do the bulk of the dockerfile parsing. 941 | 942 | The example below shows rules to run against the 'FROM' instruction. 943 | ``` 944 | FROM registry.access.redhat.com/rhel7:latest 945 | ``` 946 | 947 | The excerpt below checks for the latest flag in the 'FROM' line. 948 | 949 | ``` 950 | line_rules: 951 | FROM: 952 | paramSyntaxRegex: /^[a-z0-9./-]+(:[a-z0-9.]+)?$/ 953 | rules: 954 | - 955 | label: "is_latest_tag" 956 | regex: /latest/ 957 | level: "error" 958 | message: "base image uses 'latest' tag" 959 | description: "using the 'latest' tag may cause unpredictable builds. It is recommended that a specific tag is used in the FROM line or *-released which is the latest supported release." 960 | reference_url: 961 | - "https://docs.docker.com/reference/builder/" 962 | - "#from" 963 | ``` 964 | Here is another example that parses the 'RUN' line. 965 | ``` 966 | RUN true \ 967 | && yum -y --disablerepo=\* --enablerepo=rhel-7-server-rpms install yum-utils \ 968 | && yum-config-manager --disable \* \ 969 | && yum-config-manager --enable rhel-7-server-rpms \ 970 | && yum clean all \ 971 | && true 972 | 973 | RUN true \ 974 | && yum -y install file open-vm-tools perl open-vm-tools-deploypkg net-tools \ 975 | && yum clean all \ 976 | && true 977 | ``` 978 | 979 | The regex below checks to see if the yum command has been issued. If it has, check to see if _yum clean all_ has been run as well. 980 | ``` 981 | RUN: 982 | paramSyntaxRegex: /.+/ 983 | rules: 984 | - 985 | label: "no_yum_clean_all" #This is a short description of the rule 986 | regex: /yum(?!.+clean all|.+\.repo)/g #regex the linter is attempting to match 987 | level: "warn" # warn, error or info: These results will define how the linter exits 988 | message: "yum clean all is not used" 989 | description: "the yum cache will remain in this layer making the layer unnecessarily large" 990 | reference_url: 991 | - "http://docs.projectatomic.io/container-best-practices/#" 992 | - "_clear_packaging_caches_and_temporary_package_downloads" 993 | # Lastly, any best practice documentation that may be pertinent to the rule 994 | ``` 995 | ===== Required Instructions Section 996 | 997 | While the line rules section uses regex, the required instructions looks for the instantiation of the instruction. 998 | 999 | ``` 1000 | required_instructions: 1001 | - 1002 | instruction: "EXPOSE" 1003 | count: 1 1004 | level: "info" 1005 | message: "There is no 'EXPOSE' instruction" 1006 | description: "Without exposed ports how will the service of the container be accessed?" 1007 | reference_url: 1008 | - "https://docs.docker.com/reference/builder/" 1009 | - "#expose" 1010 | ``` 1011 | 1012 | ==== How do I use the Linter? 1013 | 1014 | Execution of the CLI version of the linter may look like this: 1015 | 1016 | ``` 1017 | dockerfile_lint -f /path/to/dockerfile -r sample_rules/basic_rules.yaml 1018 | ``` 1019 | 1020 | Here is some sample output from the command above: 1021 | 1022 | ``` 1023 | --------ERRORS--------- 1024 | 1025 | ERROR: Maintainer is not defined. The MAINTAINER line is useful for identifying the author in the form of MAINTAINER Joe Smith . 1026 | Reference -> https://docs.docker.com/reference/builder/#maintainer 1027 | 1028 | --------INFO--------- 1029 | 1030 | INFO: There is no 'ENTRYPOINT' instruction. None. 1031 | Reference -> https://docs.docker.com/reference/builder/#entrypoint 1032 | 1033 | ``` 1034 | By default, the linter runs in strict mode (errors and/or warnings result in non-zero return code). Run the command with '-p' or '--permissive to run in permissive mode: 1035 | ``` 1036 | dockerfile_lint -p -f /path/to/dockerfile 1037 | ``` 1038 | This allows for quick and automated testing as what is informational and what needs to be addressed immediately. 1039 | -------------------------------------------------------------------------------- /creating/help.adoc: -------------------------------------------------------------------------------- 1 | You can provide a man-like help file with your images that allows for users to have a deeper understanding of your 2 | image. This function now allows you to provide a: 3 | 4 | - more verbose description of the what the image is and does 5 | - understanding of how the image should be run 6 | - description of the security implications inherent in running the image 7 | - requirement if the image needs to be installed 8 | 9 | You can use the atomic application to display this help file trivially like so: 10 | [source, none] 11 | ---- 12 | # atomic help 13 | ---- 14 | 15 | ==== Location 16 | For the `atomic` tool to be able to parse your help file, it must be located in the image as `/help.1` and in the 'man' format. 17 | 18 | ==== Required headings 19 | 20 | The following headings are strongly encouraged in the help file for an image. 21 | 22 | ===== NAME 23 | Image name with short description. 24 | 25 | ===== DESCRIPTION 26 | Describe in greater detail the role or purpose of the image (application, service, base image, builder image, etc.). 27 | 28 | ===== USAGE 29 | Describe how to run the image as a container and what factors might influence the behavior of the image itself. Provide specific command lines that are appropriate for how the container should be run. 30 | 31 | ===== ENVIRONMENT VARIABLES 32 | Explain all environment variables available to run the image in different ways without the need of rebuilding the image. 33 | 34 | ===== HISTORY 35 | Similar to a Changelog of sorts which can be as detailed as the maintainer desires. 36 | 37 | ==== Optional Headings 38 | 39 | Use the following sections in your help file when applicable. 40 | 41 | ===== LABELS 42 | Describe LABEL settings (from the Dockerfile that created the image) that contain pertinent information. 43 | For containers run by atomic, that could include INSTALL, RUN, UNINSTALL, and UPDATE LABELS. 44 | For more information see https://github.com/projectatomic/ContainerApplicationGenericLabels/[Container Application Generic Labels]. 45 | 46 | ===== SECURITY IMPLICATIONS 47 | If your image uses any privileges that you want to make the user aware of, be sure to document which ones are used and optionally 48 | why. 49 | 50 | ==== Sample Template 51 | We recommend writing the help file in the https://help.github.com/articles/markdown-basics/[markdown] language and then 52 | converting it to the man format. This is handy because github can natively display markdown, so the help file can be used 53 | in multiple ways. For a template, see the example help file below and the template markdown file that can also be obtained at https://github.com/container-images/container-image-template/blob/master/help/help.md[here]. 54 | 55 | .Sample help template in markdown format 56 | [source, markdown] 57 | ---- 58 | % IMAGE_NAME (1) Container Image Pages 59 | % MAINTAINER 60 | % DATE 61 | 62 | # NAME 63 | Image_name - short description 64 | 65 | # DESCRIPTION 66 | Describe how image is used (user app, service, base image, builder image, etc.), the services or features it provides, and environment it is intended to run in (stand-alone docker, atomic super-privileged, oc multi-container app, etc.). 67 | 68 | # USAGE 69 | Describe how to run the image as a container and what factors might influence the behavior of the image itself. Provide specific command lines that are appropriate for how the container should be run. Here is an example for a container image meant to be run by the atomic command: 70 | 71 | To pull the container and set up the host system for use by the XYZ container, run: 72 | 73 | # atomic install XYZimage 74 | 75 | To run the XYZ container (after it is installed), run: 76 | 77 | # atomic run XYZimage 78 | 79 | To remove the XYZ container (not the image) from your system, run: 80 | 81 | # atomic uninstall XYZimage 82 | 83 | Also, describe the default configuration options (when defined): default user, exposed ports, volumes, working directory, default command, etc. 84 | 85 | # ENVIRONMENT VARIABLES 86 | Explain all the environment variables available to run the image in different ways without the need of rebuilding the image. Change variables on the docker command line with -e option. For example: 87 | 88 | MYSQL_PASSWORD=mypass 89 | The password set for the current MySQL user. 90 | 91 | # LABELS 92 | Describe LABEL settings (from the Dockerfile that created the image) that contains pertinent information. 93 | For containers run by atomic, that could include INSTALL, RUN, UNINSTALL, and UPDATE LABELS. 94 | 95 | 96 | # SECURITY IMPLICATIONS 97 | If you expose ports or run with privileges, note those and provide an explanation. For example: 98 | 99 | Root privileges 100 | Container is running as root. Explain why is it necessary. 101 | 102 | -p 3306:3306 103 | Opens container port 3306 and maps it to the same port on the Host. 104 | 105 | --net=host --cap_add=net_admin 106 | Network devices of the host are visible inside the container and can be configured. 107 | 108 | # HISTORY 109 | Similar to a Changelog of sorts which can be as detailed as the maintainer wishes. 110 | 111 | # SEE ALSO 112 | References to documentation or other sources. For example: 113 | 114 | Does Red Hat provide MariaDB technical support on RHEL 7? https://access.redhat.com/solutions/1247193 115 | Install and Deploy a Mariadb Container Image https://access.redhat.com/documentation/en/red-hat-enterprise-linux-atomic-host/7/single/getting-started-guide/#install_and_deploy_a_mariadb_container 116 | ---- 117 | 118 | ==== Example Help File for the rsyslog Container 119 | 120 | [source, markdown] 121 | ---- 122 | % RSYSLOG (1) Container Image Pages 123 | % Stephen Tweedie 124 | % January 27, 2016 125 | 126 | # NAME 127 | rsyslog \- rsyslog container image 128 | 129 | # DESCRIPTION 130 | The rsyslog image provides a containerized packaging of the rsyslogd daemon. The rsyslogd daemon is a 131 | utility that supports system message logging. With the rsyslog container installed and running, you 132 | can configure the rsyslogd service directly on the host computer as you would if the daemon were 133 | not containerized. 134 | 135 | You can find more information on the rsyslog project from the project Web site (http://www.rsyslog.com/doc). 136 | 137 | The rsyslog image is designed to be run by the atomic command with one of these options: 138 | 139 | `install` 140 | 141 | Sets up the container to access directories and files from the host system to use for rsyslogd configuration, 142 | logging, log rotation, and credentials. 143 | 144 | `run` 145 | 146 | Starts the installed container with selected privileges to the host and with logging-related files and 147 | directories bind mounted inside the container. If the container stops, it is set to always restart. 148 | 149 | `uninstall` 150 | 151 | Removes the container from the system. This removes the syslog logrotate file, leave all other files 152 | and directories associated with rsyslogd on the host system. 153 | 154 | Because privileges are opened to the host system, the running rsyslog container can gather log messages 155 | from the host and save them to the filesystem on the host. 156 | 157 | The container itself consists of: 158 | - rhel7/rhel base image 159 | - rsyslog RPM package 160 | 161 | Files added to the container during docker build include: /bin/install.sh, /bin/rsyslog.sh, and /bin/uninstall.sh. 162 | 163 | # USAGE 164 | To use the rsyslog container, you can run the atomic command with install, run, or uninstall options: 165 | 166 | To set up the host system for use by the rsyslog container, run: 167 | 168 | atomic install rhel7/rsyslog 169 | 170 | To run the rsyslog container (after it is installed), run: 171 | 172 | atomic run rhel7/rsyslog 173 | 174 | To remove the rsyslog container (not the image) from your system, run: 175 | 176 | atomic uninstall rhel7/rsyslog 177 | 178 | # LABELS 179 | The rsyslog container includes the following LABEL settings: 180 | 181 | That atomic command runs the docker command set in this label: 182 | 183 | `INSTALL=` 184 | 185 | LABEL INSTALL="docker run --rm --privileged -v /:/host \ 186 | -e HOST=/host -e IMAGE=IMAGE -e NAME=NAME \ 187 | IMAGE /bin/install.sh" 188 | 189 | The contents of the INSTALL label tells an `atomic install rhel7/rsyslog` command to remove the container 190 | after it exits (--rm), run with root privileges open to the host, mount the root directory (/) from the hos on 191 | the /host directory within the container, set the location of the host file system to /host, set the name of 192 | the image and run the install.sh script. 193 | 194 | `RUN=` 195 | 196 | LABEL RUN="docker run -d --privileged --name NAME \ 197 | --net=host --pid=host \ 198 | -v /etc/pki/rsyslog:/etc/pki/rsyslog \ 199 | -v /etc/rsyslog.conf:/etc/rsyslog.conf \ 200 | -v /etc/sysconfig/rsyslog:/etc/sysconfig/rsyslog \ 201 | -v /etc/rsyslog.d:/etc/rsyslog.d \ 202 | -v /var/log:/var/log \ 203 | -v /var/lib/rsyslog:/var/lib/rsyslog \ 204 | -v /run:/run \ 205 | -v /etc/machine-id:/etc/machine-id:ro \ 206 | -v /etc/localtime:/etc/localtime:ro \ 207 | -e IMAGE=IMAGE -e NAME=NAME \ 208 | --restart=always IMAGE /bin/rsyslog.sh" 209 | 210 | The contents of the RUN label tells an `atomic run rhel7/rsyslog` command to open various privileges to the host 211 | (described later), mount a variety of host files and directories into the container, set the name of the container, 212 | set the container to restart automatically if it stops, and run the rsyslog.sh script. 213 | 214 | `UNINSTALL=` 215 | 216 | LABEL UNINSTALL="docker run --rm --privileged -v /:/host \ 217 | -e HOST=/host -e IMAGE=IMAGE -e NAME=NAME \ 218 | IMAGE /bin/uninstall.sh" 219 | 220 | The contents of the UNINSTALL label tells an `atomic uninstall rhel7/rsyslog` command to uninstall the rsyslog 221 | container. Stopping the container in this way removes the container, but not the rsyslog image from your system. 222 | Also, uninstalling leaves all rsyslog configuration files and log files intact on the host (only removing the 223 | syslog logrotate file). 224 | 225 | `BZComponent=` 226 | 227 | The bugzilla component for this container. For example, "BZComponent="rsyslog-docker". 228 | 229 | `Name=` 230 | 231 | The registry location and name of the image. For example, "Name="rhel7/rsyslog": 232 | 233 | `Version=` 234 | 235 | The Red Hat Enterprise Linux version from which the container was built. For example, "Version="7.2". 236 | 237 | `Release=` 238 | 239 | The specific release number of the container Release="12.1.a": 240 | 241 | `Architecture=` 242 | 243 | The machine architecture associated with the Red Hat Enterprise Linux release. For example, "Architecture="x86_64" 244 | 245 | When the atomic command runs the rsyslog container, it reads the command line associated with the selected option 246 | from a LABEL set within the Docker container itself. It then runs that command. The following sections detail 247 | each option and associated LABEL: 248 | 249 | # SECURITY IMPLICATIONS 250 | The rsyslog container is what is referred to as a super-privileged container. It is designed to have almost complete 251 | access to the host system as root user. The following docker command options open selected privileges to the host: 252 | 253 | `-d` 254 | 255 | Runs continuously as a daemon process in the background 256 | 257 | `--privileged` 258 | 259 | Turns off security separation, so a process running as root in the container would have the same access to the 260 | host as it would if it were run directly on the host. 261 | 262 | `--net=host` 263 | 264 | Allows processes run inside the container to directly access host network interfaces 265 | 266 | `--pid=host` 267 | 268 | Allows processes run inside the container to see and work with all processes in the host process table 269 | 270 | `--restart=always` 271 | 272 | If the container should fail or otherwise stop, it would be restarted 273 | 274 | # HISTORY 275 | Similar to a Changelog of sorts which can be as detailed as the maintainer wishes. 276 | 277 | # AUTHORS 278 | Stephen Tweedie 279 | ---- 280 | 281 | ==== Converting Markdown to man Format 282 | There are several methods for converting markdown format to man format. One prevalent method is to use `go-md2man` supplied 283 | by the golang-github-cpuguy83-go-md2man package. To convert from markdown to man using this utility, you do as follows: 284 | 285 | [source, none] 286 | ---- 287 | go-md2man -in path_to_man_file -out output_file 288 | ---- 289 | -------------------------------------------------------------------------------- /delivering/delivering_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[delivering]] 3 | == Delivering Images 4 | :data-uri: 5 | :toc: 6 | :toclevels 4: 7 | :homepage https://github.com/projectatomic/container-best-practices: 8 | 9 | // Labels & https://github.com/projectatomic/ContainerApplicationGenericLabels/blob/master/vendor/redhat/names.md 10 | 11 | === Image Naming 12 | 13 | This section describes the image naming standards for Docker images. 14 | 15 | Docker URLs are similar to GitHub repository names. Their structure is: 16 | 17 | REGISTRY:PORT/USER/REPO:TAG 18 | 19 | The implicit default registry is `docker.io`. This means that relative URLs, such as `redhat/rhel` resolve to `docker.io/redhat/rhel`. The "registry" and "repository" elements must be present in the names of images. "Port", "user", and "tag" are not always required, and are not always present. 20 | 21 | Here is an example showing search results for a query targeting Fedora images: 22 | 23 | $ sudo docker search fedora 24 | INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED 25 | docker.io docker.io/fedora Official Fedora 21 base image and semi-off... 172 [OK] 26 | docker.io docker.io/fedora/apache 30 [OK] 27 | docker.io docker.io/fedora/couchdb 30 [OK] 28 | docker.io docker.io/fedora/mariadb 22 [OK] 29 | docker.io docker.io/fedora/ssh 19 [OK] 30 | 31 | Here we see a search that shows an image name in the REGISTRY/USER/REPO format in the NAME column: 32 | 33 | $ sudo docker search zdover23 34 | INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED 35 | docker.io docker.io/zdover23/fed20publican 0 36 | 37 | For more information on naming recommendations, see https://github.com/projectatomic/ContainerApplicationGenericLabels/blob/master/vendor/redhat/names.md[this document]. 38 | -------------------------------------------------------------------------------- /general_guidance/general_guidance_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[General Guidance]] 3 | == General Guidance 4 | :data-uri: 5 | :homepage https://github.com/projectatomic/container-best-practices: 6 | 7 | === Acceptance Criteria 8 | 9 | TBD 10 | 11 | // Here come the image acceptance criteria 12 | 13 | === Flexible containers 14 | 15 | TBD 16 | 17 | // Consider moving elsewhere. 18 | 19 | === Configuration 20 | 21 | TBD 22 | 23 | // Recommendations for orchestrated and standalone containers. Consider moving elsewhere. 24 | -------------------------------------------------------------------------------- /goals/goals_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[Goals]] 3 | == Goals 4 | :data-uri: 5 | :toc: 6 | :toclevels 4: 7 | :homepage https://github.com/projectatomic/container-best-practices: 8 | 9 | === Provide general guidance on containerizing applications 10 | === Provide a deep-dive into specific challenges related to container technology 11 | === Describe a complete end-to-end journey of a containerized application, including the technology, tools and best practices 12 | -------------------------------------------------------------------------------- /images/interconnect_single.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/projectatomic/container-best-practices/e9bf7589d124ec2efa258bc812f93d8087283d82/images/interconnect_single.png -------------------------------------------------------------------------------- /images/multi_node_single_container.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/projectatomic/container-best-practices/e9bf7589d124ec2efa258bc812f93d8087283d82/images/multi_node_single_container.png -------------------------------------------------------------------------------- /images/simple_db.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/projectatomic/container-best-practices/e9bf7589d124ec2efa258bc812f93d8087283d82/images/simple_db.png -------------------------------------------------------------------------------- /images/simple_db_containerized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/projectatomic/container-best-practices/e9bf7589d124ec2efa258bc812f93d8087283d82/images/simple_db_containerized.png -------------------------------------------------------------------------------- /images/single_node_mult_containers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/projectatomic/container-best-practices/e9bf7589d124ec2efa258bc812f93d8087283d82/images/single_node_mult_containers.png -------------------------------------------------------------------------------- /index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | = Container Best Practices 3 | :description: A guide for creating and managing container-based applications. 4 | //:icons: font 5 | :toc: left 6 | :toclevels: 5 7 | :sectnums: 8 | :homepage https://github.com/projectatomic/container-best-practices: 9 | 10 | // Overview 11 | include::overview/overview_index.adoc[] 12 | 13 | // Terminology 14 | include::terminology/terminology_index.adoc[] 15 | 16 | // Planning 17 | include::planning/planning_index.adoc[] 18 | 19 | // Creating 20 | include::creating/creating_index.adoc[] 21 | 22 | // Building 23 | include::building/building_index.adoc[] 24 | 25 | // Testing 26 | include::testing/testing_index.adoc[] 27 | 28 | // Delivering 29 | include::delivering/delivering_index.adoc[] 30 | 31 | // Maintaining 32 | //include::maintaining/maintaining_index.adoc[] 33 | 34 | 35 | -------------------------------------------------------------------------------- /maintaining/maintaining_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[Maintaining]] 3 | == Maintaining 4 | :data-uri: 5 | :toc: 6 | :toclevels 4: 7 | :homepage https://github.com/projectatomic/container-best-practices: 8 | 9 | === Lifecycle 10 | ==== Techniques for Upgrades 11 | === Garbage Collection 12 | -------------------------------------------------------------------------------- /mark_change.py: -------------------------------------------------------------------------------- 1 | import os 2 | import sys 3 | import subprocess 4 | import argparse 5 | import shutil 6 | 7 | class ChangeReview(object): 8 | def __init__(self, filenames): 9 | self.files = filenames 10 | self.check_file_names() 11 | #self.files = ['planning/planning_index.adoc', 'creating/creating_index.adoc'] 12 | self.projdir = os.getcwd() 13 | self.outdir = os.path.join(self.projdir, 'output') 14 | 15 | def check_file_names(self): 16 | for fname in self.files: 17 | if not (fname.endswith(".adoc") or fname.endswith(".asciidoc")): 18 | sys.exit("{} does not end in .adoc or .asciidoc".format(fname)) 19 | if not os.path.exists(fname): 20 | sys.exit("Unable to find {}".format(fname)) 21 | 22 | def process_file(self): 23 | for fname in self.files: 24 | if self.create_original(fname): 25 | if self.create_patch(fname): 26 | self.patch_file(fname) 27 | 28 | def create_original(self, cfile): 29 | basename = os.path.basename(cfile) 30 | outdir = os.path.join(self.outdir, os.path.dirname(cfile)) 31 | cmd = ['git', 'show', 'HEAD~1:{}'.format(cfile)] 32 | print cmd 33 | result = subprocess.Popen(cmd, stderr=subprocess.PIPE, stdout=subprocess.PIPE) 34 | stdout, stderr = result.communicate() 35 | if not os.path.exists(outdir): 36 | os.makedirs(outdir) 37 | if result.returncode != 0: 38 | foo = subprocess.Popen(['pwd']) 39 | foo.communicate() 40 | shutil.copyfile(os.path.join(self.projdir, cfile), os.path.join(outdir, os.path.basename(cfile))) 41 | return False 42 | output = open(os.path.join(outdir, basename), 'w') 43 | output.write(stdout) 44 | output.close() 45 | return True 46 | 47 | def create_patch(self, cfile): 48 | outdir = os.path.join(self.outdir, os.path.dirname(cfile)) 49 | basename = os.path.basename(cfile) 50 | cmd = ['git', 'diff', 'HEAD~1', cfile] 51 | foo = subprocess.check_output(cmd) 52 | if foo == '': 53 | return False 54 | new_file_lines = [] 55 | for line in foo.splitlines(): 56 | if line.startswith('+') and not line.startswith('++'): 57 | new_file_lines.append(line[:1] + '[aqua-background]##' + line[1:] + "##") 58 | else: 59 | new_file_lines.append(line) 60 | output = open(os.path.join(outdir, basename + '.patch'), 'w') 61 | output.write("\n".join(new_file_lines) + "\n") 62 | output.close() 63 | return True 64 | 65 | def patch_file(self, cfile): 66 | outdir = os.path.join(self.outdir, os.path.dirname(cfile)) 67 | basename = os.path.basename(cfile) 68 | os.chdir(outdir) 69 | print os.curdir 70 | cmd = ['patch', '-p1', basename, basename + '.patch'] 71 | subprocess.check_call(cmd) 72 | 73 | 74 | parser = argparse.ArgumentParser(description='Change markup based on a diff') 75 | parser.add_argument('filenames', nargs='+', help='filenames') 76 | args = parser.parse_args() 77 | 78 | cr = ChangeReview(args.filenames) 79 | cr.process_file() 80 | 81 | -------------------------------------------------------------------------------- /overview/overview_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[Overview]] 3 | == Overview 4 | :data-uri: 5 | :homepage https://github.com/projectatomic/container-best-practices: 6 | 7 | === Abstract 8 | 9 | Container technology is a popular packaging method for developers and system administrators to build, ship and run distributed applications. Production use of image-based container technology requires a disciplined approach to development and writing Dockerfiles and defining containerized applications can become rather complex. Therefore, we're passing on our experience in this document, which aims to provide guidance and recommendations for creation, deployment and usage of containerized applications. 10 | 11 | This guide assumes the reader has at least basic knowledge of the containerization technologies. The document also isn't a reference guide of all the Dockerfile instructions. Should you require this kind of content, the documentation is available on the https://www.docker.com/[Docker website]. 12 | 13 | // consider adding a references section linking important projects 14 | 15 | === Contributing 16 | 17 | This is a continuously evolving work with the source files available on https://github.com/projectatomic/container-best-practices[GitHub]. If you find any inconsistencies, mistakes or typos, please use the https://github.com/projectatomic/container-best-practices/issues[issue tracker] to report them. If you wish to participate, feel free to open a https://github.com/projectatomic/container-best-practices/pulls[pull request]. 18 | -------------------------------------------------------------------------------- /planning/openshift_logs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/projectatomic/container-best-practices/e9bf7589d124ec2efa258bc812f93d8087283d82/planning/openshift_logs.png -------------------------------------------------------------------------------- /planning/planning_application_classes.adoc: -------------------------------------------------------------------------------- 1 | === Application Classes 2 | 3 | We have defined applications into four general categories: 4 | 5 | . System Services 6 | . Client Tools 7 | . Service Components 8 | . Micro-service Applications 9 | 10 | 11 | ==== System Services 12 | 13 | System services are a special kind of application. These are drivers or system agents 14 | that extend the functionality of the host system. They are typically single-container 15 | images. They are typically run using automation during a start-up script like cloud-init or a 16 | configuration management system. System service containers require special runtime configuration to 17 | enable the appropriate level of privilege to modify the host system. They are commonly referred as 18 | Super Privileged Containers (SPCs). They utilize the benefits of container packaging but not separation. 19 | 20 | ==== Client Tools 21 | 22 | Client Tools applications are another special kind of application. These are used by end-users who do 23 | not wish to install a client using traditional packaging such as RPM. Container technology enables an 24 | end-user to add a client to their workstation without modifying the operating system. 25 | 26 | There are an endless number of potential clients for this class of applications. A few examples include 27 | remote clients such as OpenStack or Amazon Web Services (AWS) client tools. An extension of the model is 28 | vagrant-like development environment where a tool set for a given project is packaged. For example, 29 | Red Hat's link:https://access.redhat.com/documentation/en/red-hat-enterprise-linux-atomic-host/version-7/getting-started-with-containers/#using_the_atomic_tools_container_image[rhel-tools image] 30 | is a toolkit for interacting with an immutable Atomic host system. It includes git, strace and sosreport, for example. 31 | 32 | Two important architectural decisions should be considered for client container images. 33 | 34 | . How does the end-user interact with the container? Will they use them like traditional command line 35 | interface (CLI) tools? Or will they enter the container environment as a shell, perform some commands, then exit. 36 | The entrypoint command chosen for the container will determine the default behavior. 37 | . Will end-users will need access to files on the host system? If so, will the default behavior bindmount 38 | the current working directory or a user-specified directory? 39 | 40 | ==== Service Components 41 | 42 | Service components are applications that an application developer integrates with. Databases are common examples. 43 | A database is typically a component of a larger application. 44 | 45 | The challenge of porting service components to container technology is optimizing integration. Will the application 46 | developer be able to configure the service to their needs? Will the application developer have sufficient documentation 47 | to install, configure and secure the service being integrated? 48 | 49 | ==== Microservice Applications 50 | 51 | The microservice architecture is particularly well-suited to container technology. Martin Fowler describes microservice 52 | applications as "suites of independently deployable services."footnote:[Martin Fowler, 53 | http://martinfowler.com/articles/microservices.html] Well-designed microservice applications have a clean separation 54 | of code, configuration and data. 55 | 56 | Planning is especially critical for microservice applications because they are especially challenging to port to 57 | container technology. The planning phase must include experts who understand the application's architecture and 58 | service topology, performance characteristics, configuration and dependencies such as networking and storage. While 59 | many applications can be ported to container technology without modification there are sometimes optimizations that 60 | should be made regarding configuration, storage, installation or service architecture. 61 | 62 | ===== Deconstructing Microservice Applications 63 | 64 | The process of deconstructing applications varies widely depending on the complexity and architecture of the 65 | application. Consider the following steps as a guide to a generalized process. 66 | 67 | . Identify the components that will be broken down into microservices. These typically map to container images. 68 | . Identify how the services will communicate. How are REST or message bus interfaces authenticated? 69 | . Identify how data will be accessed by the services. Which services need read/write access to the storage? 70 | . Create a service topology drawing to represent the components, lines of communication and storage. This will 71 | guide the development work, configuration discussions, debugging and potentially become part of the 72 | end-user documentation. 73 | . Identify how the services will be configured, which services need to share configuration and how these 74 | services might be deployed in a highly available configuration. -------------------------------------------------------------------------------- /planning/planning_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | 3 | [[plan]] 4 | == Application Planning 5 | :data-uri: 6 | :homepage https://github.com/projectatomic/container-best-practices: 7 | 8 | As you begin to contemplate the containerization of your application, there are number of factors that 9 | should be considered prior to authoring a Dockerfile. You will want to plan out everything from 10 | how to start the application, to network considerations, to making sure your image is architected in a way that 11 | can run in multiple environments like Atomic Host or OpenShift. 12 | 13 | The very act of containerizing any application presents a few hurdles that are perhaps considered 14 | defacto in a traditional Linux environment. The following sections highlight these hurdles and 15 | offer solutions which would be typical in a containerized environment. 16 | 17 | //Simple database 18 | include::planning_scenarios_simple_db.adoc[] 19 | 20 | 21 | //Distributed database 22 | include::planning_scenarios_distributed_db.adoc[] 23 | 24 | //Storage initalization 25 | include::planning_scenarios_initialization.adoc[] 26 | 27 | === Security and user requirements 28 | 29 | === Host and image synchronization 30 | 31 | Some applications that run in containers require the host and container to more or less be synchronized on certain 32 | attributes so their behaviors are also similar. One such common attribute can be time. The following sections discuss 33 | best practices to keeping those attributes similar or the same. 34 | 35 | ==== Time 36 | 37 | Consider a case where multiple containers (and the host) are running applications and logging to something like 38 | a log server. The log timestamps and information would almost be entirely useless if each container reported a different 39 | time than the host. 40 | 41 | The best way to synchronize the time between a container and its host is through the use of bind mounts. You simply need 42 | to bind mount the host's _/etc/localtime_ with the container's _/etc/localtime_. We use the `ro` flag to ensure the container 43 | can't modify the host's time zone by default. 44 | 45 | In your Dockerfile, this can be accomplished by adding the following to your RUN label: 46 | 47 | .Synchronizing the timezone of the host to the container. 48 | ``` 49 | -v /etc/localtime:/etc/localtime:ro 50 | ``` 51 | 52 | ==== Machine ID 53 | 54 | The _/etc/machine-id_ file is often used as an identifier for things like applications and logging. Depending on your 55 | application, it might be beneficial to also bind-mount the machine ID of the host into the container. For example, in many cases journald relies on the machine ID for identification. The sosreport application also uses it. To bind-mount the machine ID of the host to the container, specify the following when running your container or add the following line to your atomic `RUN` label so `atomic` can utilize it: 56 | 57 | .Synchronizing the host machine ID with a container 58 | ``` 59 | -v /etc/machine-id:/etc/machine-id:ro 60 | ``` 61 | 62 | // === Considerations for images on Atomic Host and OpenShift 63 | 64 | // TBD: === Where to store related components 65 | 66 | // ==== scripts 67 | 68 | // ==== tar files 69 | 70 | // ==== help files 71 | 72 | // ==== Dockerfiles 73 | 74 | [[planning_starting_application]] 75 | === Starting your applications within a container 76 | At some point in the design of your Dockerfile and image, you will need to determine how to start your 77 | application. There are three prevalent methods for starting applications: 78 | 79 | - Call the application binary directly 80 | - Call a script that results in your binary starting 81 | - Use systemd to start the application 82 | 83 | For the most part, there is no single right answer on which method should be used; however, there are 84 | some softer decision points that might help you decide which would be easiest for you as the 85 | Dockerfile owner. 86 | 87 | ==== Calling the Binary Directly 88 | If your application is not service-oriented, calling the binary directly might be the simplest and most 89 | straight-forward method to start a container. There is no memory overhead and no additional packages 90 | are needed (like systemd and its dependencies). However, it is more difficult to deal with 91 | setting environment variables. 92 | 93 | ==== Using a Script 94 | Using a special script to start your application in a container can be a handy way to deal with slightly 95 | more complex applications. One upside is that it is generally trivial to set environment variables. This 96 | method is also good when you need to call more than a single binary to start the application correctly. 97 | One downside is that you now have to maintain the script and ensure it is always present in the image. 98 | 99 | [[planning_use_systemd]] 100 | ==== Use systemd 101 | Using systemd to start your application is great if your application is service-oriented (like httpd). 102 | It can benefit from leveraging well tested unit files generally delivered with the applications 103 | themselves and therefore can make complex applications that require environment variables easy to work 104 | with. One disadvantage is that systemd will increase the size of your image and there is a small 105 | amount of memory used for systemd itself. 106 | 107 | NOTE: As of docker-1.10, the docker run parameter of _--privileged_ is no longer needed to use systemd 108 | within a container. 109 | 110 | You can implement using link:#creating_using_systemd[systemd fairly simply in your Dockerfile]. 111 | 112 | //TBD: === Techniques for deploying or starting images from a host 113 | // ==== host systemd considerations 114 | // ==== native docker (ah) unit file 115 | // ===== example unit file - atomic create unit file 116 | // ==== openshift driven 117 | 118 | [[planning_network]] 119 | === Network Considerations 120 | 121 | ==== Single Host 122 | 123 | ==== Multi Host 124 | 125 | ==== Networking in OpenShift 126 | 127 | Establishing network connection between containers in OpenShift is different from the standard Docker container linking approach. OpenShift uses a built-in DNS so that services can be reached by the service DNS and service IP address. 128 | In other words, applications running in a container can connect to another container using the service name. For example, if a container running the MySQL database is a **database** service endpoint, **database** will be used as a hostname to connect to it from another container. 129 | In addition to DNS record, you can also use the environment variables with IP address of the service which are provided for every container running in the same project as the service. However, if the IP address (environment variable) changes, you will need to redeploy the container. Using service names is therefore recommended. 130 | 131 | For details, see https://docs.openshift.org/latest/architecture/additional_concepts/networking.html[OpenShift Documentation]. 132 | 133 | //==== AEP / OSE / Docker considerations 134 | 135 | [[planning_storage]] 136 | === Storage Considerations 137 | 138 | When you architect your container image, storage can certainly be a critical consideration. The power of containers is 139 | that they can mimic, replicate, or replace all kinds of applications and therein lies why you must be careful in 140 | considering how you deal with storage needs. 141 | 142 | By nature, the storage for containers is ephemeral. This makes sense because one of the attractions of containers 143 | is that they can be easily created, deleted, replicated, and so on. If no consideration to storage is given, the 144 | container will only have access to its own filesystem. This means if the container is deleted, whatever information, 145 | whether it is logs or data, will be lost. For some applications, this is perfectly acceptable if not preferred. 146 | 147 | However, if your application generates important data that should be retained or perhaps could be shared amongst 148 | multiple containers, you will need to ensure that this storage is set up for the user. 149 | 150 | ==== Persistent Storage for Containers: Data Volumes 151 | 152 | Docker defines link:https://docs.docker.com/engine/admin/volumes/volumes/[persistent storage] in two ways. 153 | 154 | . Data volumes 155 | . Data volume containers 156 | 157 | However at present, the use of data volumes 158 | is emerging to be the preferred storage option for users of Docker. The Docker website defines a data volume as 159 | _"a specially-designated directory within one or more containers that bypasses the Union File System."_ It has the distinct 160 | advantages that they can be shared and reused for one or more containers. Moreover, a data volume will 161 | persist even if the associated container is deleted. 162 | 163 | Data volumes must be explicitly created and preferably should be named to provide it with a meaningful name. You can 164 | manually create a data volume with the `docker volume create` command. 165 | 166 | .Creating a data volume for persistent storage 167 | ``` 168 | $ docker volume create 169 | ``` 170 | 171 | NOTE: You can also specify a driver name with the `-d` option 172 | 173 | ===== Using Data Volumes in a Dockerfile 174 | 175 | For developers whose applications require persistent storage, the trick will be instantiating the data volume 176 | prior to running the image. This, however, can be achieved leveraging the link:#label_action[LABEL metadata] 177 | and applications like atomic. 178 | 179 | We recommend that the data volume be created through the use of the INSTALL label. The INSTALL label 180 | is meant to identify a script that should be run prior to ever running the image. In that install script, adding 181 | something like the following can be used to create the data volume. 182 | 183 | .Creating a data volume in your install script 184 | ``` 185 | chroot /host /usr/bin/docker volume create 186 | ``` 187 | 188 | To then use the data volume, the RUN label would need to use the bind mount feature. Adding the following to your 189 | RUN label would bind mount the data volume by name: 190 | 191 | .Adding a data volume by name into your RUN label 192 | ``` 193 | -v :/ 194 | ``` 195 | 196 | ==== Persistent Storage for Containers: Mounting a Directory from the Host 197 | You can also leverage the host filesystem for persistent storage through the use of bind mounts. The basic idea for this 198 | is to use a directory on the host filesystem that will be bind mounted into the container at runtime. This can be simply 199 | used by adding a bind mount to your RUN label: 200 | 201 | .Bind mounting a directory from the rootfs to a running container 202 | ``` 203 | -v /:/ 204 | ``` 205 | 206 | One downside to this approach is that anyone with privileges to that directory on the host will be able to view and 207 | possibly alter the content. 208 | 209 | ==== OpenShift Persistent Storage 210 | ==== Storage Backends for Persistent Storage 211 | 212 | === Logging 213 | 214 | If your application logs actions, errors, and warnings to some sort of log mechanism, you will want to consider how 215 | to allows users to obtain, review, and possibly retain those logs. The flexibility of a container environment 216 | can however present some challenges when it comes to logging because typically your containers are separated 217 | by namespace and cannot leverage the system logging without some explicit action by the users. There are also 218 | several solutions for logging containers like: 219 | 220 | * using a logging service like rsyslog or fluentd 221 | * setting the docker daemon's log driver 222 | * logging to a file shared with the host (bind mounting) 223 | 224 | As a developer, if your application uses logging of some manner, you should be thinking about how you will 225 | handle your log files. Each of the aforementioned solutions has its pros and cons. 226 | 227 | [[logging_use_service]] 228 | ==== Using a Logging Service 229 | 230 | Most traditional Linux systems use a logging service like link:http://www.rsyslog.com/[rsyslog] to collect and store 231 | its log files. Often the logging service will coordinate logging with journald but nevertheless it too is a service and 232 | will accept log input. 233 | 234 | If your application uses a logger and you want to take advantage of the host's logger, you can bind mount _/dev/log_ 235 | between the host and container as part of the RUN label like so: 236 | 237 | ``` 238 | -v /dev/log:/dev/log 239 | ``` 240 | 241 | Depending on the host distribution, log messages will now be in the host's journald and subsequently in 242 | _/var/log/messages_ assumming the host is using something like rsyslog. 243 | 244 | ==== Setting the Log Driver for docker Daemon 245 | 246 | Docker has the ability to link:https://docs.docker.com/engine/admin/logging/overview/[configure a logging driver]. When 247 | implemented, it will impact all containers on the system. This is only useful when you can ensure that the 248 | host will only be running your application as this might impact other containers. Therefore this method has limited 249 | usefulness unless you can ensure the final runtime environment. 250 | 251 | [[logging_host_shared_storage]] 252 | ==== Using Shared Storage with the Host 253 | 254 | The use of xref:planning_storage[persistent storage] can be another effective way to deal with log files whether 255 | you choose to perform a simple bind mount with the host or data volumes. Like using a logging service, it has the 256 | advantage that the logs can be preserved irregardless of the state of the container. Shared storage also reduces 257 | the potential to chew up filesystem space assigned to the container itself. You can bind mount either a file or 258 | directory between host and container using the `-v` flag in your RUN label. 259 | 260 | ``` 261 | -v : 262 | ``` 263 | 264 | ==== Logging in OpenShift 265 | 266 | OpenShift automatically collects logs of image builds and processes running inside containers. The recommended way to log for containers running in OpenShift is to send the logs to standard output or standard error rather than storing it in a file. This way, OpenShift can catch the logs and output them directly in the console, as seen in the picture below, or on the command line (_oc logs_). 267 | 268 | image::planning/openshift_logs.png[] 269 | 270 | For details on logs aggregation, see the https://docs.openshift.org/latest/install_config/aggregate_logging.html[OpenShift docuemntation]. 271 | 272 | === Security and User Considerations 273 | 274 | ==== Passing Credentials and Secrets 275 | 276 | Storing sensitive data like credentials is a hot topic, especially because Docker does not provide a designated option for storing and passing secret values to containers. 277 | 278 | Currently, a very popular way to pass credentials and secrets in a container is specifying them as **environment variables** at container runtime. You as a consumer of such an image don't expose any of your sensitive data publicly. 279 | 280 | However, this approach also has caveats: 281 | 282 | * If you commit such a container and push your changes to a registry, the final image will contain also all your sensitive data publicly. 283 | 284 | * Processes inside your container and other containers linked to your container might be able to access this information. Similarily, everything you pass as an environment variable is accessible from the host machine using *docker inspect* as seen in the https://hub.docker.com/r/openshift/mysql-56-centos7/[mysql example below]. 285 | 286 | ``` 287 | # docker run -d --name mysql_database -e MYSQL_USER=user -e MYSQL_PASSWORD=password -e MYSQL_DATABASE=db -p 3306:3306 openshift/mysql-56-centos 288 | # docker inspect openshift/mysql-56-centos 289 | 290 | 291 | 292 | "Env": [ 293 | "MYSQL_USER=user", 294 | "MYSQL_PASSWORD=password", 295 | "MYSQL_DATABASE=db", 296 | 297 | 298 | 299 | 300 | ``` 301 | 302 | There are other ways how to store secrets and although using environment variables might lead to leaking private data in certain corner cases, it still belongs to the safest workarounds available. 303 | 304 | There are a couple of things to keep in mind when operating with secrets: 305 | 306 | * For obvious reasons, you should avoid using default passwords - users tend to forget to change the default configuration and in case a known password leaks, it can be easily misused. 307 | 308 | * Although squashing removes intermediate layers from the final image, secrets from those layers will still be present in the build cache. 309 | 310 | ===== Handling Secrets in Kubernetes 311 | 312 | Containers running through Kubernetes can take advantage of the **secret** resource type to store sensitive data such as passwords or tokens. Kubernetes uses tmpfs volumes for storing secrets. To learn how to create and access these, refer to the http://kubernetes.io/docs/user-guide/secrets/[Kubernetes User Guide]. 313 | 314 | 315 | ===== Other Projects Facilitating Secret Management 316 | 317 | **Custodia** 318 | 319 | Custodia is an open-source project that defines an API for storing and sharing secrets such as passwords and certificates in a way that keeps data secure, manageable and audiatable. Custodia uses the HTTP protocol and a RESTful API as an IPC mechanism over a local Unix Socket. Custodia is fully modular and users can control how authentication, authorization and API plugins are combined and exposed. You can learn more details on the project's https://github.com/latchset/custodia[github repository] or https://github.com/latchset/custodia/wiki[wiki page]. 320 | 321 | **Vault** 322 | 323 | Another open-source project that aims to handle secure accessing and storing of secrets is Vault. Detailed information about the tool and use cases can be found on the https://www.vaultproject.io/intro/index.html[Vault project website]. 324 | 325 | //TBD: 326 | ==== User NameSpace Mapping (docker-1.10 feature) 327 | ==== https://www.openshift.com/promotions/docker-security.html 328 | 329 | === Preventing Your Image Users from Filling the Filesystem 330 | 331 | Most default docker deployments only set aside about 20GB of storage for each container. For many applications, that 332 | amount of storage is more than enough. But if your containerized application produces significant log output, 333 | or your deployment scenario restarts containers infrequently, file system space can become a concern. 334 | 335 | 336 | The first step to preventing the container filesystem from filling up is to make sure your images 337 | are link:#creating_concise[small and concise]. This obviously will reduce how much space your 338 | image consumes from the filesystem right away. However, as a developer, the following techniques 339 | can be used by you to manage the container filesystem size. 340 | 341 | 342 | 343 | ==== Ask for a Larger Storage Space on Run 344 | 345 | One solution to dealing with filesystem space could be to increase the amount of storage allocated to the container when 346 | your image is run. This can be achieved with the following switch to `docker run`. 347 | 348 | .Increase the container storage space to 60GB 349 | ``` 350 | --storage-opt size:60 351 | ``` 352 | 353 | If you are using a defined RUN label in your Dockerfile, you could add the switch to that label. However, 354 | abuse of this switch could lead to irking users and you should be prudent in using it. 355 | 356 | ==== Space Considerations for Logging 357 | 358 | Logging can sometimes unknowingly consume disk space, particularily when a service or daemon has 359 | failed. If your application performs logging, or more specifically verbose logging, consider the 360 | following approaches to help keep filesystem usage down: 361 | 362 | * Use logrotate inside the container periodically. 363 | * Mount your logs to a link:#logging_host_shared_storage[shared host filesystem] 364 | * link:#logging_use_service[Use a logging service or the host's journalctl (/dev/log)] 365 | 366 | === Deployment Considerations 367 | 368 | Preparing applications for production distribution and deployment must carefully consider the supported 369 | deployment platforms. Production services require high uptime, injection of private or sensitive data, 370 | storage integration and configuration control. The deployment platform determines methods for load balancing, 371 | scheduling and upgrading. A platform that does not provide these services requires additional work when 372 | developing the container packaging. 373 | 374 | //TBD: flexible contianers 375 | 376 | ==== Platform 377 | ==== Lifecycle 378 | ==== Maintenance 379 | ==== Build infrastructure 380 | -------------------------------------------------------------------------------- /planning/planning_scenarios_distributed_db.adoc: -------------------------------------------------------------------------------- 1 | === Container Interconnection: Database Server with Local and Distributed Clients 2 | 3 | By definition, distributed application components need to communicate with one another. 4 | Container technologies encourage developers to make these interconnection points explicit and 5 | provide a number of mechanisms to coordinate or otherwise enable communication between containers. 6 | 7 | ==== Traditional Database Server/Environment 8 | 9 | Consider the database example in the previous section. Once we have established persistent 10 | storage for the database server, we also need to consider how database clients will connect to it. 11 | In nearly all cases these connections will occur through a socket, over the network or locally 12 | via UNIX domain socket special file. 13 | 14 | // TBD: (Diagram placeholder - Block for running container, inset for listening port on top of container block, distinct block outside of container showing shared/mapped directories for UNIX sockets.) 15 | 16 | Simple non-distributed applications may assume that a database is co-located on the same server 17 | and use an established port number, or UNIX domain socket path, as their default access mechanism. 18 | 19 | True multi-node distributed applications may host the database as a distinct node in which case 20 | communication must occur via the network. Clients that wish to use the database must be made 21 | aware of its location, either via explicit configuration or a service discovery mechanism. 22 | 23 | .Traditional DB environment using both socket and TCP/IP connections 24 | image::images/interconnect_single.png[] 25 | 26 | ==== Container Environment - Docker 27 | 28 | The previous example shows a traditional database where a single node allows both socket 29 | and port (TCP/IP) connections. If we were to "containerize" the database server and 30 | the database client into seperate containers, this would present a slight challenge in 31 | the architecture due to the container namespacing. Consider the following image: 32 | 33 | .Single Node Database with server and client in separate containers 34 | image::images/single_node_mult_containers.png[] 35 | 36 | In this setup, there are actually two clients. One is containerized and the other is executing 37 | from the container host directly. The database is also containerized but isolated by namespacing 38 | as well. The database client executing on the host can still communicate with the containerized 39 | database server via TCP/IP because Docker has an internal network for containers to communication with 40 | each other and the host. Once an interconnection mechanism has been established a container developer must ensure 41 | that service containers are properly configured to allow access to these connections. 42 | 43 | Some container coordination frameworks, such as Kubernetes, attempt to simplify this use case for 44 | containers co-located on a single node by sharing the network port space between node-local containers. 45 | 46 | Further details and examples of networking interconnect options for various container frameworks and 47 | scenarios can be found in the xref:planning_network[network considerations] section of this document. 48 | 49 | For non-network connections between containers on a single node, shared filesystem locations, either for 50 | domain sockets or actual filesystem content, must be set up at the time the containers are launched. 51 | Docker, for example, allows mapping a host directory to a container directory by adding the following 52 | argument to the run command: 53 | 54 | ``` 55 | -v : 56 | ``` 57 | 58 | In our DB server example, assuming the database maintains a listening UNIX domain socket in 59 | `/var/run/postgres` we could launch both our server and client with the following argument included: 60 | 61 | ``` 62 | -v /var/run/postgres:/var/run/postgres 63 | ``` 64 | 65 | This will ensure that both the server and client see the same directory content, exported from the host, 66 | allowing the client to connect using the expected/default location. 67 | 68 | Further details and example can be found in the xref:planning_storage[storage considerations] section of 69 | this document. 70 | 71 | Another iteration on this scenario would be where the database server and clients are on different nodes 72 | and require network access to communicate. In this case, you must ensure that Docker not only exposes a 73 | port for the database container but that a port is also exposed to the network so other clients can 74 | communicate with it. 75 | 76 | .Multiple node deployment where server and client are separated 77 | image::images/multi_node_single_container.png[] 78 | 79 | Notice how in this scenario, the database server is still containerized but the client resides on a different 80 | node. 81 | For network connections, Docker provides a simple directive in the Dockerfile to expose a port from the 82 | running container. For example, to create a Postgres DB server container that listens on the default 83 | Postgres port, you would add the following line: 84 | 85 | ``` 86 | EXPOSE 5432 87 | ``` 88 | 89 | You then also need to ensure that you perform the port mapping when the container runs using either the `-P` or `-p` flags. 90 | -------------------------------------------------------------------------------- /planning/planning_scenarios_initialization.adoc: -------------------------------------------------------------------------------- 1 | === Data Initialization 2 | 3 | A truly stateless application component acquires all configuration information via combination of discovery or injection via a cloud, container or configuration management framework. It assumes that all local storage is ephemeral and that any data that requires persistence beyond a shutdown, reboot or termination must be stored elsewhere. 4 | 5 | In practice, many applications are not truly stateless in the sense defined above. Instead, they require at least some element of persistent state or storage to be made available or "attached" to the component at the time it is launched. Frequently, this storage must be initialized the first time the application is run. 6 | 7 | ==== Examples 8 | 9 | - Creation of schema/tables and initial population of a relational database 10 | - Initialization of configuration data, such as the location of a central server or executive to which the application component should connect. 11 | - Initialization of unique identifying information such as a UUID, key pair or shared secrets 12 | 13 | ==== Key Issues 14 | 15 | - Tracking whether initialization has occurred to ensure it only happens once or, at the very least, only occurs when the user wants it to 16 | 17 | - Selecting persistence between restarts of a component versus persistence beyond termination/removal 18 | 19 | - If data is persistent beyond termination of the component, re-associating the persistent storage with a freshly launched instance of the component (be it a VM or a container) 20 | 21 | - If data is persistent across restarts _and_ updates to an underlying container image, ensuring that the “old” persistent data is still available. Users might expect behavior similar to RPMs in this area. 22 | 23 | ==== General Approaches and Patterns - Containers 24 | 25 | Two common patterns have emerged to address components that require one time data initialization. 26 | 27 | - Automatic Initialization - In this pattern, any component that requires data initialization incorporates a check into initial start up. If the check determines that persistent data is already present, it continues as normal. If persistent data is not present, it performs the required data initialization before moving on to normal start up. 28 | 29 | - Explicit Initialization - In this pattern users must explicitly execute an initialization step prior to running an application component. Details may differ depending on the specific container tool or framework being used. 30 | 31 | ==== Persistent Storage in Docker 32 | 33 | Docker containers provide persistence a few different ways. Changes to the local file system of a running container persist across starts and stops but are lost if the container is ever removed. If a user requires persistence beyond removal, Docker provides the concept of "Volumes" which are available in two flavors. 34 | 35 | - "Data volumes" are directories that exist outside of the container file system and whose contents persist even after a container is terminated. 36 | - "Bind mounts" are host directories that can also be directly mounted into a running container. 37 | 38 | For more details on Docker storage configurations see the xref:planning_storage[storage considerations] section of this guide. 39 | 40 | 41 | ==== Framework Support 42 | 43 | This is an area of active development within the various container management frameworks and there is no silver bullet. 44 | 45 | Generally speaking, if an application component does not provide some mechanism for automatic initialization it falls to the user to identify and perform any expected explicit storage initialization. It is also the user's responsibility to track the resulting persistent storage objects during the removal/termination/restart of a container or an update to the underlying container image. 46 | 47 | ===== Explicit Initialization - Atomic CLI 48 | 49 | The one exception is the Atomic CLI (aka "atomic run") which provides support within its metadata format for encoding any required explicit initialization steps. 50 | 51 | // TBD: (Brief example and then reference to atomic CLI docs.) 52 | -------------------------------------------------------------------------------- /planning/planning_scenarios_simple_db.adoc: -------------------------------------------------------------------------------- 1 | === Persistent Storage: Simple Database Server 2 | 3 | Although transience is the main benefit of containers, being able to preserve data after a container terminates is often an essential requirement for production environments. Below are outlined common complications the user can encounter and possible solutions. 4 | 5 | ==== Traditional database server 6 | 7 | One of the simpler environments in the IT world is a database that serves one or more 8 | client nodes. A corporate directory is an example most of us can identify with. Consider 9 | the figure below. 10 | 11 | .Simple database topology 12 | image::images/simple_db.png[] 13 | 14 | In this scenario, we have a single server running a Linux distribution. The server functions 15 | largely as a database server (perhaps postgres) for other clients that can connect to it on 16 | the network. The database is capable of connecting to the clients on the network using the 17 | standard TCP/IP network stack and typically a combination of TCP socket and port. In the case 18 | of posgres, the default port is 5432. 19 | 20 | More importantly, many database implementations store the database files on reliable, enterprise 21 | storage such as SANs or robust RAID arrays. This is done to obviously protect the database 22 | from data loss. By default, containers have immutable storage; and therefore, if the container 23 | is deleted, your data will be lost. As a developer, you will need to understand and design 24 | your containerization in a way that will allow for data to persist regardless of the state 25 | of the container. 26 | 27 | 28 | ==== Containerized Environment 29 | 30 | In the case of a database server, retaining your data can be critical. The default storage for 31 | containers themselves is not persistent but it can be with a little planning. The most common 32 | way to allow for data persistence is using one of the xref:planning_storage[several methods] 33 | already available to docker or your chosen deployment platform. The following figure is a simplified 34 | containerized topography of the same database from above. 35 | 36 | .Containerized database 37 | image::images/simple_db_containerized.png[] 38 | 39 | Note how the container host, like the traditional Linux deployment, has enterprise storage 40 | associated with it. Through the use of link:https://docs.docker.com/engine/userguide/containers/dockervolumes/[docker volumes], 41 | we can assign storage to containers and those volumes will persist irregardless of the 42 | state of the container. 43 | 44 | For more information about planning for persistent storage, check out the 45 | xref:planning_storage[Storage Options] section. 46 | -------------------------------------------------------------------------------- /planning/simple_db.odg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/projectatomic/container-best-practices/e9bf7589d124ec2efa258bc812f93d8087283d82/planning/simple_db.odg -------------------------------------------------------------------------------- /preface.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[Preface]] 3 | == Preface 4 | 5 | This Document describes a number of good practices regarding the creation 6 | and usage of Container Images. 7 | 8 | It is a continuously evolving work published on github.com. Technically speaking 9 | there will be editions, as git tags, so that referencing a section is simple. 10 | 11 | As of October 2016 we the Authors agreed to revisit major parts of this document. 12 | -------------------------------------------------------------------------------- /scripts/COPYING: -------------------------------------------------------------------------------- 1 | GNU LIBRARY GENERAL PUBLIC LICENSE 2 | Version 2, June 1991 3 | 4 | Copyright (C) 1991 Free Software Foundation, Inc. 5 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 6 | Everyone is permitted to copy and distribute verbatim copies 7 | of this license document, but changing it is not allowed. 8 | 9 | [This is the first released version of the library GPL. It is 10 | numbered 2 because it goes with version 2 of the ordinary GPL.] 11 | 12 | Preamble 13 | 14 | The licenses for most software are designed to take away your 15 | freedom to share and change it. By contrast, the GNU General Public 16 | Licenses are intended to guarantee your freedom to share and change 17 | free software--to make sure the software is free for all its users. 18 | 19 | This license, the Library General Public License, applies to some 20 | specially designated Free Software Foundation software, and to any 21 | other libraries whose authors decide to use it. You can use it for 22 | your libraries, too. 23 | 24 | When we speak of free software, we are referring to freedom, not 25 | price. Our General Public Licenses are designed to make sure that you 26 | have the freedom to distribute copies of free software (and charge for 27 | this service if you wish), that you receive source code or can get it 28 | if you want it, that you can change the software or use pieces of it 29 | in new free programs; and that you know you can do these things. 30 | 31 | To protect your rights, we need to make restrictions that forbid 32 | anyone to deny you these rights or to ask you to surrender the rights. 33 | These restrictions translate to certain responsibilities for you if 34 | you distribute copies of the library, or if you modify it. 35 | 36 | For example, if you distribute copies of the library, whether gratis 37 | or for a fee, you must give the recipients all the rights that we gave 38 | you. You must make sure that they, too, receive or can get the source 39 | code. If you link a program with the library, you must provide 40 | complete object files to the recipients so that they can relink them 41 | with the library, after making changes to the library and recompiling 42 | it. And you must show them these terms so they know their rights. 43 | 44 | Our method of protecting your rights has two steps: (1) copyright 45 | the library, and (2) offer you this license which gives you legal 46 | permission to copy, distribute and/or modify the library. 47 | 48 | Also, for each distributor's protection, we want to make certain 49 | that everyone understands that there is no warranty for this free 50 | library. If the library is modified by someone else and passed on, we 51 | want its recipients to know that what they have is not the original 52 | version, so that any problems introduced by others will not reflect on 53 | the original authors' reputations. 54 | 55 | Finally, any free program is threatened constantly by software 56 | patents. We wish to avoid the danger that companies distributing free 57 | software will individually obtain patent licenses, thus in effect 58 | transforming the program into proprietary software. To prevent this, 59 | we have made it clear that any patent must be licensed for everyone's 60 | free use or not licensed at all. 61 | 62 | Most GNU software, including some libraries, is covered by the ordinary 63 | GNU General Public License, which was designed for utility programs. This 64 | license, the GNU Library General Public License, applies to certain 65 | designated libraries. This license is quite different from the ordinary 66 | one; be sure to read it in full, and don't assume that anything in it is 67 | the same as in the ordinary license. 68 | 69 | The reason we have a separate public license for some libraries is that 70 | they blur the distinction we usually make between modifying or adding to a 71 | program and simply using it. Linking a program with a library, without 72 | changing the library, is in some sense simply using the library, and is 73 | analogous to running a utility program or application program. However, in 74 | a textual and legal sense, the linked executable is a combined work, a 75 | derivative of the original library, and the ordinary General Public License 76 | treats it as such. 77 | 78 | Because of this blurred distinction, using the ordinary General 79 | Public License for libraries did not effectively promote software 80 | sharing, because most developers did not use the libraries. We 81 | concluded that weaker conditions might promote sharing better. 82 | 83 | However, unrestricted linking of non-free programs would deprive the 84 | users of those programs of all benefit from the free status of the 85 | libraries themselves. This Library General Public License is intended to 86 | permit developers of non-free programs to use free libraries, while 87 | preserving your freedom as a user of such programs to change the free 88 | libraries that are incorporated in them. (We have not seen how to achieve 89 | this as regards changes in header files, but we have achieved it as regards 90 | changes in the actual functions of the Library.) The hope is that this 91 | will lead to faster development of free libraries. 92 | 93 | The precise terms and conditions for copying, distribution and 94 | modification follow. Pay close attention to the difference between a 95 | "work based on the library" and a "work that uses the library". The 96 | former contains code derived from the library, while the latter only 97 | works together with the library. 98 | 99 | Note that it is possible for a library to be covered by the ordinary 100 | General Public License rather than by this special one. 101 | 102 | GNU LIBRARY GENERAL PUBLIC LICENSE 103 | TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 104 | 105 | 0. This License Agreement applies to any software library which 106 | contains a notice placed by the copyright holder or other authorized 107 | party saying it may be distributed under the terms of this Library 108 | General Public License (also called "this License"). Each licensee is 109 | addressed as "you". 110 | 111 | A "library" means a collection of software functions and/or data 112 | prepared so as to be conveniently linked with application programs 113 | (which use some of those functions and data) to form executables. 114 | 115 | The "Library", below, refers to any such software library or work 116 | which has been distributed under these terms. A "work based on the 117 | Library" means either the Library or any derivative work under 118 | copyright law: that is to say, a work containing the Library or a 119 | portion of it, either verbatim or with modifications and/or translated 120 | straightforwardly into another language. (Hereinafter, translation is 121 | included without limitation in the term "modification".) 122 | 123 | "Source code" for a work means the preferred form of the work for 124 | making modifications to it. For a library, complete source code means 125 | all the source code for all modules it contains, plus any associated 126 | interface definition files, plus the scripts used to control compilation 127 | and installation of the library. 128 | 129 | Activities other than copying, distribution and modification are not 130 | covered by this License; they are outside its scope. The act of 131 | running a program using the Library is not restricted, and output from 132 | such a program is covered only if its contents constitute a work based 133 | on the Library (independent of the use of the Library in a tool for 134 | writing it). Whether that is true depends on what the Library does 135 | and what the program that uses the Library does. 136 | 137 | 1. You may copy and distribute verbatim copies of the Library's 138 | complete source code as you receive it, in any medium, provided that 139 | you conspicuously and appropriately publish on each copy an 140 | appropriate copyright notice and disclaimer of warranty; keep intact 141 | all the notices that refer to this License and to the absence of any 142 | warranty; and distribute a copy of this License along with the 143 | Library. 144 | 145 | You may charge a fee for the physical act of transferring a copy, 146 | and you may at your option offer warranty protection in exchange for a 147 | fee. 148 | 149 | 2. You may modify your copy or copies of the Library or any portion 150 | of it, thus forming a work based on the Library, and copy and 151 | distribute such modifications or work under the terms of Section 1 152 | above, provided that you also meet all of these conditions: 153 | 154 | a) The modified work must itself be a software library. 155 | 156 | b) You must cause the files modified to carry prominent notices 157 | stating that you changed the files and the date of any change. 158 | 159 | c) You must cause the whole of the work to be licensed at no 160 | charge to all third parties under the terms of this License. 161 | 162 | d) If a facility in the modified Library refers to a function or a 163 | table of data to be supplied by an application program that uses 164 | the facility, other than as an argument passed when the facility 165 | is invoked, then you must make a good faith effort to ensure that, 166 | in the event an application does not supply such function or 167 | table, the facility still operates, and performs whatever part of 168 | its purpose remains meaningful. 169 | 170 | (For example, a function in a library to compute square roots has 171 | a purpose that is entirely well-defined independent of the 172 | application. Therefore, Subsection 2d requires that any 173 | application-supplied function or table used by this function must 174 | be optional: if the application does not supply it, the square 175 | root function must still compute square roots.) 176 | 177 | These requirements apply to the modified work as a whole. If 178 | identifiable sections of that work are not derived from the Library, 179 | and can be reasonably considered independent and separate works in 180 | themselves, then this License, and its terms, do not apply to those 181 | sections when you distribute them as separate works. But when you 182 | distribute the same sections as part of a whole which is a work based 183 | on the Library, the distribution of the whole must be on the terms of 184 | this License, whose permissions for other licensees extend to the 185 | entire whole, and thus to each and every part regardless of who wrote 186 | it. 187 | 188 | Thus, it is not the intent of this section to claim rights or contest 189 | your rights to work written entirely by you; rather, the intent is to 190 | exercise the right to control the distribution of derivative or 191 | collective works based on the Library. 192 | 193 | In addition, mere aggregation of another work not based on the Library 194 | with the Library (or with a work based on the Library) on a volume of 195 | a storage or distribution medium does not bring the other work under 196 | the scope of this License. 197 | 198 | 3. You may opt to apply the terms of the ordinary GNU General Public 199 | License instead of this License to a given copy of the Library. To do 200 | this, you must alter all the notices that refer to this License, so 201 | that they refer to the ordinary GNU General Public License, version 2, 202 | instead of to this License. (If a newer version than version 2 of the 203 | ordinary GNU General Public License has appeared, then you can specify 204 | that version instead if you wish.) Do not make any other change in 205 | these notices. 206 | 207 | Once this change is made in a given copy, it is irreversible for 208 | that copy, so the ordinary GNU General Public License applies to all 209 | subsequent copies and derivative works made from that copy. 210 | 211 | This option is useful when you wish to copy part of the code of 212 | the Library into a program that is not a library. 213 | 214 | 4. You may copy and distribute the Library (or a portion or 215 | derivative of it, under Section 2) in object code or executable form 216 | under the terms of Sections 1 and 2 above provided that you accompany 217 | it with the complete corresponding machine-readable source code, which 218 | must be distributed under the terms of Sections 1 and 2 above on a 219 | medium customarily used for software interchange. 220 | 221 | If distribution of object code is made by offering access to copy 222 | from a designated place, then offering equivalent access to copy the 223 | source code from the same place satisfies the requirement to 224 | distribute the source code, even though third parties are not 225 | compelled to copy the source along with the object code. 226 | 227 | 5. A program that contains no derivative of any portion of the 228 | Library, but is designed to work with the Library by being compiled or 229 | linked with it, is called a "work that uses the Library". Such a 230 | work, in isolation, is not a derivative work of the Library, and 231 | therefore falls outside the scope of this License. 232 | 233 | However, linking a "work that uses the Library" with the Library 234 | creates an executable that is a derivative of the Library (because it 235 | contains portions of the Library), rather than a "work that uses the 236 | library". The executable is therefore covered by this License. 237 | Section 6 states terms for distribution of such executables. 238 | 239 | When a "work that uses the Library" uses material from a header file 240 | that is part of the Library, the object code for the work may be a 241 | derivative work of the Library even though the source code is not. 242 | Whether this is true is especially significant if the work can be 243 | linked without the Library, or if the work is itself a library. The 244 | threshold for this to be true is not precisely defined by law. 245 | 246 | If such an object file uses only numerical parameters, data 247 | structure layouts and accessors, and small macros and small inline 248 | functions (ten lines or less in length), then the use of the object 249 | file is unrestricted, regardless of whether it is legally a derivative 250 | work. (Executables containing this object code plus portions of the 251 | Library will still fall under Section 6.) 252 | 253 | Otherwise, if the work is a derivative of the Library, you may 254 | distribute the object code for the work under the terms of Section 6. 255 | Any executables containing that work also fall under Section 6, 256 | whether or not they are linked directly with the Library itself. 257 | 258 | 6. As an exception to the Sections above, you may also compile or 259 | link a "work that uses the Library" with the Library to produce a 260 | work containing portions of the Library, and distribute that work 261 | under terms of your choice, provided that the terms permit 262 | modification of the work for the customer's own use and reverse 263 | engineering for debugging such modifications. 264 | 265 | You must give prominent notice with each copy of the work that the 266 | Library is used in it and that the Library and its use are covered by 267 | this License. You must supply a copy of this License. If the work 268 | during execution displays copyright notices, you must include the 269 | copyright notice for the Library among them, as well as a reference 270 | directing the user to the copy of this License. Also, you must do one 271 | of these things: 272 | 273 | a) Accompany the work with the complete corresponding 274 | machine-readable source code for the Library including whatever 275 | changes were used in the work (which must be distributed under 276 | Sections 1 and 2 above); and, if the work is an executable linked 277 | with the Library, with the complete machine-readable "work that 278 | uses the Library", as object code and/or source code, so that the 279 | user can modify the Library and then relink to produce a modified 280 | executable containing the modified Library. (It is understood 281 | that the user who changes the contents of definitions files in the 282 | Library will not necessarily be able to recompile the application 283 | to use the modified definitions.) 284 | 285 | b) Accompany the work with a written offer, valid for at 286 | least three years, to give the same user the materials 287 | specified in Subsection 6a, above, for a charge no more 288 | than the cost of performing this distribution. 289 | 290 | c) If distribution of the work is made by offering access to copy 291 | from a designated place, offer equivalent access to copy the above 292 | specified materials from the same place. 293 | 294 | d) Verify that the user has already received a copy of these 295 | materials or that you have already sent this user a copy. 296 | 297 | For an executable, the required form of the "work that uses the 298 | Library" must include any data and utility programs needed for 299 | reproducing the executable from it. However, as a special exception, 300 | the source code distributed need not include anything that is normally 301 | distributed (in either source or binary form) with the major 302 | components (compiler, kernel, and so on) of the operating system on 303 | which the executable runs, unless that component itself accompanies 304 | the executable. 305 | 306 | It may happen that this requirement contradicts the license 307 | restrictions of other proprietary libraries that do not normally 308 | accompany the operating system. Such a contradiction means you cannot 309 | use both them and the Library together in an executable that you 310 | distribute. 311 | 312 | 7. You may place library facilities that are a work based on the 313 | Library side-by-side in a single library together with other library 314 | facilities not covered by this License, and distribute such a combined 315 | library, provided that the separate distribution of the work based on 316 | the Library and of the other library facilities is otherwise 317 | permitted, and provided that you do these two things: 318 | 319 | a) Accompany the combined library with a copy of the same work 320 | based on the Library, uncombined with any other library 321 | facilities. This must be distributed under the terms of the 322 | Sections above. 323 | 324 | b) Give prominent notice with the combined library of the fact 325 | that part of it is a work based on the Library, and explaining 326 | where to find the accompanying uncombined form of the same work. 327 | 328 | 8. You may not copy, modify, sublicense, link with, or distribute 329 | the Library except as expressly provided under this License. Any 330 | attempt otherwise to copy, modify, sublicense, link with, or 331 | distribute the Library is void, and will automatically terminate your 332 | rights under this License. However, parties who have received copies, 333 | or rights, from you under this License will not have their licenses 334 | terminated so long as such parties remain in full compliance. 335 | 336 | 9. You are not required to accept this License, since you have not 337 | signed it. However, nothing else grants you permission to modify or 338 | distribute the Library or its derivative works. These actions are 339 | prohibited by law if you do not accept this License. Therefore, by 340 | modifying or distributing the Library (or any work based on the 341 | Library), you indicate your acceptance of this License to do so, and 342 | all its terms and conditions for copying, distributing or modifying 343 | the Library or works based on it. 344 | 345 | 10. Each time you redistribute the Library (or any work based on the 346 | Library), the recipient automatically receives a license from the 347 | original licensor to copy, distribute, link with or modify the Library 348 | subject to these terms and conditions. You may not impose any further 349 | restrictions on the recipients' exercise of the rights granted herein. 350 | You are not responsible for enforcing compliance by third parties to 351 | this License. 352 | 353 | 11. If, as a consequence of a court judgment or allegation of patent 354 | infringement or for any other reason (not limited to patent issues), 355 | conditions are imposed on you (whether by court order, agreement or 356 | otherwise) that contradict the conditions of this License, they do not 357 | excuse you from the conditions of this License. If you cannot 358 | distribute so as to satisfy simultaneously your obligations under this 359 | License and any other pertinent obligations, then as a consequence you 360 | may not distribute the Library at all. For example, if a patent 361 | license would not permit royalty-free redistribution of the Library by 362 | all those who receive copies directly or indirectly through you, then 363 | the only way you could satisfy both it and this License would be to 364 | refrain entirely from distribution of the Library. 365 | 366 | If any portion of this section is held invalid or unenforceable under any 367 | particular circumstance, the balance of the section is intended to apply, 368 | and the section as a whole is intended to apply in other circumstances. 369 | 370 | It is not the purpose of this section to induce you to infringe any 371 | patents or other property right claims or to contest validity of any 372 | such claims; this section has the sole purpose of protecting the 373 | integrity of the free software distribution system which is 374 | implemented by public license practices. Many people have made 375 | generous contributions to the wide range of software distributed 376 | through that system in reliance on consistent application of that 377 | system; it is up to the author/donor to decide if he or she is willing 378 | to distribute software through any other system and a licensee cannot 379 | impose that choice. 380 | 381 | This section is intended to make thoroughly clear what is believed to 382 | be a consequence of the rest of this License. 383 | 384 | 12. If the distribution and/or use of the Library is restricted in 385 | certain countries either by patents or by copyrighted interfaces, the 386 | original copyright holder who places the Library under this License may add 387 | an explicit geographical distribution limitation excluding those countries, 388 | so that distribution is permitted only in or among countries not thus 389 | excluded. In such case, this License incorporates the limitation as if 390 | written in the body of this License. 391 | 392 | 13. The Free Software Foundation may publish revised and/or new 393 | versions of the Library General Public License from time to time. 394 | Such new versions will be similar in spirit to the present version, 395 | but may differ in detail to address new problems or concerns. 396 | 397 | Each version is given a distinguishing version number. If the Library 398 | specifies a version number of this License which applies to it and 399 | "any later version", you have the option of following the terms and 400 | conditions either of that version or of any later version published by 401 | the Free Software Foundation. If the Library does not specify a 402 | license version number, you may choose any version ever published by 403 | the Free Software Foundation. 404 | 405 | 14. If you wish to incorporate parts of the Library into other free 406 | programs whose distribution conditions are incompatible with these, 407 | write to the author to ask for permission. For software which is 408 | copyrighted by the Free Software Foundation, write to the Free 409 | Software Foundation; we sometimes make exceptions for this. Our 410 | decision will be guided by the two goals of preserving the free status 411 | of all derivatives of our free software and of promoting the sharing 412 | and reuse of software generally. 413 | 414 | NO WARRANTY 415 | 416 | 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO 417 | WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. 418 | EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR 419 | OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY 420 | KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE 421 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 422 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE 423 | LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME 424 | THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 425 | 426 | 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 427 | WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY 428 | AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU 429 | FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 430 | CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE 431 | LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING 432 | RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A 433 | FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF 434 | SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 435 | DAMAGES. 436 | 437 | END OF TERMS AND CONDITIONS 438 | 439 | How to Apply These Terms to Your New Libraries 440 | 441 | If you develop a new library, and you want it to be of the greatest 442 | possible use to the public, we recommend making it free software that 443 | everyone can redistribute and change. You can do so by permitting 444 | redistribution under these terms (or, alternatively, under the terms of the 445 | ordinary General Public License). 446 | 447 | To apply these terms, attach the following notices to the library. It is 448 | safest to attach them to the start of each source file to most effectively 449 | convey the exclusion of warranty; and each file should have at least the 450 | "copyright" line and a pointer to where the full notice is found. 451 | 452 | 453 | Copyright (C) 454 | 455 | This library is free software; you can redistribute it and/or 456 | modify it under the terms of the GNU Library General Public 457 | License as published by the Free Software Foundation; either 458 | version 2 of the License, or (at your option) any later version. 459 | 460 | This library is distributed in the hope that it will be useful, 461 | but WITHOUT ANY WARRANTY; without even the implied warranty of 462 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 463 | Library General Public License for more details. 464 | 465 | You should have received a copy of the GNU Library General Public 466 | License along with this library; if not, write to the Free Software 467 | Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 468 | 469 | Also add information on how to contact you by electronic and paper mail. 470 | 471 | You should also get your employer (if you work as a programmer) or your 472 | school, if any, to sign a "copyright disclaimer" for the library, if 473 | necessary. Here is a sample; alter the names: 474 | 475 | Yoyodyne, Inc., hereby disclaims all copyright interest in the 476 | library `Frob' (a library for tweaking knobs) written by James Random Hacker. 477 | 478 | , 1 April 1990 479 | Ty Coon, President of Vice 480 | 481 | That's all there is to it! 482 | -------------------------------------------------------------------------------- /scripts/layering_size.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python -Es 2 | # Copyright (C) 2016 Red Hat 3 | # AUTHOR: Brent Baude 4 | # see file 'COPYING' for use and warranty information 5 | # 6 | # layering_size allows you to see the size of each layer that make 7 | # up an image. 8 | # 9 | # This program is free software; you can redistribute it and/or 10 | # modify it under the terms of the GNU General Public License as 11 | # published by the Free Software Foundation; either version 2 of 12 | # the License, or (at your option) any later version. 13 | # 14 | # This program is distributed in the hope that it will be useful, 15 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 16 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 | # GNU General Public License for more details. 18 | # 19 | # You should have received a copy of the GNU General Public License 20 | # along with this program; if not, write to the Free Software 21 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 22 | # 02110-1301 USA. 23 | # 24 | # 25 | 26 | import sys 27 | try: 28 | import docker 29 | except Exception: 30 | sys.exit("The docker-py package is not installed. Install it") 31 | 32 | c = docker.Client() 33 | 34 | if len(sys.argv) < 2: 35 | sys.exit("Pass an image name") 36 | image = sys.argv[1] 37 | 38 | outputs = [] 39 | def get_parent_info(image): 40 | global outputs 41 | inspect_info = c.inspect_image(image) 42 | parent = inspect_info['Parent'] 43 | iid = inspect_info['Id'] 44 | size = inspect_info['Size'] 45 | cmd = "" if inspect_info['ContainerConfig']['Cmd'] is None else " ".join(inspect_info['ContainerConfig']['Cmd']).replace("/bin/sh -c ","") 46 | if len(parent) > 0: 47 | get_parent_info(parent) 48 | outputs.append({'id': iid, 'parent': parent, 'size': size, 'cmd': cmd}) 49 | 50 | return inspect_info['VirtualSize'] 51 | 52 | 53 | 54 | total_size = str(round(float(get_parent_info(image)) / (1000 * 1000), 2)) 55 | print("") 56 | col_out = "{:30} {:10} {:20}" 57 | print(col_out.format("Id", "Size(MB)", 'Command')) 58 | print(col_out.format("-" * 20, "-" * 8, "-" * 10)) 59 | 60 | for image in outputs: 61 | mb = float(image['size']) / (1000 * 1000) 62 | print(col_out.format(image['id'][:30], str(round(mb, 2)), image['cmd'][:60])) 63 | 64 | print("") 65 | print(col_out.format("", "-" * 6, "")) 66 | print(col_out.format("", total_size, "")) 67 | -------------------------------------------------------------------------------- /terminology/terminology_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[Terminology]] 3 | == Terminology 4 | :data-uri: 5 | :homepage https://github.com/projectatomic/container-best-practices: 6 | 7 | === Dictionary 8 | 9 | When discussing containerization, it’s important to have a solid grasp on the related vocabulary. One of the challenges people have is that many of the following terms 10 | are used interchangeably. It can be confusing, especially for newcomers. 11 | 12 | The goal of this section is to clarify these terms, so that we can speak the same language. 13 | 14 | ==== Container Image 15 | 16 | Container image is a filesystem tree that includes all of the requirements for running a container, as well as metadata describing the content. You can think of it as a packaging technology. 17 | 18 | ==== Container 19 | 20 | A container is composed of two things: a writable filesystem layer on top of a container image, and a traditional linux process. 21 | Multiple containers can run on the same machine and share the OS kernel with other containers, each running as an isolated processes in the user space. 22 | Containers take up less space than VMs (application container images are typically tens of MBs in size), and start almost instantly. 23 | 24 | ==== Repository 25 | 26 | When using the `docker` command, a repository is what is specified on the command line, not an image. In the following command, “fedora” is the repository. 27 | 28 | ``` 29 | docker pull fedora 30 | ``` 31 | 32 | This is actually expanded automatically to: 33 | 34 | ``` 35 | docker pull docker.io/library/fedora:latest 36 | ``` 37 | 38 | This can be confusing, and many people refer to this as an image or a container image. In fact, the docker images sub-command is what is used to list the locally available repositories. Conceptually, these repositories can be thought about as container images, but it’s important to realize that these repositories are actually made up of layers. 39 | 40 | When we specify the repository on the command line, the Docker daemon is doing some extra work for you. The Docker daemon (not the client tool) is configured with a list of servers to search. In our example above, the daemon will search for the “fedora” repository on each of the configured servers. 41 | 42 | In the above command, only the repository name was specified, but it’s also possible to specify a full URL address with the Docker client. To highlight this, let’s start with dissecting a full address. 43 | 44 | ``` 45 | REGISTRY[:PORT]/NAMESPACE/REPOSITORY[:TAG] 46 | ``` 47 | 48 | The full URL is made up of a standard server name, a namespace, and optionally a tag. There are actually many permutations of how to specify a URL and as you explore the Docker ecosystem, you will find that many pieces are optional. The following commands are all valid and all pull some permutation of the same repository: 49 | 50 | ``` 51 | docker pull docker.io/library/fedora:latest 52 | docker pull docker.io/library/fedora 53 | docker pull library/fedora 54 | docker pull fedora 55 | ``` 56 | 57 | ==== Image Layer 58 | 59 | Repositories are often referred to as images or container images, but actually they are made up of one or more layers. 60 | Image layers in a repository are connected together in a parent-child relationship. Each image layer represents some pieces of the final container image. 61 | 62 | ==== Registry 63 | A registry server, is essentially a fancy file server that is used to store Docker repositories. 64 | Typically, the registry server is specified as a normal DNS name and optionally a port number to connect to. 65 | Much of the value in the Docker ecosystem comes from the ability to push and pull repositories from registry servers. 66 | 67 | When a Docker daemon does not have a locally cached copy of a repository, it will automatically pull it from a registry server. 68 | Usually the default registry is set to docker.io (Docker Hub). It is important to stress, that there is implicit trust in the registry server. 69 | 70 | You must determine how much you trust the content provided by the registry and you may want to allow or block certain registries. 71 | In addition to security, there are other concerns such as users having access to licensed software and compliance issues. 72 | The simplicity with which Docker allows users to pull software makes it critical that you trust upstream content. 73 | 74 | ==== Namespace 75 | 76 | A namespace is a tool for separating groups of repositories. 77 | On the public DockerHub, the namespace is typically the username of the person sharing the image, but can also be a group name, or a logical name. 78 | 79 | ==== Tag 80 | 81 | When an image builder creates a new repository, they will typically label the best image layers to use. 82 | These are called tags and typically map to versions of software contained in the repository. 83 | In other words, tags are how various images in a repository are distinguished from each other. 84 | 85 | === Container Use Cases 86 | 87 | There are many types of Container design patterns forming. Since containers are the runtime version of a container image, the way a container is built is tightly coupled to how it is run. 88 | 89 | Some Container Images are designed to be run without privileges while others are more specialized and require root-like privileges. 90 | There are many dimensions in which patterns can be evaluated and often users will see multiple patterns or use cases tackled together in one container image/container. 91 | 92 | This section will delve into some of the common use cases that users are tackling with containers. 93 | 94 | ==== Application Containers 95 | 96 | Applications containers are the most popular form of containers. These are what developers and application owners care about. 97 | Application containers contain the code that developers work on. These include, for example, MySQL, Apache, MongoDB, and Node.js. 98 | 99 | ==== Cattle vs Pet Containers 100 | 101 | Containers are usually perceived as a technology that serves for deploying applications that are immutable and can be therefore redeployed or killed any time without severe consequences. As an analogy, these are often referred to as "cattle". Containers in this development environment don't have "identity", the user doesn't need to care where the contianers live in the cluster, the containers are automatically recovered after failures and can be scaled up or down as needed. 102 | In contrast, when a pet container fails, the running application will be directly affected and might fail as well. Similarly as pets, pet containers require user's closer attention and management and are usually accompanied with regular health checks. A typical example would be a containerized database. 103 | 104 | ==== Super Privileged Containers 105 | 106 | When building container infrastructure on dedicated container hosts such as Atomic Host, system administrators still need to perform administrative tasks. 107 | Whether used with distributed systems, such as Kubernetes or OpenShift or standalone container hosts, Super Privileged Containers (SPCs) are a powerful tool. 108 | SPCs can even do things like load specialized kernel modules, such as with systemtap. 109 | In an infrastructure that is built to run containers, administrators will most likely need SPCs to do things like management, monitoring, backups, etc. 110 | It's important to realize that there is typically a tighter coupling between SPCs and the host kernel, so administrators need to choose a rock solid container host and standardize on it, 111 | especially in a large clustered/distributed environment where things are more difficult to troubleshoot. 112 | They then need to select a user space in the SPC that is compatible with the host kernel. 113 | 114 | === Image Types 115 | 116 | ==== Base Images 117 | 118 | A base image is one of the simplest types of images, but you will find a lot of definitions. 119 | Sometimes users will also refer an application image as the “base image.” 120 | However, technically, this is not a base image, these are link:#intermediate_images[Intermediate images]. 121 | 122 | Simply put, a base image is an image that has no parent layer. Typically, a base image contains a fresh copy of an operating system. 123 | Base images normally include core system tools, such as bash or coreutils and tools necessary to install packages and make updates to the image over time (yum, rpm, apt-get, dnf, microdnf...) 124 | While base images can be “hand crafted”, in practice they are typically produced and published by open source projects (like Debian, Fedora or CentOS) and vendors (like Red Hat). 125 | The provenance of base images is critical for security. In short, the sole purpose of a base image is to provide a starting place for creating your derivative images. 126 | When using a Dockerfile, the choice of which base image you are using is explicit: 127 | ``` 128 | FROM registry.fedoraproject.org/fedora 129 | ``` 130 | [[Builder_images]] 131 | ==== Builder Images 132 | 133 | These are a specialized form of container images which produce application container images as offspring. 134 | They include everything but a developer's source code. Builder images include operating system libraries, language runtimes, middleware, and the source-to-image tooling. 135 | 136 | When a builder image is run, it injects the developers source code and produces a ready-to-run offspring application container image. 137 | This newly created application container image can then be run in development or production. 138 | 139 | For example, if a developer has PHP code and they want to run it in a container, they can use a PHP builder image to produce a ready to run application container image. 140 | The developer passes the GitHub URL where the code is stored and the builder image does the rest of the work for them. 141 | The output of a Builder container is an Application container image which includes Red Hat Enterprise Linux, PHP from Software Collections, and the developer’s code, all together, ready to run. 142 | Builder images provide a powerful way to go from code to container quickly and easily, building off of trusted components. 143 | 144 | Some Builder images are created in a way that allows developers to not only provide their source code, but also custom configuration for software built into the image. 145 | One such example is the https://github.com/openshift/source-to-image/tree/master/examples/nginx-centos7#configuring-nginx[Nginx Builder image] in the source-to-image upstream repository. 146 | 147 | [[intermediate_images]] 148 | ==== Intermediate Images 149 | 150 | An Intermediate image is any container image which relies on a base image. Typically, core builds, middleware and language runtimes are built as layers on “top of” a base image. 151 | These images are then referenced in the FROM directive of another image. These images are not used on their own, they are typically used as a building block to build a standalone image. 152 | 153 | It is common to have different teams of specialists own different layers of an image. 154 | Systems administrators may own the core build layer, while “developer experience” may own the middleware layer. 155 | Intermediate Images are built to be consumed by other teams building images, but can sometimes be ran standalone too, especially for testing. 156 | 157 | 158 | ==== Intermodal Images 159 | 160 | Intermodal container images are images that have hybrid architectures. For example, many Red Hat Software Collections images can be used in two ways. 161 | 162 | First, they can be used as simple Application Containers running a fully contained Ruby on Rails and Apache server. 163 | 164 | Second, they can be used as Builder Images inside of OpenShift Container Platform. 165 | In this case, the output child images which contain Ruby on Rails, Apache, and the application code which the source-to-image process was pointed towards during the build phase. 166 | 167 | The intermodal pattern is becoming more and more common to solve two business problems with one container image. 168 | 169 | ==== Deployer Images 170 | 171 | A deployer image is a specialized kind of container which, when run, deploys or manages other containers. 172 | This pattern enables sophisticated deployment techniques such as mandating the start order of containers, or first run logic such as populating schema or data. 173 | 174 | // TBD: Container patterns could nicely add to this 175 | 176 | ==== Containerized Components 177 | 178 | A container that is meant to be deployed as part of a larger software system, not on its own. Two major trends are driving this. 179 | 180 | First, microservices are driving the use of best-of-breed components - this is also driving the use of more components combined together to build a single application. 181 | Containerized components are meeting the need to deploy an expanding quantity of complex software more quickly and easily. 182 | 183 | Second, not all pieces of software are easy to deploy as containers. Sometimes, it makes sense to containerize only certain 184 | components which are easier to move to containers or provide more value to the overall project. With multi-service application, some services may be deployed as containers, while others may be deployed through traditional a traditional methodology such as an RPM or installer script. 185 | 186 | It’s important to understand that containerized components are not designed to function on their own. 187 | They provide value to a larger piece of software, but provide very little value on their own. 188 | -------------------------------------------------------------------------------- /testing/testing_index.adoc: -------------------------------------------------------------------------------- 1 | // vim: set syntax=asciidoc: 2 | [[Testing]] 3 | == Testing 4 | :data-uri: 5 | :toc: 6 | :toclevels 4: 7 | :homepage https://github.com/projectatomic/container-best-practices: 8 | 9 | === What Should be Tested 10 | 11 | Container images generally consist of distribution packages and some scripts that help start the container properly. For example, a container with a MariaDB database typically consists of a set of RPMs, such as mariadb-server, that provides the main functionality, and scripts that handle initialization, setup, etc. A simplified example of MariaDB Dockerfile may look like this: 12 | [source,Dockerfile] 13 | ---- 14 | FROM fedora:24 15 | 16 | RUN true \ 17 | && dnf install -y mariadb-server \ 18 | && dnf clean all \ 19 | && /usr/libexec/container-setup \ 20 | && true 21 | 22 | COPY run-mysqld /usr/bin/ 23 | COPY container-setup /usr/libexec/ 24 | 25 | VOLUME ["/var/lib/mysql/data"] 26 | USER 27 27 | 28 | CMD ["run-mysqld"] 29 | ---- 30 | 31 | If we want to test the basic functionality of the container, we do not have to test the RPM functionality. The benefit of using the distribution packaging is that we know testing has already been done during the RPM develpment process. Instead, we need to focus on testing of the added scripts instead and the API of the container. The goal is to determine if it works as described. For example, for the MariaDB database container, we do not run the MariaDB unit tests in the container. Instead we focus on whether the database is initialized, configured, and responds to commands properly. 32 | 33 | === Conventions for Test Scripts 34 | 35 | It is good practice to keep the basic sanity tests for the image together with the image sources. For example test/run might be a script, that tests the image specified by the IMAGE_NAME environment variable, so users may specify an image which should be tested. 36 | 37 | === Examples of Test Scripts 38 | 39 | These examples of test scripts can be found in the container images for Software Collections: 40 | 41 | * https://github.com/sclorg/postgresql-container/blob/master/9.5/test/run 42 | * https://github.com/sclorg/s2i-python-container/blob/master/3.5/test/run 43 | 44 | A minimal script that verifies a container image by running it as a daemon and then running a script that checks the proper functionality, is shown below. It stores the IDs of the containers created during the test in a temporary directory. This makes it easy to clean up those containers after the test finishes. 45 | 46 | [source,bash] 47 | ---- 48 | #!/bin/bash 49 | # 50 | # General test of the image. 51 | # 52 | # IMAGE_NAME specifies the name of the candidate image used for testing. 53 | # The image has to be available before this script is executed. 54 | # 55 | 56 | set -exo nounset 57 | shopt -s nullglob 58 | 59 | IMAGE_NAME=${IMAGE_NAME-default-image-name} 60 | CIDFILE_DIR=$(mktemp --suffix=test_cidfiles -d) 61 | 62 | # clears containers run during the test 63 | function cleanup() { 64 | for cidfile in $CIDFILE_DIR/* ; do 65 | CONTAINER=$(cat $cidfile) 66 | 67 | echo "Stopping and removing container $CONTAINER..." 68 | docker stop $CONTAINER 69 | exit_status=$(docker inspect -f '{{.State.ExitCode}}' $CONTAINER) 70 | if [ "$exit_status" != "0" ]; then 71 | echo "Dumping logs for $CONTAINER" 72 | docker logs $CONTAINER 73 | fi 74 | docker rm $CONTAINER 75 | rm $cidfile 76 | echo "Done." 77 | done 78 | rmdir $CIDFILE_DIR 79 | } 80 | trap cleanup EXIT 81 | 82 | # returns ID of specified named container 83 | function get_cid() { 84 | local id="$1" ; shift || return 1 85 | echo $(cat "$CIDFILE_DIR/$id") 86 | } 87 | 88 | # returns IP of specified named container 89 | function get_container_ip() { 90 | local id="$1" ; shift 91 | docker inspect --format='{{.NetworkSettings.IPAddress}}' $(get_cid "$id") 92 | } 93 | 94 | # runs command to test running container 95 | function test_image() { 96 | local name=$1 ; shift 97 | echo " Testing Image" 98 | docker run --rm $IMAGE_NAME get_status `get_container_ip $name` 99 | echo " Success!" 100 | } 101 | 102 | # start a new container 103 | function create_container() { 104 | local name=$1 ; shift 105 | cidfile="$CIDFILE_DIR/$name" 106 | # create container with a cidfile in a directory for cleanup 107 | docker run --cidfile $cidfile -d $IMAGE_NAME 108 | echo "Created container $(cat $cidfile)" 109 | } 110 | 111 | 112 | # Tests. 113 | 114 | create_container test1 115 | test_image test1 116 | ---- 117 | 118 | // === Build Testing 119 | // === Image Scanning 120 | -------------------------------------------------------------------------------- /toc.py: -------------------------------------------------------------------------------- 1 | import sys 2 | toc_file = open('toc.html','w') 3 | 4 | for line in open('index.html'): 5 | if '
' not in line: 6 | toc_file.write(line) 7 | else: 8 | toc_file.write("") 9 | toc_file.write("") 10 | toc_file.close() 11 | sys.exit() 12 | --------------------------------------------------------------------------------