diff --git a/docs/proposals/metadata.md b/docs/proposals/metadata.md new file mode 100644 index 000000000000..1b749f2f37d9 --- /dev/null +++ b/docs/proposals/metadata.md @@ -0,0 +1,172 @@ +# Image Metadata + +## Abstract + +A proposal for the additional metadata for Docker images which will provide more +context about the content of the image and define relations between Docker +images. + +## Motivation + +Image metadata are needed to do automatic generation of the OpenShift v3 +resource templates, like PodTemplates, ReplicationControllers, BuildConfigs +etc. Automatic generation of a PodTemplate is also required for +DeploymentConfigs. + +## Constraints and Assumptions + +This document only defines the metadata needed by the current set of use cases. +Additional metadata and/or use cases may be added in the future. + +The metadata should be set using the [LABEL](https://docs.docker.com/reference/builder/#label) +Docker instruction. + +Once the Docker image is built the metadata can be obtained by running the +`docker inspect` command. The metadata should be available in the `Labels` +section. + +For more default about conventions or guidelines about LABEL, visit: +https://docs.docker.com/userguide/labels-custom-metadata + +> The *LABEL* instruction is supported in Docker starting from the version +> 1.6.0. This instruction wont work on older Docker. + +## Use cases + +1. As an author of Docker image that is going to be consumed by the OpenShift + platform, I want to express what categories/tags my Docker image will belongs + to, so the platform then can then consume the tags to improve the generation + workflow based on them. + +2. As an user of OpenShift I want to get reliable suggestions about services + that the Docker image I'm going to use might require to operate properly. As + an author of the Docker image, I need to have a way to record what services my + Docker image want to consume. + +3. As an author of the Docker image, I need to have a way to indicate whether + the container started from my Docker image does not support scaling. + The UI should then communicate this information with the end consumers. + +4. As an author of the Docker image, I need to have a way to indicate what + additional service(s) my Docker image might need to work properly, so the UI + or generation tools can suggest them to the end users. + +## Namespaces + +The LABEL names should typically be namespaced. The namespace should be set +accordingly to reflect the project that is going to pick up the labels and use +them. For OpenShift the namespace should be set to `openshift.io/` and for +Kubernetes the namespace is `k8s.io/`. For simple labels, like `displayName` or +`description` there might be no namespace set if they end up as standard in +Docker. + +## Image Metadata + +Name | Type | Target Namespace | +------------------------------------|--------- | ------------------ +[`tags`](#tags) | []string | openshift.io +[`wants`](#wants) | []string | openshift.io +[`displayName`](#displayName) | string | k8s.io +[`description`](#displayName) | string | k8s.io +[`exposeServices`](#exposeServices) | []string | openshift.io +[`nonScale`](#nonScale) | bool | openshift.io +[`minCpu`](#minCpu) | bool | openshift.io(?) +[`minMemory`](#minMemory) | bool | openshift.io(?) + + +### `tags` + +This label contains a list of tags represented as list of comma separated string +values. The tags are the way to categorize the Docker images into broad areas of +functionality. Tags helps UI and generation tools to suggest relevant Docker +images during the application creation process. + +*Example:* + +``` +LABEL openshift.io/tags mongodb,mongodb24,nosql +``` + +### `wants` + +Specifies a list of tags that the generation tools and the UI might use to +provide relevant suggestions if you don't have the Docker images with given tags +already. +For example, if the Docker image wants 'mysql' and 'redis' and you don't have +the Docker image with 'redis' tag, then UI might suggest you to add this image +into your deployment. + +*Example:* + +``` +LABEL openshift.io/wants mongodb,redis +``` + +### `displayName` + +This label provides a human readable name of the Docker image. The Docker image +name might be complex and might be hard to display on the UI pages. This label +should contain short, human readable version of the Docker image name. + +*Example:* + +``` +LABEL k8s.io/displayName MySQL 5.5 Server +``` + +### `description` + +This label can be used to give the Docker image consumers more detailed +information about the service or functionality this image provides. The UI can +then use this description together with the Docker image name to provide more +human friendly information to end users. + +*Example:* + +``` +LABEL k8s.io/description The MySQL 5.5 Server with master-slave replication support +``` + +### `exposeServices` + +This label contains a list of service ports that match with the EXPOSE instructions +in the Dockerfile and provide more descriptive information about what actual service +on the given port provides to consumers. + +The format is `PORT[/PROTO]:NAME` where the `[PROTO]` part is optional +and it defaults to `tcp` if it is not specified. + +*Example:* + +``` +LABEL openshift.io/exposeServices 2020/udp:ftp,8080:http +``` + +### `nonScalable` (post-3.0) + +An image might use this variable to suggest that it does not support scaling. +The UI will then communicate this to consumers of that image. +Being not-scalable basically means that the value of 'replicas' should initially +not be set higher than 1. + +*Example:* + +``` +LABEL openshift.io/nonScalable true +``` + +### `minCpu` and `minMemory` (post-3.0) + +This label suggests how much resources the Docker image might need in order +to work properly. The UI might warn the user that deploying this Docker image +may exceed the user quota. + +The values must be compatible with [Kubernetes +quantity](https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/resources.md#resource-quantities) values for CPU and memory. + +Examples: + +``` +LABEL openshift.io/minMemory 8Gi +LABEL openshift.io/minCpu 4 +```