platformdoc/docs/components/component-type-docker.md

   1 # Component Requirements: Docker
   2
   3 ## Overview
   4
   5 Component developers are required to provide artifacts for the platform to be able to deploy your component including:
   6
   7 * [Component specification](component-specification/docker-specification)
   8 * [Data formats](data-formats)
   9 * [Auxiliary component specification](component-specification/docker-specification#auxiliary)
  10 * [Docker image](#docker-on-the-platform)
  11
  12 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:
  13
  14 * [Service registration](#service-registration)
  15 * [Configuration management on the new platform](#configuration)
  16 * [Operational concerns](#operational-concerns)
  17
  18 To help component developers to make and to test the changes needed to have components run on the platform, a command-line tool called [`dcae-cli`](dcae-cli/quickstart) is provided by the platform team.
  19
  20 ## Service registration
  21
  22 Every [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:
  23
  24 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.
  25 2. Component healthcheck details must be provided in the Docker auxiliary component specification
  26
  27 ### Expose port
  28
  29 Components that listen on a specific port must explicitly declare in their Dockerfile that port using the `EXPOSE` instruction before building the image.
  30 Warning! At the current time, you can not expose multiple ports in your Dockerfile or registration *will not work* correctly.
  31
  32 ### Health check
  33
  34 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 [Docker auxiliary specification](component-specification/docker-specification#auxiliary).
  35
  36 ## Configuration
  37
  38 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`.
  39
  40 You can see more details on the generated application configuration [here](component-specification/docker-specification#generate-application-configuration).
  41
  42 ### Config binding service
  43 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:
  44
  45 ```
  46 <config binding service hostname>:<port>/service_component/NAME
  47 ```
  48 For Docker components, NAME should be set to `HOSTNAME`, which was provided as an ENV variable inside of your container.
  49
  50 The binding service integrates with the streams and services section of your component specification. For example, if you specify that you call a service:
  51 ```
  52 "services": {
  53     "calls": [{
  54         "config_key": "vnf-db",
  55         "request": {
  56             "format": "dcae.vnf.meta",
  57             "version": "1.0.0"
  58             },
  59         "response": {
  60             "format": "dcae.vnf.kpi",
  61             "version": "1.0.0"
  62             }
  63     }],
  64 ...
  65 }
  66 ```
  67 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`:
  68 ```
  69 // your configuration
  70 {
  71     "vbf-db" :                 // see above
  72         [IP:Port1, IP:Port2,…] // all of these meet your needs, choose one.
  73 }
  74 ```
  75 Regarding `<config binding service hostname>:<port>`, there is DNS work going on to make this resolvable in a convenient way inside of your container.
  76 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
  77 `<config binding service hostname>:<port>`.
  78
  79 ### Policy Reconfiguration
  80
  81 *Details coming soon*
  82
  83 ### DMaaP
  84
  85 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 [message router topic](component-specification/common-specification/#message-router) or to a [data router feed](component-specification/common-specification/#data-router).  Given a composition with components that use DMaaP, the platform will provision the topic or feed and provide the necessary [connection details](dcae-cli/dmaap-connection-objects) at runtime for each DMaaP dependent component.  These connection details will be provided through your application's [generated configuration](component-specification/generated-configuration).
  86
  87 In order to test DMaaP connections in onboarding, the developer (currently) must provision all test topics and feeds manually and provide the [dcae-cli with the connection details](dcae-cli/walkthrough/#dmaap-testing) when deploying your application.
  88
  89 ## Docker on the platform
  90
  91 ### Images
  92
  93 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.
  94
  95 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.
  96
  97 ```
  98 docker login YOUR_NEXUS_DOCKER_REGISTRY
  99 ```
 100
 101 Tag your image:
 102
 103 ```
 104 docker tag laika:0.4.0 YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0
 105 ```
 106
 107 Or build and tag:
 108
 109 ```
 110 docker build -t YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0 .
 111 ```
 112
 113 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.
 114
 115 ```
 116 docker push YOUR_NEXUS_DOCKER_REGISTRY/laika:0.4.0
 117 ```
 118
 119 *NOTE*  Replace `laika` with your application's name.  Replace the `0.4.0` version with your application's version.
 120
 121 ### Ports
 122
 123 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 [you exposed](#service-registration).
 124
 125 ### Envs
 126
 127 The platform provides a set of environment variables into each Docker container:
 128
 129 Name | Type | Description
 130 ---- | ---- | -----------
 131 `HOSTNAME` | string | Unique name of the component instance that is generated
 132 `CONSUL_HOST` | string | Hostname of the platform's Consul instance
 133 `CONFIG_BINDING_SERVICE` | string | Hostname of the platform's config binding service instance
 134 `DOCKER_HOST` | string | Host of the target platform Docker host to run the container on
 135
 136 ## Operational concerns
 137
 138 ### Logging
 139
 140 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.
 141
 142 To use the `docker logs` command for your deployed running Docker container,
 143
 144 1.  You must have Docker installed on your local machine
 145 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`.
 146 3.  Find the target Docker host using the `dcae_cli profiles show` command:
 147
 148 ```
 149 $ dcae_cli profiles show YOUR_PROFILE_NAME
 150 {
 151     ...
 152     "docker_host": "YOUR_DOCKER_HOST:2376"
 153 }
 154 ```
 155
 156 4.  Set your Docker client to point to the target Docker host:
 157
 158 ```
 159 $ export DOCKER_HOST="tcp://YOUR_DOCKER_HOST:2376"
 160 ```
 161
 162 5.  Use the `docker logs` command:
 163
 164 ```
 165 $ docker logs <generated component name>
 166 ```