From 038259d62a4d321eb327a5f47cd941f77ba68d57 Mon Sep 17 00:00:00 2001 From: Brent Baude Date: Feb 04 2016 20:56:01 +0000 Subject: Updated Outline and Makefile Updating the outline by integrating the older content into the new outline. Also adding new headers for new contant. Changed the make pdf from a2x to asciidoctor-pdf so that links and special styles work. --- diff --git a/Makefile b/Makefile index 4515e66..abb43f8 100644 --- a/Makefile +++ b/Makefile @@ -30,7 +30,8 @@ publish: $(LABS) git push origin gh-pages -f pdf: $(LABS) - a2x -fpdf -dbook --fop --no-xmllint -v index.adoc + #a2x -fpdf -dbook --fop --no-xmllint -v index.adoc + asciidoctor -r asciidoctor-pdf -b pdf -o container_best_practices.pdf index.adoc epub: $(LABS) $(SLIDES) a2x -fepub -dbook --no-xmllint -v index.adoc diff --git a/appendix/appendix_index.html b/appendix/appendix_index.html deleted file mode 100644 index 06fa48b..0000000 --- a/appendix/appendix_index.html +++ /dev/null @@ -1,120 +0,0 @@ - - - - - - - -Appendix - - - - -
-
-

Appendix

-
-
-

Atomic application

-
-

The atomic application is meant to be a user-friendly way to -install, manage, and run container images using container. Unlike docker commands, it leverages the ability -read and act upon LABELs defined in a Dockerfile. By its nature, it helps authors of Dockerfiles to have -their images run as they intended without a significant amount of knowledge by the end users. Atomic has several -subcommands:

-
-
-
    -
  • -

    diff

    -
    • -
  • -

    help

    -
    • -
  • -

    host

    -
    • -
  • -

    info

    -
    • -
  • -

    install

    -
    • -
  • -

    images

    -
    • -
  • -

    migrate

    -
    • -
  • -

    mount

    -
    • -
  • -

    push

    -
    • -
  • -

    scan

    -
    • -
  • -

    stop

    -
    • -
  • -

    run

    -
    • -
  • -

    top

    -
    • -
  • -

    uninstall

    -
    • -
  • -

    unmount

    -
    • -
  • -

    update

    -
    • -
  • -

    version

    -
    • -
  • -

    verify

    -
    • -
-
-
-

Knowledge of these subcommands can make you a better author of Dockerfiles because you too can simplify end users' -interactions with your images. Look to the following sections for more information on these relevant subcommands.

-
-
-

Displaying the help file

-
-

You can display the help file for a container using the atomic command. -For example, to display the help file for a container called foobar, you would run the command:

-
-
-
-
# atomic help foobar
-
-
-
-

This is the default method of displaying the help file. In this case, the help file is formatted like any typical -man page and is displayed (like man) with a pager. The help file needs to be located in the / of the image filesystem -and called help.1.

-
-
-

If no help file is present and there is no HELP LABEL defined, atomic will simply tell you it could not find any -help associated with that container or image.

