Merge "DCAE Controller documentation DCAEGEN2-213" into amsterdam

1 files changed, 319 insertions, 0 deletions

diff --git a/docs/sections/components/component-type-docker.rst b/docs/sections/components/component-type-docker.rst
new file mode 100755
index 00000000..449e58a8
--- /dev/null
+++ b/docs/sections/components/component-type-docker.rst
@@ -0,0 +1,319 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.

+.. http://creativecommons.org/licenses/by/4.0

+

+.. _docker-requirements:

+

+Docker Component Requirements

+=============================

+

+Overview

+--------

+

+Component developers are required to provide artifacts for the platform

+to be able to deploy your component including:

+

+-  :any:`Component specification <docker-specification>`

+-  :doc:`Data formats <data-formats>`

+-  :any:`Auxiliary component specification <docker-auxiliary-details>`

+-  :any:`Docker image <docker-on-the-platform>`

+

+In addition, components will have to be enhanced to be compliant with

+the DCAE platform in order to correctly be deployed and be managed. This

+page will discuss the changes which are grouped into the following

+categories:

+

+-  :any:`Service registration <service-registration>`

+-  :any:`Configuration management on the new platform <docker-configuration>`

+-  :any:`Operational concerns <operational-concerns>`

+

+To help component developers to make and to test the changes needed to

+have components run on the platform, a command-line tool called

+:doc:`dcae-cli <dcae-cli/quickstart>` is provided by the platform team.

+

+.. _service-registration:

+

+Service registration

+--------------------

+

+Every :doc:`Docker component is registered <architecture/service-discovery>` with the platform’s

+service discovery layer. Docker components are not expected to make the

+explicit make registration calls because that is done by through a

+platform 3rd party registration service. A couple things are needed from

+component developers in order for this registration to occur

+successfully:

+

+1. Docker images must be created from a Dockerfile that has an `EXPOSE <https://docs.docker.com/engine/reference/builder/#/expose>`_ instruction. This applies to components that listen on a port.

+2. Component healthcheck details must be provided in the Docker

+   auxiliary component specification

+

+Expose port

+~~~~~~~~~~~

+

+Components that listen on a specific port must explicitly declare in

+their Dockerfile that port using the ``EXPOSE`` instruction before

+building the image. Warning! At the current time, you can not expose

+multiple ports in your Dockerfile or registration *will not work*

+correctly.

+

+Health check

+~~~~~~~~~~~~

+

+Component developers are required to provide a way for the platform to periodically check the health of their running components. The platform uses Consul to perform these periodic calls. Consul provides different types of `check definitions <https://www.consul.io/docs/agent/checks.html>`_. The details of the definition used by your component is to be provided through the :any:`Docker auxiliary specification <docker-auxiliary-details>`.

+

+.. _docker-configuration:

+

+Configuration

+-------------

+

+The component’s application configuration is generated from the

+submitted component specification into a JSON representation. The DCAE

+platform will provide the configuration JSON by making it available on a

+remote HTTP service. Components are required to pull their configuration

+JSON at application startup. The configuration JSON is stored under the

+components uniquely generated name which is provided by the environment

+variable ``HOSTNAME``.

+

+You can see more details on the generated application configuration

+:any:`here <docker-specification>`.

+

+Config binding service

+~~~~~~~~~~~~~~~~~~~~~~

+

+The config binding service is a platform HTTP service that is

+responsible for providing clients with a fully resolved configuration

+JSON at runtime. Components should make an HTTP GET on:

+

+::

+

+    <config binding service hostname>:<port>/service_component/NAME

+

+For Docker components, NAME should be set to ``HOSTNAME``, which was

+provided as an ENV variable inside of your container.

+

+The binding service integrates with the streams and services section of

+your component specification. For example, if you specify that you call

+a service:

+

+::

+

+    "services": {

+        "calls": [{

+            "config_key": "vnf-db",

+            "request": {

+                "format": "dcae.vnf.meta",

+                "version": "1.0.0"

+                },

+            "response": {

+                "format": "dcae.vnf.kpi",

+                "version": "1.0.0"

+                }

+        }],

+    ...

+    }

+

+Then the config binding service will find all available IP addresses of

+services meeting your needs, and provide them to you under your

+``config_key``:

+

+::

+

+    // your configuration

+    {

+        "vbf-db" :                 // see above 

+            [IP:Port1, IP:Port2,…] // all of these meet your needs, choose one.

+    }

+

+Regarding ``<config binding service hostname>:<port>``, there is DNS

+work going on to make this resolvable in a convenient way inside of your

+container. However, currently you will be given a name as an ENV

+variable, ``CONFIG_BINDING_SERVICE``, and you will need to query

+Consul’s service discovery to get

+``<config binding service hostname>:<port>``.

+

+Policy Reconfiguration

+~~~~~~~~~~~~~~~~~~~~~~

+

+*(Draft and subject to change)*

+

+Components must provide a way to receive policy reconfiguration, that

+is, configuration parameters that have been updated via the Policy UI.

+The component developer provides a docker script (defined in the :any:`Docker auxiliary specification <docker-specification>`)

+that will be triggered when this occurs.

+

+DMaaP

+~~~~~

+

+Components can be publishers or subscribers to either message router

+topics or data router feeds. This is defined in the component

+specification under the ``streams`` section where you can specify

+whether your component is expected to subscribe or to publish to a

