From Fedora Project Wiki

Line 1: Line 1:
{{Draft}}
 
 
 
= Container Maintainer Guidelines =
 
= Container Maintainer Guidelines =
  
Line 11: Line 9:
 
== Container Guidelines ==
 
== Container Guidelines ==
  
The Container Guidelines are a collection of common issues and the severity that should be placed on them. While these guidelines should not be ignored, they should also not be blindly followed. If you think that your container should be exempt from part of the Guidelines, please bring the issue to the Fedora Container Committee (Pending Existence). In the absence of a Fedora Container Committee, please seek guidance from the [[Cloud_SIG|Fedora Cloud SIG|]].
+
The Container Guidelines are a collection of common issues and the severity that should be placed on them. While these guidelines should not be ignored, they should also not be blindly followed. If you think that your container should be exempt from part of the Guidelines, please bring the issue to the Fedora Container Committee (Pending Existence). In the absence of a Fedora Container Committee, please seek guidance from the [[Cloud_SIG|Fedora Cloud SIG]].
  
 
=== Docker Containers (Dockerfile) ===
 
=== Docker Containers (Dockerfile) ===
Line 29: Line 27:
  
 
{|
 
{|
!Name  
+
!Name
 
!Description
 
!Description
 
|-
 
|-
Line 48: Line 46:
 
|}
 
|}
  
 +
{{admon/note|Dockerfile Label Guidelines Upstream|
 +
The LABELs used here are meant to be a Fedora adaptation of the upstream [https://projectatomic.io Project Atomic] effort to define [https://github.com/projectatomic/ContainerApplicationGenericLabels Container Application Generic Labels].
 +
}}
  
 +
These LABELs should be defined in a single line of the Dockerfile such that they don't each lead to another layer in the build. The following is a very simple Dockerfile example containing the required LABELs:
  
These LABELs should be defined in a single line of the Dockerfile such that they don't each lead to another layer in the build. The following is a very simple Dockerfile example containing the required LABELs:
+
A recommended pattern is to define these items as ENV variables such that they can be used elsewhere, also note the <code>$FGC</code> and <code>$DISTTAG</code>.
 +
 
 +
<code>$FGC</code> is defined as Fedora Generational Core by the [[Modularity|Fedora Modularity]] effort as a part of [[BaseRuntime| the Base Runtime]] and will serve as our docker registry namespace.
 +
 
 +
<code>$DISTTAG</code> is defined just as it is for RPMs, but since Dockerfiles lack a mechanism similar to RPM Macros this is being stored in the base image such that it can be inherited by layered images.
 +
 
 +
By following the pattern below, we can define the container specific information in one place on the ENV line and have it be set properly in the LABEL line (again, noting the <code>$FGC</code> and <code>$DISTTAG</code> being used but never defined as these are inherited).
  
 
<pre>
 
<pre>
FROM fedora
+
FROM fedora:25
 
MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>
 
MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>
  
LABEL BZComponent="myawesomecontainer" \
+
ENV NAME=myawesomecontainer VERSION=0.1 RELEASE=1 ARCH=x86_64
         Name="fedora/myawesomecontainer" \
+
LABEL BZComponent="$NAME" \
         Version="0.1" \
+
         Name="$FGC/$NAME" \
         Release="1" \
+
         Version="$VERSION" \
         Architecture="x86_64"
+
         Release="$RELEASE.$DISTTAG" \
 +
         Architecture="$ARCH"
 
</pre>
 
</pre>
  
Line 67: Line 76:
 
Another item required is a CMD or ENTRYPOINT entry so that when an user were run perform the following command (for example), expected behavior occurs.:
 
Another item required is a CMD or ENTRYPOINT entry so that when an user were run perform the following command (for example), expected behavior occurs.:
  
<pre>docker run registry.fedoraproject.org/fedora/myawesomecontainer</pre>
+
<pre>docker run registry.fedoraproject.org/f25/myawesomecontainer</pre>
  
 
For more information on these entries, please reference the upstream [https://docs.docker.com/engine/reference/builder/ Dockerfile documentation]. The following is extending on the above example, showing a CMD directive.
 
For more information on these entries, please reference the upstream [https://docs.docker.com/engine/reference/builder/ Dockerfile documentation]. The following is extending on the above example, showing a CMD directive.
  
 
<pre>
 
<pre>
FROM fedora
+
FROM fedora:25
 
MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>
 
MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>
  
LABEL BZComponent="myawesomecontainer" \
+
ENV NAME=myawesomecontainer VERSION=0.1 RELEASE=1 ARCH=x86_64
         Name="fedora/myawesomecontainer" \
+
LABEL BZComponent="$NAME" \
         Version="0.1" \
+
         Name="$FGC/$NAME" \
         Release="1" \
+
         Version="$VERSION" \
         Architecture="x86_64"
+
         Release="$RELEASE.$DISTTAG" \
 +
         Architecture="$ARCH"
  
 
CMD printf "My Awesome Container!\n"
 
CMD printf "My Awesome Container!\n"
Line 86: Line 96:
 
== Content ==
 
== Content ==
  
Dockerfiles in Fedora should not contain net new code, which is unfortunately subjective in nature. The meaning of this is that software should be packaged properly as RPMs and placed in the Fedora repositories, Dockerfiles are simply a deliver mechanism for pre-defined "ready to run" configurations. This can be achieved as an [https://github.com/projectatomic/atomicapp/blob/master/docs/start_guide.md Atomic App] or similar. Any content that is to accompany the Dockerfile must either be configuration files or startup/orchestration scripts. The goal of this is such that we follow the key points of the [https://docs.pagure.org/releng/philosophy.html Fedora Release Engineering Philosophy].
+
Dockerfiles in Fedora should not contain net new code. The meaning of this is that software should be packaged properly as RPMs and placed in the Fedora repositories, Dockerfiles are simply a deliver mechanism for pre-defined "ready to run" configurations. This can be achieved as an [https://github.com/projectatomic/atomicapp/blob/master/docs/start_guide.md Atomic App] or similar. Any content that is to accompany the Dockerfile must either be configuration files or startup/orchestration scripts. The goal of this is such that we follow the key points of the [https://docs.pagure.org/releng/philosophy.html Fedora Release Engineering Philosophy].
  
 
=== Multi Container Services ===
 
=== Multi Container Services ===
Line 93: Line 103:
 
These types of multi-container services should be documented in such a way that users can adapt them to their needs. One example would be using the [https://projectatomic.io Project Atomic] [https://github.com/projectatomic/nulecule nulecule] specification.
 
These types of multi-container services should be documented in such a way that users can adapt them to their needs. One example would be using the [https://projectatomic.io Project Atomic] [https://github.com/projectatomic/nulecule nulecule] specification.
  
{{admon/important|FIXME|We need an user facing outlet (possibly searchable) for this kind of information to live on so that it's easy for users to consume this content. Possibly some sort of dnf plugin to search for ready-to-run multi-container service configurations or similar.}}
+
{{admon/important|Future|In the future there will be an user facing outlet such that this information can be index and searched so that it's easy for users to consume this content. Our long term [[Changes/FedoraDockerRegistry| Fedora Docker Registry]] goals are still in development}}
  
 
= Discussion =
 
= Discussion =
 +
 +
For suggestions, feedback, or to report issues with this page please contact the [[Cloud|Fedora Cloud SIG]].
  
 
See [[Talk:PackagingDrafts/Containers]] for discussion.
 
See [[Talk:PackagingDrafts/Containers]] for discussion.
 
[[Category:Packaging guidelines drafts]]
 

Revision as of 20:27, 9 December 2016

Container Maintainer Guidelines

In the Fedora world, the concept of being a Package Maintainer is well known as all the software currently released and published as an official "Build Artifact" of the Fedora Project for inclusion in the Fedora GNU/Linux distribution has always been packaged in RPM Package Manager Format.

However, as technology changes so must the Fedora Project. The concept of "containers" on Linux has become quite prominent and Fedora will be publishing container images as officially released Build Artifact. One thing to note is that containers images are not a new software packaging format but more so a delivery mechanism where many different things such be easily shipped as a single unit. An example of this is packages that can be combined to deliver an easily ran "software solution".

Below you will find Guidelines similar in nature to that of the Fedora Packaging Guidelines but catered towards the concept of Containers. Initially Fedora will be targeting the Docker container implemention but there are many and others will likely be incorporated in the future.

Container Guidelines

The Container Guidelines are a collection of common issues and the severity that should be placed on them. While these guidelines should not be ignored, they should also not be blindly followed. If you think that your container should be exempt from part of the Guidelines, please bring the issue to the Fedora Container Committee (Pending Existence). In the absence of a Fedora Container Committee, please seek guidance from the Fedora Cloud SIG.

Docker Containers (Dockerfile)

Docker images are built using a Dockerfile much in the same way an RPM is built using a spec file. In this section are Fedora Guidelines for creating Docker images using a Dockerfile.


Note.png
Dockerfile Guidelines Upstream
These guidelines are a Fedora adaptation of the Upstream Project Atomic effort to define Container Best Practices.

LABELS

Dockerfiles have a concept of a LABEL which can add arbitrary metadata to an image as a key-value pair. Fedora Guidelines on the topic of LABELs follows the Project Atomic Container Application Generic Labels standards for LABEL definition.

Required LABELs for a Fedora Docker Image are as follows:

Name Description
BZComponent The Bugzilla component name where bugs against this container should be reported by users.
Name Name of the Image
Version Version of the image
Release Release Number for this version
Architecture Architecture the software in the image should target (Optional: if omitted, it will be built for all supported Fedora Architectures)
Note.png
Dockerfile Label Guidelines Upstream
The LABELs used here are meant to be a Fedora adaptation of the upstream Project Atomic effort to define Container Application Generic Labels.

These LABELs should be defined in a single line of the Dockerfile such that they don't each lead to another layer in the build. The following is a very simple Dockerfile example containing the required LABELs:

A recommended pattern is to define these items as ENV variables such that they can be used elsewhere, also note the $FGC and $DISTTAG.

$FGC is defined as Fedora Generational Core by the Fedora Modularity effort as a part of the Base Runtime and will serve as our docker registry namespace.

$DISTTAG is defined just as it is for RPMs, but since Dockerfiles lack a mechanism similar to RPM Macros this is being stored in the base image such that it can be inherited by layered images.

By following the pattern below, we can define the container specific information in one place on the ENV line and have it be set properly in the LABEL line (again, noting the $FGC and $DISTTAG being used but never defined as these are inherited).

FROM fedora:25
MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>

ENV NAME=myawesomecontainer VERSION=0.1 RELEASE=1 ARCH=x86_64
LABEL BZComponent="$NAME" \
        Name="$FGC/$NAME" \
        Version="$VERSION" \
        Release="$RELEASE.$DISTTAG" \
        Architecture="$ARCH"

CMD / ENTRYPOINT

Another item required is a CMD or ENTRYPOINT entry so that when an user were run perform the following command (for example), expected behavior occurs.:

docker run registry.fedoraproject.org/f25/myawesomecontainer

For more information on these entries, please reference the upstream Dockerfile documentation. The following is extending on the above example, showing a CMD directive.

FROM fedora:25
MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>

ENV NAME=myawesomecontainer VERSION=0.1 RELEASE=1 ARCH=x86_64
LABEL BZComponent="$NAME" \
        Name="$FGC/$NAME" \
        Version="$VERSION" \
        Release="$RELEASE.$DISTTAG" \
        Architecture="$ARCH"

CMD printf "My Awesome Container!\n"

Content

Dockerfiles in Fedora should not contain net new code. The meaning of this is that software should be packaged properly as RPMs and placed in the Fedora repositories, Dockerfiles are simply a deliver mechanism for pre-defined "ready to run" configurations. This can be achieved as an Atomic App or similar. Any content that is to accompany the Dockerfile must either be configuration files or startup/orchestration scripts. The goal of this is such that we follow the key points of the Fedora Release Engineering Philosophy.

Multi Container Services

Each container image should provide only one "service" and multi-container services should be handled by an external orchestration tool at the users discretion such as OpenShift Origin, kubernetes, deis, Docker Swarm, Docker Compose, DC/OS, Cloud Foundry, Apache Mesos, etc.

These types of multi-container services should be documented in such a way that users can adapt them to their needs. One example would be using the Project Atomic nulecule specification.

Important.png
Future
In the future there will be an user facing outlet such that this information can be index and searched so that it's easy for users to consume this content. Our long term Fedora Docker Registry goals are still in development

Discussion

For suggestions, feedback, or to report issues with this page please contact the Fedora Cloud SIG.

See Talk:PackagingDrafts/Containers for discussion.