Atomic/VFAD 20170310

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.

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

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