diff options
Diffstat (limited to 'docs/sections/components/component-type-docker.rst')
| -rwxr-xr-x | docs/sections/components/component-type-docker.rst | 319 |
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>
|