WIP: Initial Image Metadata proposal

docs/proposals/metadata.md

@@ -0,0 +1,153 @@
+# 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 a PodTemplates, ReplicationControllers, BuildConfigs
+and other.  Automatic generation of PodTemplate is also required for
+Deployments.
+
+## Constraints and Assumptions
+
+For the time being, there is no good way how to define metadata for Docker
+images other than specifying extra environment variables. There is an upstream
+work currently being done to fix this situlation and we should switch to that in
+the implementation in the future.
+
+We also assume that there might be more use-cases and metadata define for images
+that helps with generation stuff, this document only provides those needed in
+the short-term.
+
+## Use cases
+
+1. As an author of the Docker image, I want to specify a flag that will tell
+   whether the image I build can be used as an STI image builder, so that when
+   somebody use my image in OpenShift v3 the BuildConfig generated for this image
+   will default the build strategy to STI. For this, I only need to specify if my
+   entrypoint accepts a 'tar' stream that contains the application as an input.
+
+2. As an author of the Docker image, I want to specify list of services that the
+   image I'm building will provide, so in OpenShift v3 we can automatically
+   setup Routes, Services and health-checks for this image. For example, in case
+   I'm building 'mysql' image, I can specify `PUBLISHES=mysql/tcp/3128` so when
+   the image is deployed, we automatically setup a Service for it, add health-check
+   for 'mysql' service type and wire the Route for the 3128 port.
+
+3. As an user of OpenShift v3 I want to be able to say what services my
+   application will consume, so the platform can find the corresponding Docker
+   images and make the services available for my application.
+   For example, as an user I can say I want to have 'mysql' service available in
+   my application, so the platform will check the ImageRepositories for the
+   Image that have `PUBLISHES="mysql/tcp/3128"` and add it to my deployment.
+
+4. As an author of the Docker image, I want to specify what _secrets_ the image
+   I'm building require, so I can consume them in the Image.
+   For example I can specify `SECRETS=api/twitter` that should tell the platform
+   to lookup for the 'api/twitter' secret and make it available inside the
+   Image.
+
+5. As an author of the Docker image, I need to have a way to disable
+   'clustering' for my Image, in case the Docker image does not support this.
+   In other words, if the Docker image specify this, the ReplicationController
+   generated for this Image should never get `replicas` set higher than 1.
+
+## The list of proposed metadata
+
+### ACCEPT_TAR_STREAM
+
+If this variable is set, then the BuildConfig generated for this Docker image
+will default the build strategy to 'STI'. The Docker image entrypoint is
+expected to support the 'tar' input stream with the application.
+
+### PUBLISHES
+
+This variable contains a list of services that the Docker image publishes. The
+service is described as `<name>/PROTO/PORT` (eg. `mysql/tcp/3128`) where the
+'PROTO' part is optional and default to 'tcp'.
+
+When the platform consumes this Docker image, it should automatically setup
+Service(s) with given name and port, the Route should be created for this
+service and the health-check should be generated for the ReplicationController
+that implements this Service.
+
+Once this Docker image is imported into ImageRepository, the service might be
+referenced by other metadata (SUBSCRIBES, REQUIRES, COMPANIONS, see bellow.)
+
+
+### SUBSCRIBES
+
+This variable contains a list of services that the Docker image can consume.
+The value can be a valid Docker image name or the service name. In order to
+distinguish between them, the proposed format for the value us following:
+
+```
+SUBSCRIBES="service:redis/6379,image:openshift/redis"
+```
+
+In this case, we lookup user ImageRepositories for the Docker image that
+publishes `redis/6379` service. If there is no match, we continue to search for
+the `openshift/redis` image.
+
+The generation tools should automatically generate corresponding Service for
+each defined service.
+
+### REQUIRES
+
+This variable contains a list of services that the Docker image requires in
+order to work properly. The value format is same as for SUBSCRIBES.  Where the
+SUBSCRIBES setup the infrastructure for pub/sub the REQUIRES might indicate that
+the Docker image requires another Docker image in order to work.  For example, a
+'phpmyadmin' requires 'mysql' service to be available, otherwise it won't work
+properly. A special 'backup' Docker image for mysql will require 'mysql' to be
+available within a Pod in order to do database dump from it.
+
+### COMPANIONS
+
+This variable contains a list of services that are companions to the Docker
+image. For example a 'redis-slave' Docker image is a companion for
+'redis-master' Docker image. Where the SUBSCRIBES defines relations to services
+that are required, the companions are optional and the Docker image can work
+without them.
+
+### SECRETS
+
+This variable contains a list of secrets (secret indentifiers) that the Docker
+image requires to work properly. For example the Docker image might require
+Twitter API keys in order to send HTTP requests to the Twitter API. The
+generation tools should check if the required secrets are available and if not,
+it should ask the user to provide them.
+
+An example value can be: `SECRETS=keys/twitter,keys/facebook`
+
+### SINGLETON
+
+This variable indicates if the Docker image is clusterable or not. In case of
+Docker image with standalone 'mysql' server you don't want to have the number of
+replicas in ReplicationController be higher than 1, otherwise you can risk that
+multiple standalone mysql servers will access data on shared volume.
+
+### HOST_VOLUMES
+
+This variable contains a list of Docker volumes that will be host-mounted
+instead of network mounted. These volumes will not be persistent, but they might
+be faster than network volumes.
+
+### URL_MAPPINGS
+
+This variable contains a list of URL mappings. For example, if your 'phpmyadmin'
+is available on '/phpmyadmin' URL, you can override this by specifying a mapping
+in following form: `/phpmyadmin:/`. In this case the traffic will gets routed
+from '/phpmyadmin' to '/'.
+
+### MIN_CPU,MIN_MEMORY,MIN_###
+
+This variable define a minimal amount of resources needed in order to make this
+Docker image work properly. This value should be plugged into the Container
+definitions and the resource quote should pre-check if the user has enough
+resources to start this Docker image.