From 1fca6acb2918beef86a5a78dc659683830908cd2 Mon Sep 17 00:00:00 2001 From: Ralph Knag Date: Tue, 5 Dec 2017 12:05:57 -0500 Subject: DCAE Controller documentation DCAEGEN2-213 Issue-ID: DCAEGEN2-213 Change-Id: I7f2023b7f88b73eef852eca0bbf9086e14903cd6 Signed-off-by: Ralph Knag --- docs/sections/components/component-type-docker.rst | 319 +++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100755 docs/sections/components/component-type-docker.rst (limited to 'docs/sections/components/component-type-docker.rst') 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 ` +- :doc:`Data formats ` +- :any:`Auxiliary component specification ` +- :any:`Docker image ` + +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 ` +- :any:`Configuration management on the new platform ` +- :any:`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 ` is provided by the platform team. + +.. _service-registration: + +Service registration +-------------------- + +Every :doc:`Docker component is registered ` 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 `_ 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 `_. The details of the definition used by your component is to be provided through the :any:`Docker auxiliary specification `. + +.. _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 `. + +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: + +:: + + :/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 ``:``, 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 +``:``. + +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 `) +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 ` or to a :any:`data router feed `. +Given a composition with components that use DMaaP, the platform will +provision the topic or feed and provide the necessary :any:`connection details ` at runtime for each DMaaP +dependent component. These connection details will be provided through +your application’s :any:`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 ` 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 `_ 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 `_ . +Note that the registry may require a login. Use the Docker `login command `_ +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 `. + +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 -- cgit 1.2.3-korg