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. 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.
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, and images intended to ONLY be ran as a system container will have the label atomic.type='system'
- 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