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 container images are not a new software packaging format but more so a delivery mechanism where many different things can 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. Fedora is targeting the any OCI Compliant container runtime implementation.
General Fedora Container Information
In this section you will find general information about Fedora Container Images that should be useful for Fedora Container Layered Image Maintainers.
Build System
In order to get a better understanding of the big picture of how all this works, Container Maintainers might find the Layered Image Build Service Architecture Document interesting. However, extensive coverage of the Build System is out of the scope of this Guidelines document.
Vocabulary Terms
- Container Registry - (often refereed to as simply a "registry") a service that stores and distributes Container Images via namespaces/repositories.
- Fedora Generational Core - defined by the Fedora Modularity effort as a part of the Base Runtime and will serve as our registry namespace. For all intents and purposes this will be a synonym of the Fedora Release. (Will often be noted as
$FGC)
Fedora Container Naming
A Fedora Container Layered Image name should be the same as the the name of main service that it intends to provide end users. Therefore, naming must follow the Fedora Naming Guidelines.
Container naming as it will exist in Fedora Package DB (and [Distgit http://pkgs.fedoraproject.org/cgit/docker]) should be relatively standard. None of the Fedora releases/DistGit-branch naming should be taken into consideration by the main container name, just as it is for RPM Package Naming.
Fedora content is now "namespaced" in both Fedora Package DB and DigtGit, with the default namespace being 'rpms' for backwards compatibility. This allows for Container Layered Images to share the same base component name as their RPM counterpart (where applicable).
Below is a reference of the Registry Layout which will clarify how different Fedora releases are handled.
Fedora Base Image
The Fedora Base Image provides information that can be used by the Layered Images via inherited Environment Variables.
These are outlined below:
$FGCis defined as Fedora Generational Core by the Fedora Modularity effort as a part of the Base Runtime and will serve as our registry namespace.$DISTTAGis 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.
Fedora Container Registries and Updates
In Fedora there are two Registries: candidate and stable.
All Layered Image Builds end up in the candidate registry as soon as they are successful in the Fedora Layered Image Build System. These images can immediately be pulled (example using docker: docker pull candidate-registry.fedoraproject.org/$FGC/$NAME:latest).
Gated releases will happen on a Two Week Cadence, alternating with the Fedora Two Week Atomic Host.
Registry Layout
Fedora Base Images will be available at the "root" namespace of the registry, an example is below:
https://candidate-registry.fedoraproject.org/fedora:24 https://candidate-registry.fedoraproject.org/fedora:25 https://candidate-registry.fedoraproject.org/fedora:latest https://registry.fedoraproject.org/fedora:24 https://registry.fedoraproject.org/fedora:25 https://registry.fedoraproject.org/fedora:latest
Fedora Layered Images will be available in their respective $FGC namespace which coorelates to their DistGit branch and Koji tag. An example is as follows for the f25 Fedora Generational Core and the cockpit container image.
There are multiple tags applied to each image:
$FGC/Name:Version-Release(including$DISTTAG)$FGC/Name:Version$FGC/Name:latest- The :latest tag can be omitted when issuing a
docker pullcommand.
- The :latest tag can be omitted when issuing a
The latter two tags are updated in-place and a new execution of docker pull will get the latest image.
https://candidate-registry.fedoraproject.org/f25/cockpit:0-1.f25docker https://candidate-registry.fedoraproject.org/f25/cockpit:0 https://candidate-registry.fedoraproject.org/f25/cockpit:latest https://registry.fedoraproject.org/f25/cockpit:0-1.f25docker https://registry.fedoraproject.org/f25/cockpit:0 https://registry.fedoraproject.org/f25/cockpit:latest
Searching the Registry
At the time of this writing there is no search functionality for the Container Registry but we will release a manifest of all available stable Fedora Layered Images in the Fedora Container Registry as Layered Images become available for release. We aim to change this in the future and provide search functionality to users.
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.
Containers (Dockerfile)
Container images in Fedora 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 Container images using a Dockerfile.
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 Layered 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) |
| Run or Usage | Either provides an Atomic Run line, or a human readable example of container execution |
| Help | Provides a detailed narrative of how the container is meant to be used. In many cases will be a link. |
Optional labels for Fedora Layered Images
| Name | Description |
|---|---|
| Install | Powers "atomic install" command. Usually required for system containers. |
| Uninstall | Powers "atomic uninstall" command. Required if Install is present. |
The LABELs used here are meant to be a Fedora adaptation of the upstream Project Atomic effort to define Container Application Generic Labels as well as Container Best Practices.
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 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
LABEL MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>
ENV NAME=myawesomecontainer VERSION=0 RELEASE=1 ARCH=x86_64
LABEL BZComponent="$NAME" \
Name="$FGC/$NAME" \
Version="$VERSION" \
Release="$RELEASE.$DISTTAG" \
Architecture="$ARCH"
VERSIONING
In the previous section there was coverage of LABELs, one of those is the Version that is set in the example using the ENV variable VERSION which at this time needs to be 0. Any changes made to the Dockerfile or the contents of the resulting image that would require a rebuild should increment the Release LABEL that is similarly set using the ENV variable named RELEASE. The reasoning for this is described below.
At this time there is no way to automatically populate the Version/VERSION value with the same value of the latest version of the primary RPM belonging to the container image. This is something that is currently on the roadmap.
Why is this needed?
If we set the Version LABEL to the version of it's respective RPM at the time of the Container Image Review, then the maintainer will constantly have to update it by hand every time there is a RPM update which is inconvenient and error prone. Beyond that, there's a possibility that the version of the RPM could be updated by the layered image automatic rebuilds and the maintainer isn't able to update the Dockerfile in a timely manner (Automatic Rebuilds are done by Release Engineering in order to pull in security updates for all layered images). If this were to happen, then the version of the container image will not match the version of the software it's meant to deliver which would lead to confusion and potentially unexpected negative side effects for users. Therefore, for the time being we're saying that the version number of the container is not meaningful but it will be as soon as possible.
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
LABEL MAINTAINER "Adam Miller" <maxamillion@fedoraproject.org>
ENV NAME=myawesomecontainer VERSION=0 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.
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 Container 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.