projectatomic / containerapplicationgenericlabels

Default Containerized Application Labels used to document the application and/or image

Standard Container/Application Identifiers

Default Containerized Application Labels/Annotations/Ids used to document the application and/or image

With the introduction of the Atomic command, we are accessing container image meta data to describe the purpose of the image or the application defined by the image.

We would like to get consensus on default names. Proposals have been made to namespace the label names defined in Docker.

But we believe there should be some generic toplevel names defined that are not vendor specific, or distribution specific.

If you would like to see additional names and descriptions added please open issues and send pull requests to update this readme.

Overview

The following types of data are being considered:

1. Labels used to describe how to use the application/image

Name	Description
help	Command to run the help command of the image
run	Command to run the image
run_opts_file	Path to a file containing options that will be used in 'run' command in place of ${RUN_OPTS}
uninstall	Command to uninstall the image
install	Command to install the image
stop	Command to execute before stopping container
debug	Command to run the image with debugging turned on

2. Labels Names used to describe the application/image

Name	Description
name	Name of the Image
version	Version of the image
release	Release Number for this version
architecture	Architecture for the image
build-date	Date/Time image was built as RFC 3339 date-time
vendor	Owner of the image
url	Url with more information on the image
summary	Short Description of the image
description	Detailed description of the image
vcs-type	The type of version control used by the container source. Generally one of git, hg, svn, bzr, cvs
vcs-url	URL of the version control repository
vcs-ref	A 'reference' within the version control repository; e.g. a git commit, or a subversion branch
authoritative-source-url	The authoritative location in which the image is published
distribution-scope	Intended scope of distribution for image (see below for possible values)
changelog-url	URL of a page containing release notes for the image

3. Possible values of distribution-scope field

Name	Description
private	No public redistribution intended
authoritative-source-only	Redistribution only from the source listed in the 'authoritative-source-url' label
restricted	Redistribution only with permission
public	No redistribution limits beyond licenses

4. Custom labels may be defined by a namespace prefix using reverse DNS notation of a domain controlled by the author. For example, com.redhat.access.

    LABEL io.openshift.expose-services="8080:http" \
          io.openshift.tags="builder,nodejs,nodejs010"
   

Details on Labels

authoritative-source-url

• The authoritative location the image is published by the owner.
• In combination with the 'name' label, this tells a user where to go and look for official updates and current versions of the image, regardless of the local tags.

distribution-scope

• The intended scope of distribution for the image.
• Allows a user to define the intended scope of distribution. This addresses the end-user case of internal builds vs. public content and the use case of a vendor like Red Hat that provides content streams under subscription agreements - which is different from the license(s) of the image content.
• In combination with the 'authoritative-source-url' and 'name' labels allows automatic redirect to the authoritative source.

Signing Server Metadata "sigstore" Image

Signing server metadata may be served by a special image in a repository. The image shall be named "sigstore" and contain the following labels, all required:

Name	Description
sigstore-url	The signature server URL, including port
sigstore-type	Signature server type, either "docker" (static web server) or "atomic" (Atomic Registry and OpenShift API)
pubkey-id	The public key ID in the form of an email address
pubkey-fingerprint	The public key fingerprint, typically a long hexidecimal string
pubkey-url	The URL to download the public key

Example Dockerfile:

FROM scratch
LABEL sigstore-url="sigstore.example.com:8443" \
      sigstore-type="docker" \
      pubkey-id="[email protected]" \
      pubkey-fingerprint="B3B04F8CF186436EF8F1CDAD7C6ACC9EE3A31016" \
      pubkey-url="https://pgp.mit.edu/pks/lookup?op=get&search=0xFD5EB4DB480717ED"

containerapplicationgenericlabels's Issues

"com.example.webserver.memory.max" is maybe a bad example

The spec includes the following example:

Sample Name	Sample Description
com.example.webserver.memory.max	Maximum memory setting for "example.com" organization's webserver
com.example.webserver.memory.min	Minimum memory setting for "example.com" organization's webserver

I am not sure if this is a bad example or if I don't understand the idea behind it. If I were building a webserver image, I would not apply a label called "something.webserver.memory.max". I would just apply a "memory.max" label, and it would be for the webserver because that is the image to which it is applied. There wouldn't be any need to encode this fact in the name of the label.

If the idea here is that an organization might want to namespace labels because they want to avoid conflicts with labels used at other organizations that makes sense, but using com.example.memory.max and com.example.memory.min might better illustrate the idea (because here namespacing is used exclusively as an organizational differentiator).

Reason to have "name" label?

What is the reason to have the name label if it matches with the image name? Both OS and Kubernetes have display-name label which provides more information in human-readable form about the image content. For example: https://github.com/openshift/sti-ruby/blob/master/2.2/Dockerfile#L13

The problem with labels

See:

projectatomic/atomic#43

We should likely move that issue here.

Support for Intents

Having a set of labels be available to support intents as described in moby/moby#11187.

Do we have to worry about datatypes for labels? - string vs json blob?

Define standard for vendor-specific Labels

Based on some of the discussions on this proposal and subsequent pull requests, there appear to be some use cases for labels that are too specific to try to standardize (e.g. this came up in the authoritative_source and distribution_scope context).

