k8s/README.md

   1 # ONAP DCAE Kubernetes Plugin for Cloudify
   2
   3 This directory contains a Cloudify plugin  used to orchestrate the deployment of containerized DCAE platform and service components  into a Kubernetes ("k8s")
   4 environment. This work is based on the [ONAP DCAE Docker plugin] (../docker).
   5
   6 This plugin is *not* a generic Kubernetes plugin that exposes the full set of Kubernetes features.
   7 In fact, the plugin largely hides the fact that we're using Kubernetes from both component developers and blueprint authors,
   8 The Cloudify node type definitions are very similar to the Cloudify type definitions used in the ONAP DCAE Docker plugin.
   9
  10 For the node types `ContainerizedPlatformComponent`, `ContainerizedServiceComponent`, and `ContainerizedServiceComponentUsingDmaap`, this plugin
  11 creates the following Kubernetes entities:
  12
  13 - A Kubernetes `Deployment` containing information about what containers to run and what volume to mount.
  14   - The `Deployment` always includes a container that runs the component's Docker image
  15   - The `Deployment` includes any volumes specified in the blueprint
  16   - If the blueprint specifies a logging directory via the `log_info` property, the `Deployment` includes a second container,
  17   running the `filebeat` logging sidecar that ships logging information to the ONAP ELK stack.  The `Deployment` will include
  18   some additional volumes needed by filebeat.
  19 - If the blueprint indicates that the component exposes any ports, the plugin will create a Kubernetes `Service` that allocates an address
  20   in the Kubernetes network address space that will route traffic to a container that's running the component.  This `Service` provides a
  21   fixed "virtual IP" for the component.
  22 - If the blueprint indicates that the component exposes a port externally, the plugin will create an additional Kubernetes `Service` that opens up a
  23   port on the external interface of each node in the Kubernetes cluster.
  24
  25 Through the `replicas` property, a blueprint can request deployment of multiple instances of the component.  The plugin will still create a single `Deployment` (and,
  26 if needed one or two `Services`), but the `Deployment` will cause multiple instances of the container to run.   (Specifically, the `Deployment` will create
  27 a Kubernetes `Pod` for each requested instance.)  Other entities connect to a component via the IP address of a `Service`, and Kubernetes takes care of routing
  28 traffic to an appropriate container instance.
  29
  30 ## Pre-requisites
  31 ### Configuration
  32 #### Configuration file
  33 The plugin expects a configuration file in the Python "ini" format to be stored at `/opt/onap/config.txt`.  This file contains the address of the Consul cluster.
  34 Here is an example:
  35 ```
  36 [consul]
  37 address=10.12.5.115:30270
  38 ```
  39 #### Configuration entry in Consul
  40 Additional configuration information is stored in the Consul KV store under the key `k8s-plugin`.
  41 The configuration is provided as JSON object with the following properties:
  42
  43     - namespace:  k8s namespace to use for DCAE
  44     - consul_dns_name: k8s internal DNS name for Consul (passed to containers)
  45     - image_pull_secrets: list of names of k8s secrets for accessing Docker registries, with the following properties:
  46     - filebeat:  object containing onfiguration for setting up filebeat container
  47             - log_path: mount point for log volume in filebeat container
  48             - data_path: mount point for data volume in filebeat container
  49             - config_path: mount point for config volume in filebeat container
  50             - config_subpath: subpath for config data in filebeat container
  51             - config_map: name of a ConfigMap holding the filebeat configuration file
  52             - image: Docker image to use for filebeat
  53
  54 #### Kubernetes access information
  55 The plugin accesses a Kubernetes cluster.  The information and credentials for accessing a cluster are stored in a "kubeconfig"
  56 file.  The plugin expects to find such a file at `/etc/cloudify/.kube/config`.
  57
  58 #### Additional Kubernetes configuration elements
  59 The plugin expects certain elements to be provided in the DCAE/ONAP environment, namely:
  60    - Kubernetes secret(s) containing the credentials needed to pull images from Docker registries, if needed
  61    - A Kubernetes ConfigMap containing the filebeat.yml file used by the filebeat logging container
  62    - An ExternalName service
  63
  64
  65 ## Input parameters
  66
  67 ### start
  68
  69 These input parameters are for the `start` `cloudify.interfaces.lifecycle` and are inputs into the variant task operations `create_and_start_container*`.
  70
  71 #### `envs`
  72
  73 A map of environment variables that is intended to be forwarded to the container as environment variables.  Example:
  74
  75 ```yaml
  76 envs:
  77   EXTERNAL_IP: '10.100.1.99'
  78 ```
  79
  80 These environment variables will be forwarded in addition to the *platform-related* environment variables like `CONSUL_HOST`.
  81
  82 #### `volumes`
  83
  84 List of maps used for setting up Kubernetes volume mounts.  Example:
  85
  86 ```yaml
  87 volumes:
  88   - host:
  89       path: '/var/run/docker.sock'
  90     container:
  91       bind: '/tmp/docker.sock'
  92       mode: 'ro'
  93 ```
  94
  95 The table below describes the fields.
  96
  97 key | description
  98 --- | -----------
  99 path | Full path to the file or directory on the host machine to be mounted
 100 bind | Full path to the file or directory in the container where the volume should be mounted to
 101 mode | Readable, writeable: `ro`, `rw`
 102
 103 #### `ports`
 104
 105 List of strings - Used to bind container ports to host ports. Each item is of the format: `<container port>:<host port>`.
 106
 107 Note that `ContainerizedPlatformComponent` has the property pair `host_port` and `container_port`. This pair will be merged with the input parameters ports.
 108
 109 ```yaml
 110 ports:
 111   - '8000:31000'
 112 ```
 113
 114 Default is `None`.
 115
 116 In the Kubernetes environment, most components will communicate over the Kubernetes network using private addresses. For those cases,
 117 setting the `<host port>` to 0 will expose the `<container port>` to other components on the Kubernetes network, but not will not expose any
 118 ports on the Kubernetes host's external interface.    Setting `<host port>` to a non-zero value will expose that port on the external interfaces
 119 of every Kubernetes host in the cluster.  (This uses the Kubernetes `NodePort` service type.)
 120
 121 #### `max_wait`
 122
 123 Integer - seconds to wait for Docker to come up healthy before throwing a `NonRecoverableError`.
 124
 125 ```yaml
 126 max_wait:
 127     60
 128 ```
 129
 130 Default is 300 seconds.
 131
 132
 133 ## Using DMaaP
 134
 135 The node type `dcae.nodes.ContainerizedServiceComponentUsingDmaap` is intended to be used by components that use DMaaP and expects to be connected with the DMaaP node types found in the DMaaP plugin.
 136
 137 ### Node properties
 138
 139 The properties `streams_publishes` and `streams_subscribes` both are lists of objects that are intended to be passed into the DMaaP plugin and used to create additional parameters that will be passed into the DMaaP plugin.
 140
 141 #### Message router
 142
 143 For message router publishers and subscribers, the objects look like:
 144
 145 ```yaml
 146 name: topic00
 147 location: mtc5
 148 client_role: XXXX
 149 type: message_router
 150 ```
 151
 152 Where `name` is the node name of `dcae.nodes.Topic` or `dcae.nodes.ExistingTopic` that the Docker node is connecting with via the relationships `dcae.relationships.publish_events` for publishing and `dcae.relationships.subscribe_to_events` for subscribing.
 153
 154 #### Data router
 155
 156 For data router publishers, the object looks like:
 157
 158 ```yaml
 159 name: feed00
 160 location: mtc5
 161 type: data_router
 162 ```
 163
 164 Where `name` is the node name of `dcae.nodes.Feed` or `dcae.nodes.ExistingFeed` that the Docker node is connecting with via the relationships `dcae.relationships.publish_files`.
 165
 166 For data router subscribers, the object looks like:
 167
 168 ```yaml
 169 name: feed00
 170 location: mtc5
 171 type: data_router
 172 username: king
 173 password: "123456"
 174 route: some-path
 175 scheme: https
 176 ```
 177
 178 Where the relationship to use is `dcae.relationships.subscribe_to_files`.
 179
 180 If `username` and `password` are not provided, then the plugin will generate username and password pair.
 181
 182 `route` and `scheme` are parameter used in the dynamic construction of the delivery url which will be passed to the DMaaP plugin to be used in the setting up of the subscriber to the feed.
 183
 184 `route` is the http path endpoint of the subscriber that will handle files from the associated feed.
 185
 186 `scheme` is either `http` or `https`.  If not specified, then the plugin will default to `http`.
 187
 188 ### Component configuration
 189
 190 The DMaaP plugin is responsible to provision the feed/topic and store into Consul the resulting DMaaP connection details.  Here is an example:
 191
 192 ```json
 193 {
 194     "topic00": {
 195         "client_role": "XXXX",
 196         "client_id": "XXXX",
 197         "location": "XXXX",
 198         "topic_url": "https://some-topic-url.com/events/abc"
 199     }
 200 }
 201 ```
 202
 203 This is to be merged with the templatized application configuration:
 204
 205 ```json
 206 {
 207     "some-param": "Lorem ipsum dolor sit amet",
 208     "streams_subscribes": {
 209         "topic-alpha": {
 210             "type": "message_router",
 211             "aaf_username": "user-foo",
 212             "aaf_password": "password-bar",
 213             "dmaap_info": "<< topic00 >>"
 214         },
 215     },
 216     "streams_publishes": {},
 217     "services_calls": {}
 218 }
 219 ```
 220
 221 To form the application configuration:
 222
 223 ```json
 224 {
 225     "some-param": "Lorem ipsum dolor sit amet",
 226     "streams_subscribes": {
 227         "topic-alpha": {
 228             "type": "message_router",
 229             "aaf_username": "user-foo",
 230             "aaf_password": "password-bar",
 231             "dmaap_info": {
 232                 "client_role": "XXXX",
 233                 "client_id": "XXXX",
 234                 "location": "XXXX",
 235                 "topic_url": "https://some-topic-url.com/events/abc"
 236             }
 237         },
 238     },
 239     "streams_publishes": {},
 240     "services_calls": {}
 241 }
 242 ```
 243
 244 This also applies to data router feeds.