Container Policy VFAD
This VFAD was convened in order to clear out a queue of unresolved questions about the Fedora Layered Image Build System (FLIBS) [Container:Guidelines|Container Guidelines]. This included several different issues which arose around reviewing some of the early container submissions.
What follows is a summary of all of the decisions made at the VFAD, which will be implemented through container guidelines changes in the next week. For full discussion, see the Notes below.
Decisions
The INSTALL and UNINSTALL labels are optional. They are only recommended if the container needs some kind of setup beyond "pull". System containers probably always need them. If an INSTALL is supplied, and UNINSTALL should be as well. Both of these labels should work, and should be tested using the Atomic CLI. Guidelines for Install/Uninstall will be included, but mostly point to the Atomic CLI docs.
Either USAGE or RUN is required. RUN is for the Atomic CLI, which submitters are not required to use. If they choose to submit using RUN, (a) it must actually work, and (b) USAGE is not required. If the maintainer does not use RUN, they must submit USAGE instead, which is a human-readable sample command.
The VERSION label and tag will be populated with a "0" until such time as it can be automatically populated based on the "primary" RPM in the container. The RELEASE will be incremented both by the maintainer on any manual change to the package, and by the autobuilder on autobuild.
The HELP label will link to a verbose description of how to use the container. For containers needing substantial instructions, the maintainer will check a file into dist-git called "help1.txt", "README" or "README.md". Fedora will ensure that this file has a public link. The maintainer will also have a copy of that file in the root directory of the container. For such images, the maintainer may choose to populate the HELP label with a URL pointing to the dist-git file, but is encouraged to have a one-sentence description before the URL.
Maintainers will be required to explicitly declare all required Volumes in the Dockerfile. RUN/USAGE should contain examples of mounting the volumes. HELP should contain a verbose description of each Volume and what its requirements are.
systemd images (images where PID1 is systemd) are permitted, if the complexity of the container makes it a good idea.
The Guidelines will contain examples of image specifications for system containers. Any image which is intended to be a system container will contain a note to that effect in HELP, and will have a RUN line.
Action Items
- Josh Berkus to write RUN/USAGE guidelines
- Dusty to write INSTALL/UNINSTALL guidelines
- Jerry Zhang to draft guideline paragraph on System Containers
- James to write up the HELP guildelines with Josh
- Tomas to follow up on changes to "atomic help" to support the new HELP guidelines
- James to write guidelines for Volumes
- Jason and Dan Walsh to write guidelines and example for systemd containers.
- Dusty to open issue to set CONTAINER environment variable to "oci" in the Fedora base image
- Jerry to write a general HOWTO tutorial for building a container according to the guidelines.
- Jason will help with systemd container example for the HOWTO.
Notes from 2017-03-10 VFAD, covering Container Policy
Original Etherpad here: https://public.etherpad-mozilla.org/p/20170310-FedoraAtomicWGFVAD
Notes in case Etherpad is lost:
Welcome to the 2nd Virtual Fedora Activity Day for VFAD for the Fedora Atomic WG.
Attendees: dustymabe, roshi, jberkus, kushal, maxamillion, trishnag, jbrooks, ttomecek, jantill, yzhang, mkocka, goern, jhogarth, dwalsh
Fedora Container Guidelines are here: https://fedoraproject.org/wiki/Container:Guidelines
Project Atomic Upstream Container Best Practices are in: http://docs.projectatomic.io/container-best-practices/
Atomic CLI: https://github.com/projectatomic/atomic
Need to merge Atomic CLI docs -- copy into there by now?
10:00 - 10:45 RUN, INSTALL, UNINSTALL (Issues #242 and #244)
- https://pagure.io/atomic-wg/issue/242
- https://pagure.io/atomic-wg/issue/244
http://www.projectatomic.io/docs/usr-bin-atomic/
These LABELs are targeting the atomic cli which is important to Fedora Atomic Host in order to be able to target "system containers" (which will allow us to remove kubernetes from the base ostree).
Dockerfiles should be self-documented about the implications of these LABELs (or at least a link/ref to Fedora Container Guidelines)
INSTALL UNINSTALL are OPTIONAL
INSTALL
Optional or required?
AGREED: Should be optional, only recommended if the container needs some action beyond "pull image"
should point to a script inside the image
Should also explain that this LABEL is specific for the atomic cli and won't be meaningful to a "vanilla" docker/rkt client
Need command examples
Need brief overview for why you would want to do this (for people new to atomic)
Guidelines on what is "allowed" vs "restrictions"
Allowed:
Can easily pull this from the atomic-cli docs
Restrictions:
scripts should be as simple as possible
scripts must run without error
Testing of INSTALL command?
UNINSTALL
if there is an INSTALL there should probably be an UNINSTALL
container removal should "clean up"
exceptions: not required to delete directories including user files
surely there's RPM guidelines on this?
what about configuration files?
removal
YES remove systemd unit files
NO removing user files (/var/lib/httpd)
??? Configuration files
Yes if NOT MODIFIED from original content at install time (no change in checksum of file detected)
No if MODIFIED from original content at install time (change in checksum of file detected)
Partial RPM stuff (WIP) will replace a lot of this.
RUN
Label should only exist in the event that the container maintainer intends for the container to be used with the 'atomic run' command
Otherwise, USAGE is required with an example therein
USAGE
Example/doc of how to run/use this particular container
Might be useful to target the Atomic help file -> http://docs.projectatomic.io/container-best-practices/#_creating_a_help_file
AGREED:
either USAGE or RUN is required
RUN if it works with Atomic Run
AGREED GUIDELINES for INSTALL/UNINSTALL: point to /usr/bin/atomic docs and also supply short description that are loose guidelines for what to do on INSTALL/UNINSTALL.
Action Items:
Josh to Follow Up on RUN
Dusty to follow up on INSTALL/UNINSTALL
Jerry Zhang to draft guideline section on System Containers.
10:45 - 11:30 Version/Release (Issue #235)
https://pagure.io/atomic-wg/issue/235
Typically, a RPM has a very specific git ref that correlates to a N-V-R, this is not the case in container land.
For Containers, is the release the release of the "container" as an entity or of the rpm that's the primary version of the container?
VERSION: the version of the *primary* RPM package in the container (the one the "user") cares about.
But we can't do that because Automatic Rebuild
And don't have any way to automatically pull the version out of the RPM
So might get out-of-sync
RELEASE: the release of the container itself (usually "1")
The labels are requirement for koji. And for the registry. Really, we need them.
Versions for Release Candidates today (for example):
"query_data.rclist": [
"f25/cockpit:130-1.4.f25docker",
"f25/cockpit:130",
"f25/cockpit",
"f25/kubernetes-node:0.1-3.f25docker",
"f25/kubernetes-node:0.1",
"f25/kubernetes-node",
"f25/kubernetes-controller-manager:0.1-3.f25docker",
"f25/kubernetes-controller-manager:0.1",
"f25/kubernetes-controller-manager",
"f25/mariadb:10.1-2.f25docker",
"f25/mariadb:10.1",
"f25/mariadb",
"f25/kubernetes-apiserver:0.1-3.f25docker",
"f25/kubernetes-apiserver:0.1",
"f25/kubernetes-apiserver",
"f25/kubernetes:0.1-2.f25docker",
"f25/kubernetes:0.1",
"f25/kubernetes",
"f25/kubernetes-scheduler:0.1-4.f25docker",
"f25/kubernetes-scheduler:0.1",
"f25/kubernetes-scheduler",
"f25/kubernetes-master:0.1-5.f25docker",
"f25/kubernetes-master:0.1",
"f25/kubernetes-master",
"f25/s2i-base:1-2.f25docker",
"f25/s2i-base:1",
"f25/s2i-base",
"f25/kubernetes-kubelet:0.1-3.f25docker",
"f25/kubernetes-kubelet:0.1",
"f25/kubernetes-kubelet",
"f25/flannel:0.1-3.f25docker",
"f25/flannel:0.1",
"f25/flannel",
"f25/kubernetes-proxy:0.1-3.f25docker",
"f25/kubernetes-proxy:0.1",
"f25/kubernetes-proxy",
"f25/etcd:0.1-5.f25docker",
"f25/etcd:0.1",
"f25/etcd",
"f25/toolchain:1-2.f25docker",
"f25/toolchain:1",
"f25/toolchain"
AGREED: Decision: To use Version 0 until we have an automated solution
Only increment the Release Number
Remember to pull from git before incrementing the release number
Action Items:
Adam to follow up on "can the build system automatically set the Version for the container label?"
Can this be done with defining a "macro language" for Dockerfiles?
Adam and Jason to write para including Version 0 rule
ISSUE: this decision requires that all container definition changes be backwards-compatible. Discuss?
11:30 - 12:00 DESCRIPTION (Issue #243)
Issue: https://pagure.io/atomic-wg/issue/243
"HELP" as well
Proposal:
Require narrative description
Label called HELP
Requirements in issue 243
Also in file help1.txt in root of container
Questions about help file vs Label
File could be really long
AGREED: Have a file with the full verbose description in dist-git
Have a public link to that file
For the LABEL have a link to that public URL
File will be copied to help1.txt in the container (or README?)
If there are other labels containing the same information, these labels need to be added by a conversion step (not the maintainer) and content needs to be copied from the DESCRIPTION label.
Action:
* James to write up guidelines for the agreed guideline (with Josh)
* Tomas to follow up on requested changes (pick up README/help1.txt, have it supercede the label)
Contents:
This would include, for all containers:
what service/software the container provides
It would also include all of the following which are applicable to the container:
what purpose it fulfills in a larger infrastructure
what each VOLUME in the container is for and what kinds of storage they need
any details about dependencies on other container images
links to documentation or software project pages
any special requirements the container has (like lots of RAM, or sound server access)
details on any required configuration, or links to documentation on configuration
13:00 - 13:30 Volumes (Issue #234)
https://pagure.io/atomic-wg/issue/234
AGREED
We should REQUIRE maintainers to declare all expected volumes
RUN/USAGE should contain volume examples
HELP should have details of the volumes required
Action:
James to write guideline for this
13:30 - 14:00 Overage
14:00 - 14:45 Systemd containers (Issue #233) (will try to recruit Dan Walsh)
Issue: https://pagure.io/atomic-wg/issue/233
1. Do we want to accept systemd containers? YES
but only if needed (multi-service, reaping issue, pruning, etc.)
AGREED: REQUIRE note in HELP and RUN/USAGE example which includes systemd requirements
Options:
docker run -ti --tmpfs /run -v /sys/fs/cgroup:/sys/fs/cgroup IMAGE ...
Or
install oci-systemd-hook and use default docker package
docker run -ti IMAGE ...
Fedora base image to set CONTAINER=oci? Update base image?
or do we want a fedora-init base image?
three images: microdnf, regular, systemd(init)
this is future
Action:
Jason and Dan Walsh to write guidelines for SystemD containers
Dusty to open issue to set CONTAINER=oci in Fedora base image
Other Business
System Containers
Jerry to write general guidelines
Need HOWTO doc to link to
Action:
Jerry to write para in guidelines
Action:
Mike to write HOWTO for writing a container following the guildelines
Jerry will help with systemcontainer part
Jason to help with systemd container howto