+:any:`message router topic <message-router>` or to a :any:`data router feed <data-router>`.

+Given a composition with components that use DMaaP, the platform will

+provision the topic or feed and provide the necessary :any:`connection details <dcae-cli/dmaap-connection-objects>` at runtime for each DMaaP

+dependent component. These connection details will be provided through

+your application’s :any:`generated configuration <component-specification/generated-configuration>`.

+

+In order to test DMaaP connections in onboarding, the developer

+(currently) must provision all test topics and feeds manually and

+provide the :any:`dcae-cli with the connection details <dmaap-testing>` when deploying your

+application.

+

+.. _docker-on-the-platform:

+

+Docker on the platform

+----------------------

+

+Images

+~~~~~~

+

+Docker images must be pushed to the environment specific Nexus

+repository. This requires tagging your build with the full name of you

+image which includes the Nexus repository name.

+

+Use the Docker command-line to `tag <https://docs.docker.com/engine/reference/commandline/tag/>`_ your Docker image where the *target image* must contain the registry host name and port.

+

+For example, an application called laika has been tagged for an example

+Nexus registry:

+

+::

+

+    $ docker images

+    REPOSITORY                                                                               TAG                 IMAGE ID            CREATED             SIZE

+    YOUR_NEXUS_DOCKER_REGISTRY/laika                                                 0.4.0               154cc382df61        7 weeks ago         710.5 MB

+    laika                                                                                    0.4.0               154cc382df61        7 weeks ago         710.5 MB

+

+Note, the Docker registry that is used may require a login to

+authenticate.

+

+::

+

+    docker login YOUR_NEXUS_DOCKER_REGISTRY

+

+Tag your image:

+

+::

+

+    docker tag laika:0.4.0 YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0

+

+Or build and tag:

+

+::

+

+    docker build -t YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0 .

+

+After tagging, upload your image to the remote registry using the Docker `push command <https://docs.docker.com/engine/reference/commandline/push/>`_ .

+Note that the registry may require a login. Use the Docker `login command <https://docs.docker.com/engine/reference/commandline/login/>`_

+before pushing in that case.

+

+::

+

+    docker push YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0

+

+*NOTE* Replace ``laika`` with your application’s name. Replace the

+``0.4.0`` version with your application’s version.

+

+Ports

+~~~~~

+

+On the DCAE platform, Docker components are run with the ``--publish-all`` or ``-P`` argument. This means the Docker container

+for your component will be listening on a random port and that random

+port will be mapped to the port :any:`you exposed <service-registration>`.

+

+Envs

+~~~~

+

+The platform provides a set of environment variables into each Docker

+container:

+

++----------------------------+----+----------+

+| Na\                        | Ty\| Descript\|

+| me                         | pe | ion      |

++============================+====+==========+

+| ``HOSTNAME``               | st\| Unique   |

+|                            | ri\| name of  |

+|                            | ng | the      |

+|                            |    | componen\|

+|                            |    | t        |

+|                            |    | instance |

+|                            |    | that is  |

+|                            |    | generate\|

+|                            |    | d        |

++----------------------------+----+----------+

+| ``CONSOL_HOST``            | st\| Hostname |

+|                            | ri\| of the   |

+|                            | ng | platform\|

+|                            |    | ’s       |

+|                            |    | Consul   |

+|                            |    | instance |

+|                            |    |          |

+|                            |    |          |

++----------------------------+----+----------+

+| ``CONFIG_BINDING_SERVICE`` | st\| Hostname |

+|                            | ri\| of the   |

+|                            | ng | platform\|

+|                            |    | ’s       |

+|                            |    | config   |

+|                            |    | binding  |

+|                            |    | service  |

+|                            |    | instance |

+|                            |    |          |

+|                            |    |          |

+|                            |    |          |

+|                            |    |          |

+|                            |    |          |

++----------------------------+----+----------+

+| ``DOCKER_HOSTS``           | st\| Host of  |

+|                            | ri\| the      |

+|                            | ng | target   |

+|                            |    | platform |

+|                            |    | Docker   |

+|                            |    | host to  |

+|                            |    | run the  |

+|                            |    | containe\|

+|                            |    | r        |

+|                            |    | on       |

++----------------------------+----+----------+

+

+.. _operational-concerns:

+

+Operational concerns

+--------------------

+

+Logging

+~~~~~~~

+

+Currently the platform uses the default ``json-file`` logging driver for

+Docker. For onboarding testing, component developers can access their

+logs from their Docker containers either by running their component

+using the ``--attached`` flag or by using the ``docker logs`` command.

+The requirement is that applications must write to stdout and/or stderr.

+

+To use the ``docker logs`` command for your deployed running Docker

+container,

+

+1. You must have Docker installed on your local machine

+2. Have the generated name of your component. This is generated for you

+   when you execute ``dcae_cli component dev`` or

+   ``dcae_cli component run``.

+3. Find the target Docker host using the ``dcae_cli profiles show``

+   command:

+

+::

+

+    $ dcae_cli profiles show YOUR_PROFILE_NAME

+    {

+        ...

+        "docker_host": "YOUR_DOCKER_HOST:2376"

+    }

+

+4. Set your Docker client to point to the target Docker host:

+

+::

+

+    $ export DOCKER_HOST="tcp://YOUR_DOCKER_HOST:2376"

+

+5. Use the ``docker logs`` command:

+

+::

+

+    $ docker logs <generated component name>