We should define a standard for naming vendor-specific labels.

Include missing OpenShift labels e.g. wants

There are some nice existing OpenShift labels which are missing: https://docs.openshift.com/enterprise/3.0/creating_images/metadata.html

aint there a STOP label?

I havent seen it on the list...

Support for different containerization tools/formats

Hi, I'd like to have a way of describing that an image is not a docker image, but e.g. rkt. My use case is [1], where I want to be able to express that a Nulecule application doesn't necessarily consist exclusively of Docker images.

[1] https://github.com/bkabrda/nulecule-images/

Describe optional and required environment variables

Describing environment variables shouldn't be exclusive to the nulecule spec https://github.com/projectatomic/ContainerApplicationGenericLabels/blob/master/vendor/projectatomic/labels.md

install/uninstall commands use cases?

I am rather concerned about the current format of the install/uninstall commands as described in the atomic command. As implemented currently it relies on the host OS having a particular runtime available and then gives a script in the container access to the full host root and says "good luck".

Make script runtime/host agnostic

To fix this first concern perhaps have this label spec that there be a defined API on what sort of environment the "install executable" can expect to be operating in, for example having a /media/host-root mount point, etc. Then the container doesn't need to expect any details about the host and instead the relies on the host to create the correct environment.

Re-evaluate using a script

That said, I think that this whole install/uninstall thing is going to get us into a rather crazy place where containers are going to have to know what type of Linux it is installing to. Instead we could say what are the sorts of things we will need to configure and make them explicit.

For example in the install script in the blog post the command only does a handful of things:

• Puts down some configuration files via templates
• Enables the systemd unit file

Perhaps instead the container should describe those configuration files as metadata and the installer command should pick/choose the files that are appropriate for the host? So there would be a freedesktop.org/systemd/unit-template="[Service]... label or perhaps a label that is template-linux-host-configuration-dir=/usr/share/app-host-template.

I propose this because I am a bit skeptical that the API should be defined as a executable running over the root. That seems likely to take us back to a place where every upstream needs to worry about the finicky details of the host OS.

vendor/red hat page is harder to read than top-level (tables)

The red hat vendor page does not list labels in tabular format, as the top-level page does, and as a consequence is far harder to read. It would be good to normalise on either consistently using tables or not, with my preference being the former.

Label for Syscall Tables

What about having a label for syscall (system call) tables. Imagine that I want to verify that the user space packaged up in the container image can run on a given container host?

For example, what about verifying that a Fedora 22 container image can or can't run on a Fedora 18 container host?

A label for changelog

Hi,
I'm now working on a way how to put changelog information to OpenShift Xpaas JBoss MW images and I'd like to see some more standard way to attach some release notes/changelog to an image even for regular container application.

Ideally it should be two labels like:

Name	Description
changelog	a brief release notes/description whats new in image
changelog_url	url to a webpage containing description of all new shiny stuff

maintainer instruction is deprecated as of docker engine 1.13

We should introduce a substitution for MAINTAINER instruction:

moby/moby#25466

What would it be? maintainer, contact, upstream?

label capitalization style?

In each section the label capitalization is different, between all caps, CamelCase and lower case. I would suggest that we just standardize on lowercase as it is common for things like urls, programming language variable names, etc.

LABEL semantics on layered images.

May want to denote LABEL semantics on layered images.

e.g. - latest label overrides..? etc.

What is the right LABEL name for authoritative source?

Is it authoritative-source or authoritative-source-url?

authoritative-source shouldn't be required for images located on docker hub

I'm thinking what authoritative-source label should be for images that are located on Docker Hub at https://github.com/projectatomic/ContainerApplicationGenericLabels/blob/master/vendor/redhat/labels.md.

If authoritative-source is only meant to be able to reconstruct the docker pull ... command, if authoritative-source is empty, then it results in correct docker pull ... command in case of docker hub hosted images. So, for those images the label authoritative-source shouldn't be required.

Use dash case instead of underscore in label names

Are there any reasons why the labels are authoritative_source and not authoritative-source ? Kubernetes and OpenShift labels seems to both follow the foo-bar case. Also the Docker upstream promote the "dash" case: https://docs.docker.com/userguide/labels-custom-metadata/

Image name that includes string '--' not acceptable in docker 1.8+

Per vendor/redhat/names.md we accept '--' in the build image name. This causes a failure in docker v1.8+.

$ rpm -q docker
docker-1.8.1-3.git32b8b25.fc22.x86_64
$ cat /etc/redhat-release 
Fedora release 22 (Twenty Two)
$ sudo docker build -t test/atomicapp--name .
repository name component must match "[a-z0-9]+(?:[._-][a-z0-9]+)*"
$ sudo docker build -t test/atomicapp-name .
Sending build context to Docker daemon  2.08 MB
Step 0 : FROM centos:centos7
...

Add label to qualify production grade of image

Many products we want to put into images - as well as images as an entity themselves usually go through a pre-production lifecycle from experimental over beta, tech-preview, to production ready. Some are development-only or community editions vs fully supported. It would be helpful to have the ability to describe this in metadata.

