Folks,
Looking at the new FDLIBS, I'm noticing that there's not a narrative description of the image required or provided anywhere that I can find. Clearly one is needed for users. So, here's a proposal:
New Required LABELs:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
DESCRIPTION: Narrative description incuding: * What service/software it provides * What specific purpose it fulfills, if required * Notes on how to use it, if not covered by USAGE, such as how to supply configuration files * Depedencies on other images (e.g. "requires a database") * Links to documentation for the Software, if any
*Bump*
Sans feedback, I'm going to assume that everyone approves of this pretty soon ...
On 12/13/2016 01:24 PM, Josh Berkus wrote:
Folks,
Looking at the new FDLIBS, I'm noticing that there's not a narrative description of the image required or provided anywhere that I can find. Clearly one is needed for users. So, here's a proposal:
New Required LABELs:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
DESCRIPTION: Narrative description incuding: * What service/software it provides * What specific purpose it fulfills, if required * Notes on how to use it, if not covered by USAGE, such as how to supply configuration files * Depedencies on other images (e.g. "requires a database") * Links to documentation for the Software, if any
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
Why N/A? What circumstances would this be?
On 01/10/2017 10:41 AM, Matthew Miller wrote:
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
Why N/A? What circumstances would this be?
CNI Networking container for Kubernetes, for example. A bunch of "infra" containers only get invoked by other containers and/or the orchestration system.
On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
Why N/A? What circumstances would this be?
CNI Networking container for Kubernetes, for example. A bunch of "infra" containers only get invoked by other containers and/or the orchestration system.
Could we develop standard wording for that? Like
USAGE: Invoked by $OTHERCONTAINER
or
USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
or are there too many possibilities?
On 01/10/2017 10:52 AM, Matthew Miller wrote:
On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
Why N/A? What circumstances would this be?
CNI Networking container for Kubernetes, for example. A bunch of "infra" containers only get invoked by other containers and/or the orchestration system.
Could we develop standard wording for that? Like
USAGE: Invoked by $OTHERCONTAINER
or
USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
or are there too many possibilities?
I don't think there are. I'd suggest:
---------------
USAGE: Invoked by $SOMEPROCESS. Not for direct use.
"$SOMEPROCESS" should be the name of the infrastructure tool, container, or other utility which consumes this container.
---------------
On Tue, Jan 10, 2017 at 1:47 PM, Josh Berkus jberkus@redhat.com wrote:
On 01/10/2017 10:52 AM, Matthew Miller wrote:
On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
Why N/A? What circumstances would this be?
CNI Networking container for Kubernetes, for example. A bunch of "infra" containers only get invoked by other containers and/or the orchestration system.
Could we develop standard wording for that? Like
USAGE: Invoked by $OTHERCONTAINER
or
USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
or are there too many possibilities?
I don't think there are. I'd suggest:
USAGE: Invoked by $SOMEPROCESS. Not for direct use.
"$SOMEPROCESS" should be the name of the infrastructure tool, container, or other utility which consumes this container.
+1 - I like that idea, makes it very clear to the user.
-AdamM
--
Josh Berkus Project Atomic Red Hat OSAS _______________________________________________ cloud mailing list -- cloud@lists.fedoraproject.org To unsubscribe send an email to cloud-leave@lists.fedoraproject.org
On Jan 10, 2017 15:17, "Adam Miller" maxamillion@fedoraproject.org wrote:
On Tue, Jan 10, 2017 at 1:47 PM, Josh Berkus jberkus@redhat.com wrote:
On 01/10/2017 10:52 AM, Matthew Miller wrote:
On Tue, Jan 10, 2017 at 10:44:03AM -0800, Josh Berkus wrote:
On Tue, Jan 10, 2017 at 10:33:05AM -0800, Josh Berkus wrote:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers.
Why N/A? What circumstances would this be?
CNI Networking container for Kubernetes, for example. A bunch of "infra" containers only get invoked by other containers and/or the orchestration system.
Could we develop standard wording for that? Like
USAGE: Invoked by $OTHERCONTAINER
or
USAGE: Invoked by Kubernetes when $WHATEVERTRIGGERS
or are there too many possibilities?
I don't think there are. I'd suggest:
USAGE: Invoked by $SOMEPROCESS. Not for direct use.
"$SOMEPROCESS" should be the name of the infrastructure tool, container, or other utility which consumes this container.
+1 - I like that idea, makes it very clear to the user.
-AdamM
I disagree that the usage should be limited to "used by another container". Even though that is the intended use, the usage description should be uniform and state what capability or function is provided.
Actual usage pattern for code is always more interesting than intended use.
On Wed, Jan 11, 2017 at 08:12:53AM -0500, Subhendu Ghosh wrote:
I disagree that the usage should be limited to "used by another container".
To be clear, I'm only suggesting that when it is meant to be used in that way, and as more helpful than N/A. This line is meant to be a brief statement....
Even though that is the intended use, the usage description should be uniform and state what capability or function is provided. Actual usage pattern for code is always more interesting than intended use.
... and doesn't the "description" cover that detail?
On Tue, Dec 13, 2016 at 3:24 PM, Josh Berkus jberkus@redhat.com wrote:
Folks,
Looking at the new FDLIBS, I'm noticing that there's not a narrative description of the image required or provided anywhere that I can find. Clearly one is needed for users. So, here's a proposal:
New Required LABELs:
USAGE: single command line giving usage example for invoking the container; will be "N/A" for some containers. DESCRIPTION: Narrative description incuding: * What service/software it provides * What specific purpose it fulfills, if required * Notes on how to use it, if not covered by USAGE, such as how to supply configuration files * Depedencies on other images (e.g. "requires a database") * Links to documentation for the Software, if any
+1 - I like this, it follows nicely with the upstream guidelines[0] referenced in Fedora's that I'd like to further adopt as all of this evolves in Fedora space.
I'd also at some point like to discuss the labels needed for atomic app install/uninstall and OpenShift guidelines[1] that we should at least provide information on how to offer the 'atomic install' and OpenShift deployment functionality for a container to users.
-AdamM
[0] - https://github.com/projectatomic/ContainerApplicationGenericLabels [1] - https://docs.openshift.org/latest/creating_images/guidelines.html#openshift-...
--
Josh Berkus Project Atomic Red Hat OSAS _______________________________________________ cloud mailing list -- cloud@lists.fedoraproject.org To unsubscribe send an email to cloud-leave@lists.fedoraproject.org
On Tue, Jan 10, 2017 at 12:40:27PM -0600, Adam Miller wrote:
+1 - I like this, it follows nicely with the upstream guidelines[0] referenced in Fedora's that I'd like to further adopt as all of this evolves in Fedora space.
I see that these guidelines use all lower case; we should probably follow a consistent convention.
Also, looks like instead of "usage", that recommends:
help Command to run the help command of the image run Command to run the image