-
-
-
-
-
-
- - - \ No newline at end of file diff --git a/creating/creating_index.adoc b/creating/creating_index.adoc index 9af15ca..a5e27b6 100644 --- a/creating/creating_index.adoc +++ b/creating/creating_index.adoc @@ -6,6 +6,14 @@ :toclevels 4: :homepage https://github.com/projectatomic/container-best-practices: +The base unit of creating an image is the Dockerfile itself. This section +focuses on the the instructions that make up a Dockerfile. + +This chapter will not cover every Dockerfile instruction available but instead +will focus on specific ones that we want to re-enforce to those who develop +Dockerfiles. Docker has published a +link:https://docs.docker.com/engine/reference/builder/[reference guide] already +covering each of the Dockerfile instructions. === Upstream Docker Best Practices @@ -21,6 +29,90 @@ recommendations. ===== Docker Base Image Creation +=== Create small and concise images + +It is preferable to create small and concise images whenever possible. This can +be highly dependent on the application you are containerizing, but there are +techniques to help you accomplish this. The following sections cover these +techniques. + +==== Clear packaging caches and temporary package downloads + +To keep images as small as possible, it is beneficial to clear the temporary yum cache files after installing or updating packages. To remove unnecessary cache files, use the **yum clean** command. The command is described in detail in the +yum(8)+ man page. + +Cache needs to be cleaned out of every layer that updates or installs software. That means if you perform multiple install operations within one layer, you need to run **yum clean** at the end of it. For example: + +---- +RUN yum install -y epel-release && \ + rpmkeys --import file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7 && \ + yum install -y --setopt=tsflags=nodocs bind-utils gettext iproute\ + v8314 mongodb24-mongodb mongodb24 && \ + yum clean all +---- + +On the other hand, if you perform multiple install/update operations on multiple layers, **yum clean** must be run on each layer. For example: + +---- +RUN yum install -y epel-release && \ + rpmkeys --import file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7 && \ + yum clean all + +RUN yum install -y --setopt=tsflags=nodocs bind-utils gettext iproute\ + v8314 mongodb24-mongodb mongodb24 && \ + yum clean all +---- + +==== Installing Documentation + +Because you want to keep the image as small as possible, you can avoid installing documentation files along with installing or updating software by specifying the **nodocs** flag. For example: + +---- +RUN yum install -y mysql --setopt=tsflags=nodocs +---- + +==== Updating Software supplied by Base-Image + +Avoid updating software supplied by base-image unless necessary. Base images themselves are meant to be updated on a regular basis by the supplier and provide software that has been tested for a particular environment. + +Also, updating base-image software in layered images can introduce unexpected problems or bring in unwanted dependencies and in certain cases significantly expand the image size. + +In other words, avoid using instructions similar to this one: + +---- +RUN yum -y update +---- + +// TBD: different recommendations for Fedora and CentOS/RHEL base images? + +==== Minimizing the Number of Layers + +In general, having fewer layers improves readability. Commands that are chained together become a part of the same layer. To reduce the number of layers, chain commands together. Find a balance, though, between a large number of layers (and a great many commands), and a small number of layers (and obscurity caused by brevity). + +A new layer is created for every new instruction defined. This does not necessarily mean that one instruction should be associated with only one command or definition. + +Ensure transparency and provide a good overview of the content of each layer by grouping related operations together so that they together constitute a single layer. Consider this snippet from the OpenShift Python 3.3 Dockerfile: + +---- +RUN yum install -y \ + https://www.softwarecollections.org/en/scls/rhscl/python33/epel-7-x86_64/download/rhscl-python33-epel-7-x86_64.noarch.rpm && \ + yum install -y --setopt=tsflags=nodocs --enablerepo=centosplus \ + python33 python33-python-devel python33-python-setuptools \ + epel-release && \ + yum install -y --setopt=tsflags=nodocs install nss_wrapper && \ + yum clean all -y && \ + scl enable python33 "easy_install pip" && \ + chown -R default:default /opt/openshift && \ + chmod -R og+rwx /opt/openshift +---- + +Each command that is related to the installation and configuration of `sti-python` is grouped together as a part of the same layer. This meaningful grouping of operations keeps the number of layers low while keeping the easy legibility of the layers high. + +// Find a good example for the opposite case, when we want to have similar operations split into multiple instructions. + +==== Squashing layers + +// can this be done by joe regular? + === Labels Labels in Dockerfiles serve as a useful way to organize and document metadata used to describe an image. Some labels are only descriptive @@ -31,8 +123,6 @@ purposed and can viewed manually with the _docker inspect _ command. The authoritative source for labels is the https://github.com/projectatomic/ContainerApplicationGenericLabels[Container Application Generic Labels] git repository. - - ==== When are they required? ==== Descriptive labels @@ -85,8 +175,6 @@ way. The following table describes the defined action-oriented labels. === Image naming -=== Verifying your Dockerfile (linter) - === Starting your application Generally the RUN instruction in the Dockerfile is used by docker to start your application @@ -160,6 +248,8 @@ include::help.adoc[] === Creating a Changelog +=== Verifying Dockerfile (linter) + OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - OLD - @@ -189,53 +279,6 @@ TBD // maybe move somewhere RHEL-specific -==== Clearing the yum Caches - -To keep images as small as possible, it is beneficial to clear the temporary yum cache files after installing or updating packages. To remove unnecessary cache files, use the **yum clean** command. The command is described in detail in the +yum(8)+ man page. - -Cache needs to be cleaned out of every layer that updates or installs software. That means if you perform multiple install operations within one layer, you need to run **yum clean** at the end of it. For example: - ----- -RUN yum install -y epel-release && \ - rpmkeys --import file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7 && \ - yum install -y --setopt=tsflags=nodocs bind-utils gettext iproute\ - v8314 mongodb24-mongodb mongodb24 && \ - yum clean all ----- - -On the other hand, if you perform multiple install/update operations on multiple layers, **yum clean** must be run on each layer. For example: - ----- -RUN yum install -y epel-release && \ - rpmkeys --import file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-7 && \ - yum clean all - -RUN yum install -y --setopt=tsflags=nodocs bind-utils gettext iproute\ - v8314 mongodb24-mongodb mongodb24 && \ - yum clean all ----- - -==== Installing Documentation - -Because you want to keep the image as small as possible, you can avoid installing documentation files along with installing or updating software by specifying the **nodocs** flag. For example: - ----- -RUN yum install -y mysql --setopt=tsflags=nodocs ----- - -==== Updating Software supplied by Base-Image - -Avoid updating software supplied by base-image unless necessary. Base images themselves are meant to be updated on a regular basis by the supplier and provide software that has been tested for a particular environment. - -Also, updating base-image software in layered images can introduce unexpected problems or bring in unwanted dependencies and in certain cases significantly expand the image size. - -In other words, avoid using instructions similar to this one: - ----- -RUN yum -y update ----- - -// TBD: different recommendations for Fedora and CentOS/RHEL base images? ==== Users TBD @@ -322,43 +365,6 @@ ENTRYPOINT ["/usr/bin/python"] ---- -==== systemd - -tbd - -==== non-systemd - -tbd - -=== Layering - -This chapter provides guidelines on creating layers. - -==== Minimizing the Number of Layers - -In general, having fewer layers improves readability. Commands that are chained together become a part of the same layer. To reduce the number of layers, chain commands together. Find a balance, though, between a large number of layers (and a great many commands), and a small number of layers (and obscurity caused by brevity). - -A new layer is created for every new instruction defined. This does not necessarily mean that one instruction should be associated with only one command or definition. - -Ensure transparency and provide a good overview of the content of each layer by grouping related operations together so that they together constitute a single layer. Consider this snippet from the OpenShift Python 3.3 Dockerfile: - ----- -RUN yum install -y \ - https://www.softwarecollections.org/en/scls/rhscl/python33/epel-7-x86_64/download/rhscl-python33-epel-7-x86_64.noarch.rpm && \ - yum install -y --setopt=tsflags=nodocs --enablerepo=centosplus \ - python33 python33-python-devel python33-python-setuptools \ - epel-release && \ - yum install -y --setopt=tsflags=nodocs install nss_wrapper && \ - yum clean all -y && \ - scl enable python33 "easy_install pip" && \ - chown -R default:default /opt/openshift && \ - chmod -R og+rwx /opt/openshift ----- - -Each command that is related to the installation and configuration of `sti-python` is grouped together as a part of the same layer. This meaningful grouping of operations keeps the number of layers low while keeping the easy legibility of the layers high. - -// Find a good example for the opposite case, when we want to have similar operations split into multiple instructions. - ==== Squashing Layers tbd diff --git a/index.html b/index.html deleted file mode 100644 index e69de29..0000000 --- a/index.html +++ /dev/null diff --git a/planning/planning_index.adoc b/planning/planning_index.adoc index 4d4d4e3..b206416 100644 --- a/planning/planning_index.adoc +++ b/planning/planning_index.adoc @@ -8,6 +8,67 @@ Careful planning is important when working with container technology. === Deconstructing an application for containers +=== Application Classes + +We have defined applications into four general categories: + +. System Services +. Client Tools +. Service Components +. Micro-service Applications + + +==== System Services + +System services are a special kind of application. These are drivers or system agents +that extend the functionality of the host system. They are typically single-container +images. They are typically run using automation during a start-up script like cloud-init or a +configuration management system. System service containers require special runtime configuration to +enable the appropriate level of privilege to modify the host system. They are commonly referred as +Super Privileged Containers (SPCs). They utilize the benefits of container packaging but not separation. + +==== Client Tools + +Client Tools applications are another special kind of application. These are used by end-users who do +not wish to install a client using traditional packaging such as RPM. Container technology enables an +end-user to add a client to their workstation without modifying the operating system. + +There are an endless number of potential clients for this class of applications. A few examples include +remote clients such as OpenStack or Amazon Web Services (AWS) client tools. An extension of the model is +vagrant-like development environment where a tool set for a given project is packaged. For example, +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] +is a toolkit for interacting with an immutable Atomic host system. It includes git, strace and sosreport, for example. + +Two important architectural decisions should be considered for client container images. + +. How does the end-user interact with the container? Will they use them like traditional command line +interface (CLI) tools? Or will they enter the container environment as a shell, perform some commands, then exit. +The entrypoint command chosen for the container will determine the default behavior. +. Will end-users will need access to files on the host system? If so, will the default behavior bindmount +the current working directory or a user-specified directory? + +==== Service Components + +Service components are applications that an application developer integrates with. Databases are common examples. +A database is typically a component of a larger application. + +The challenge of porting service components to container technology is optimizing integration. Will the application +developer be able to configure the service to their needs? Will the application developer have sufficient documentation +to install, configure and secure the service being integrated? + +==== Microservice Applications + +The microservice architecture is particularly well-suited to container technology. Martin Fowler describes microservice +applications as "suites of independently deployable services."footnote:[Martin Fowler, +http://martinfowler.com/articles/microservices.html] Well-designed microservice applications have a clean separation +of code, configuration and data. + +Planning is especially critical for microservice applications because they are especially challenging to port to +container technology. The planning phase must include experts who understand the application's architecture and +service topology, performance characteristics, configuration and dependencies such as networking and storage. While +many applications can be ported to container technology without modification there are sometimes optimizations that +should be made regarding configuration, storage, installation or service architecture. + ==== Security and user requirements ==== Persistent vs ephemeral storage @@ -71,36 +132,6 @@ within a container. OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD OLD -=== Application Classes - -There are many different kinds of applications that may be candidates for porting to container technology. - -==== System Services - -System services are a special kind of application. These are drivers or system agents that extend the functionality of the host system. They are typically single-container images. They are typically run using automation during a start-up script like cloud-init or a configuration management system. System service containers require special runtime configuration to enable the appropriate level of privilege to modify the host system. They are commonly referred as Super Privileged Containers (SPCs). They utilize the benefits of container packaging but not separation. - -==== Client Tools - -Client Tools applications are another special kind of application. These are used by end-users who do not wish to install a client using traditional packaging such as RPM. Container technology enables an end-user to add a client to their workstation without modifying the operating system. - -There are an endless number of potential clients for this class of applications. A few examples include remote clients such as OpenStack or Amazon Web Services (AWS) client tools. An extension of the model is vagrant-like development environment where a tool set for a given project is packaged. For example, 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] is a toolkit for interacting with an immutable Atomic host system. It includes git, strace and sosreport, for example. - -Two important architectural decisions should be considered for client container images. - -. How does the end-user interact with the container? Will they use them like traditional command line interface (CLI) tools? Or will they enter the container environment as a shell, perform some commands, then exit. The entrypoint command chosen for the container will determine the default behavior. -. Will end-users will need access to files on the host system? If so, will the default behavior bindmount the current working directory or a user-specified directory? - -==== Service Components - -Service components are applications that an application developer integrates with. Databases are common examples. A database is typically a component of a larger application. - -The challenge of porting service components to container technology is optimizing integration. Will the application developer be able to configure the service to their needs? Will the application developer have sufficient documentation to install, configure and secure the service being integrated? - -==== Microservice Applications - -The microservice architecture is particularly well-suited to container technology. Martin Fowler describes microservice applications as "suites of independently deployable services."footnote:[Martin Fowler, http://martinfowler.com/articles/microservices.html] Well-designed microservice applications have a clean separation of code, configuration and data. - -Planning is especially critical for microservice applications because they are especially challenging to port to container technology. The planning phase must include experts who understand the application's architecture and service topology, performance characteristics, configuration and dependencies such as networking and storage. While many applications can be ported to container technology without modification there are sometimes optimizations that should be made regarding configuration, storage, installation or service architecture. === Deconstructing Microservice Applications