drop authoritative-source-url label

Please drop the authoritative-source-url label from the specification:

• It is easy for this to become stale over time as organizations rename their public-facing registries.
• This label cannot support multiple registries.
• It has never been authoritative from the point of view of trust. It's easy for anyone to forge the value, and we should encourage container users to authenticate their images with cryptographic means instead.

Proposal: add a Build label

I would like to propose a Build label that contains a hint how to build the docker image. This label will carry some free text.

Example:

# Dockerfile
LABEL Build docker build --rm --tag myimage .

and a bash alias docker-build='$(grep LABEL Dockerfile | grep Build | cut -d " " -f 3- )'

License label

Can the image have a license? I feel like this is pretty problematic when most images are composed of multiple pieces of various software with different licenses.

Proposal: Add a License Label

I would like to propose a License label that contains license information about the image. It will carry string containing license information. Could be simply the name of the license (GPLv2.1), or a comma separated list of several different licenses (GPLv2.1, Apache-2.0). License Names should be the short name from the osi.

All images should contain a License Label to easy use of containers for compliance and governance sensitive organizations.

Add a standard for classifying containers

In practice there are different kinds of container images:

• Basic bootstrap such as a base image and runtimes such JBoss EAP, Python, etc. These images are meant for building upon.
• There are individual service components such as e.g. a mariadb image delivered by an ISV, or a db-cluster atomic-app image. These are meant to be aggregated into applications, but by themselves usually would not be modified beyond parameterization.
• We have top-level applications, that just will be parameterized and the run - e.g. a containerized delivery of Kolab. Could be a single, multi-service container for an existing enterprise app or a full atomic-app. These ususally will just be installed, parameterized and run.
• There sometimes are containers that are simply 'hidden' components of something else - e.g. a component of an atomic-app or something like the openshift pod container, that is not useful on it's own and would only be used when pulled in by something else.

It would be a good thing to capture this classification in the meta-data to e.g. be able to filter search on it.

Use cases for container configuration?

There are two examples of using these labels for container configuration? I sort of get the use case for the min memory label but max memory doesn't seem like a realistic concern.

Can whoever wrote the container configuration section explain a few more use cases of what this might be used for?

Also, why are the container that it is formatted as a reverse DNS oid even though these labels are presumably scoped to a single image?

Clarify relation to opencontainers/image-spec

https://github.com/opencontainers/image-spec/blob/master/annotations.md

image source repository and related metadata

Hi, I wonder if there is any interest in labelling images with metadata relating to the source code repository from which it was built. Since with docker images the Dockerfile is only one piece of the puzzle (and other scripts or artifacts might be ADDed in, RUN, etc.) and typically these are collected together in a version control repository, to find out precisely what was used to build an image, one may need to refer to the repository and to a specific commit within.

So it might be useful to label with at least the commit-id, but probably also a repository URL, and if it can't be inferred from the URL, a repository type.

Why are labels io.k8s.display-name and io.openshift.tags required?

The document states that these two labels are required:

• io.k8s.display-name (Name of the container displayed in Kubernetes)
• io.openshift.tags (tags used by searching engine, e.g. "builder,php,php56,rh-php56")

Is that true? Why are those being enforced?

document "usage" label?

The "usage" label has recently turned up in rhel75 images:

            "usage": "This image is very generic and does not serve a single use case. Use it as a base to build your own images.",

This caught us by surprise because we hadn't heard of this label before. I wonder whether, if it's going to be used across a bunch of RH images, it ought to be described in this spec.

Add vendor links in the main readme

I've totally missed the /vendor folder. Links should be included in the main readme.

Vendor vs Maintainer vs ???

Docker images have a "maintainer" field, and this spec introduces a "Vendor" label. What's the difference? Is one an individual while one is an organization? Should it be an email address, a URL, or is the format unspecified?

Missing help label description

The help label is used by atomic, but is not documented in this repository. IMO it also caused the issue tracked in https://pagure.io/atomic-wg/issue/267, which was also reported to projectatomic/atomic#967.
Once the dilemma is resolved, we should document this label properly here.

Define a set of Red Hat supported labels

When I open this document I am confused with what labels will Red Hat images have. There are two sets, Naming and versioning related and Other labels: some of the labels are required, some are optional, some does not specify anything.

What labels should users of Red Hat images expect?

@riekrh @aweiteka @rhatdan

Labels "Build {Date,Host}"

I feel like having whitespace in the name might cause troubles.

Current keys in metadata use camelcase. I would prefer being consistent.

`authoritative_source_url` and `authoritative_source`

Are those the same thing? Or is one an url (of registry's fronted) and the other registry URI to use with pull?

Proposal: add TEST label

The purpose of the TEST label is for the image authors to be able to specify a self-contained check to figure out whether the image can run correctly on the given host.

Use case:

FROM fedora:22
LABEL TEST='sh -c "([ -c /dev/kvm ] && [ \"$(stat -c \"%a\" /dev/kvm)\" -eq "666\" ]) || (echo \"Bad KVM device\"; exit 1)"'

$ atomic test my-kvm-image
ERROR: Bad KVM device