--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
+.. http://creativecommons.org/licenses/by/4.0\r
+\r
+.. _docker-requirements:\r
+\r
+Docker Component Requirements\r
+=============================\r
+\r
+Overview\r
+--------\r
+\r
+Component developers are required to provide artifacts for the platform\r
+to be able to deploy your component including:\r
+\r
+- :any:`Component specification <docker-specification>`\r
+- :doc:`Data formats <data-formats>`\r
+- :any:`Auxiliary component specification <docker-auxiliary-details>`\r
+- :any:`Docker image <docker-on-the-platform>`\r
+\r
+In addition, components will have to be enhanced to be compliant with\r
+the DCAE platform in order to correctly be deployed and be managed. This\r
+page will discuss the changes which are grouped into the following\r
+categories:\r
+\r
+- :any:`Service registration <service-registration>`\r
+- :any:`Configuration management on the new platform <docker-configuration>`\r
+- :any:`Operational concerns <operational-concerns>`\r
+\r
+To help component developers to make and to test the changes needed to\r
+have components run on the platform, a command-line tool called\r
+:doc:`dcae-cli <dcae-cli/quickstart>` is provided by the platform team.\r
+\r
+.. _service-registration:\r
+\r
+Service registration\r
+--------------------\r
+\r
+Every :doc:`Docker component is registered <architecture/service-discovery>` with the platform’s\r
+service discovery layer. Docker components are not expected to make the\r
+explicit make registration calls because that is done by through a\r
+platform 3rd party registration service. A couple things are needed from\r
+component developers in order for this registration to occur\r
+successfully:\r
+\r
+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.\r
+2. Component healthcheck details must be provided in the Docker\r
+ auxiliary component specification\r
+\r
+Expose port\r
+~~~~~~~~~~~\r
+\r
+Components that listen on a specific port must explicitly declare in\r
+their Dockerfile that port using the ``EXPOSE`` instruction before\r
+building the image. Warning! At the current time, you can not expose\r
+multiple ports in your Dockerfile or registration *will not work*\r
+correctly.\r
+\r
+Health check\r
+~~~~~~~~~~~~\r
+\r
+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>`.\r
+\r
+.. _docker-configuration:\r
+\r
+Configuration\r
+-------------\r
+\r
+The component’s application configuration is generated from the\r
+submitted component specification into a JSON representation. The DCAE\r
+platform will provide the configuration JSON by making it available on a\r
+remote HTTP service. Components are required to pull their configuration\r
+JSON at application startup. The configuration JSON is stored under the\r
+components uniquely generated name which is provided by the environment\r
+variable ``HOSTNAME``.\r
+\r
+You can see more details on the generated application configuration\r
+:any:`here <docker-specification>`.\r
+\r
+Config binding service\r
+~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+The config binding service is a platform HTTP service that is\r
+responsible for providing clients with a fully resolved configuration\r
+JSON at runtime. Components should make an HTTP GET on:\r
+\r
+::\r
+\r
+ <config binding service hostname>:<port>/service_component/NAME\r
+\r
+For Docker components, NAME should be set to ``HOSTNAME``, which was\r
+provided as an ENV variable inside of your container.\r
+\r
+The binding service integrates with the streams and services section of\r
+your component specification. For example, if you specify that you call\r
+a service:\r
+\r
+::\r
+\r
+ "services": {\r
+ "calls": [{\r
+ "config_key": "vnf-db",\r
+ "request": {\r
+ "format": "dcae.vnf.meta",\r
+ "version": "1.0.0"\r
+ },\r
+ "response": {\r
+ "format": "dcae.vnf.kpi",\r
+ "version": "1.0.0"\r
+ }\r
+ }],\r
+ ...\r
+ }\r
+\r
+Then the config binding service will find all available IP addresses of\r
+services meeting your needs, and provide them to you under your\r
+``config_key``:\r
+\r
+::\r
+\r
+ // your configuration\r
+ {\r
+ "vbf-db" : // see above \r
+ [IP:Port1, IP:Port2,…] // all of these meet your needs, choose one.\r
+ }\r
+\r
+Regarding ``<config binding service hostname>:<port>``, there is DNS\r
+work going on to make this resolvable in a convenient way inside of your\r
+container. However, currently you will be given a name as an ENV\r
+variable, ``CONFIG_BINDING_SERVICE``, and you will need to query\r
+Consul’s service discovery to get\r
+``<config binding service hostname>:<port>``.\r
+\r
+Policy Reconfiguration\r
+~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+*(Draft and subject to change)*\r
+\r
+Components must provide a way to receive policy reconfiguration, that\r
+is, configuration parameters that have been updated via the Policy UI.\r
+The component developer provides a docker script (defined in the :any:`Docker auxiliary specification <docker-specification>`)\r
+that will be triggered when this occurs.\r
+\r
+DMaaP\r
+~~~~~\r
+\r
+Components can be publishers or subscribers to either message router\r
+topics or data router feeds. This is defined in the component\r
+specification under the ``streams`` section where you can specify\r
+whether your component is expected to subscribe or to publish to a\r
+:any:`message router topic <message-router>` or to a :any:`data router feed <data-router>`.\r
+Given a composition with components that use DMaaP, the platform will\r
+provision the topic or feed and provide the necessary :any:`connection details <dcae-cli/dmaap-connection-objects>` at runtime for each DMaaP\r
+dependent component. These connection details will be provided through\r
+your application’s :any:`generated configuration <component-specification/generated-configuration>`.\r
+\r
+In order to test DMaaP connections in onboarding, the developer\r
+(currently) must provision all test topics and feeds manually and\r
+provide the :any:`dcae-cli with the connection details <dmaap-testing>` when deploying your\r
+application.\r
+\r
+.. _docker-on-the-platform:\r
+\r
+Docker on the platform\r
+----------------------\r
+\r
+Images\r
+~~~~~~\r
+\r
+Docker images must be pushed to the environment specific Nexus\r
+repository. This requires tagging your build with the full name of you\r
+image which includes the Nexus repository name.\r
+\r
+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.\r
+\r
+For example, an application called laika has been tagged for an example\r
+Nexus registry:\r
+\r
+::\r
+\r
+ $ docker images\r
+ REPOSITORY TAG IMAGE ID CREATED SIZE\r
+ YOUR_NEXUS_DOCKER_REGISTRY/laika 0.4.0 154cc382df61 7 weeks ago 710.5 MB\r
+ laika 0.4.0 154cc382df61 7 weeks ago 710.5 MB\r
+\r
+Note, the Docker registry that is used may require a login to\r
+authenticate.\r
+\r
+::\r
+\r
+ docker login YOUR_NEXUS_DOCKER_REGISTRY\r
+\r
+Tag your image:\r
+\r
+::\r
+\r
+ docker tag laika:0.4.0 YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0\r
+\r
+Or build and tag:\r
+\r
+::\r
+\r
+ docker build -t YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0 .\r
+\r
+After tagging, upload your image to the remote registry using the Docker `push command <https://docs.docker.com/engine/reference/commandline/push/>`_ .\r
+Note that the registry may require a login. Use the Docker `login command <https://docs.docker.com/engine/reference/commandline/login/>`_\r
+before pushing in that case.\r
+\r
+::\r
+\r
+ docker push YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0\r
+\r
+*NOTE* Replace ``laika`` with your application’s name. Replace the\r
+``0.4.0`` version with your application’s version.\r
+\r
+Ports\r
+~~~~~\r
+\r
+On the DCAE platform, Docker components are run with the ``--publish-all`` or ``-P`` argument. This means the Docker container\r
+for your component will be listening on a random port and that random\r
+port will be mapped to the port :any:`you exposed <service-registration>`.\r
+\r
+Envs\r
+~~~~\r
+\r
+The platform provides a set of environment variables into each Docker\r
+container:\r
+\r
++----------------------------+----+----------+\r
+| Na\ | Ty\| Descript\|\r
+| me | pe | ion |\r
++============================+====+==========+\r
+| ``HOSTNAME`` | st\| Unique |\r
+| | ri\| name of |\r
+| | ng | the |\r
+| | | componen\|\r
+| | | t |\r
+| | | instance |\r
+| | | that is |\r
+| | | generate\|\r
+| | | d |\r
++----------------------------+----+----------+\r
+| ``CONSOL_HOST`` | st\| Hostname |\r
+| | ri\| of the |\r
+| | ng | platform\|\r
+| | | ’s |\r
+| | | Consul |\r
+| | | instance |\r
+| | | |\r
+| | | |\r
++----------------------------+----+----------+\r
+| ``CONFIG_BINDING_SERVICE`` | st\| Hostname |\r
+| | ri\| of the |\r
+| | ng | platform\|\r
+| | | ’s |\r
+| | | config |\r
+| | | binding |\r
+| | | service |\r
+| | | instance |\r
+| | | |\r
+| | | |\r
+| | | |\r
+| | | |\r
+| | | |\r
++----------------------------+----+----------+\r
+| ``DOCKER_HOSTS`` | st\| Host of |\r
+| | ri\| the |\r
+| | ng | target |\r
+| | | platform |\r
+| | | Docker |\r
+| | | host to |\r
+| | | run the |\r
+| | | containe\|\r
+| | | r |\r
+| | | on |\r
++----------------------------+----+----------+\r
+\r
+.. _operational-concerns:\r
+\r
+Operational concerns\r
+--------------------\r
+\r
+Logging\r
+~~~~~~~\r
+\r
+Currently the platform uses the default ``json-file`` logging driver for\r
+Docker. For onboarding testing, component developers can access their\r
+logs from their Docker containers either by running their component\r
+using the ``--attached`` flag or by using the ``docker logs`` command.\r
+The requirement is that applications must write to stdout and/or stderr.\r
+\r
+To use the ``docker logs`` command for your deployed running Docker\r
+container,\r
+\r
+1. You must have Docker installed on your local machine\r
+2. Have the generated name of your component. This is generated for you\r
+ when you execute ``dcae_cli component dev`` or\r
+ ``dcae_cli component run``.\r
+3. Find the target Docker host using the ``dcae_cli profiles show``\r
+ command:\r
+\r
+::\r
+\r
+ $ dcae_cli profiles show YOUR_PROFILE_NAME\r
+ {\r
+ ...\r
+ "docker_host": "YOUR_DOCKER_HOST:2376"\r
+ }\r
+\r
+4. Set your Docker client to point to the target Docker host:\r
+\r
+::\r
+\r
+ $ export DOCKER_HOST="tcp://YOUR_DOCKER_HOST:2376"\r
+\r
+5. Use the ``docker logs`` command:\r
+\r
+::\r
+\r
+ $ docker logs <generated component name>\r
Code Review / dcaegen2.git / blobdiff