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 specifies that the component uses TLS (HTTPS) via the `tls_info` property, the `Deployment` includes an init container,
  20     a volume that holds TLS certificate artifacts, and volume mounts on the init container and the component's container.  The init container
  21     populates the TLS certificate artifacts volume with certificates, keys, keystores, etc.
  22 - If the blueprint indicates that the component exposes any ports, the plugin will create a Kubernetes `Service` that allocates an address
  23   in the Kubernetes network address space that will route traffic to a container that's running the component.  This `Service` provides a
  24   fixed "virtual IP" for the component.
  25 - If the blueprint indicates that the component exposes a port externally, the plugin will create an additional Kubernetes `Service` that opens up a
  26   port on the external interface of each node in the Kubernetes cluster.
  27
  28 Through the `replicas` property, a blueprint can request deployment of multiple instances of the component.  The plugin will still create a single `Deployment` (and,
  29 if needed one or two `Services`), but the `Deployment` will cause multiple instances of the container to run.   (Specifically, the `Deployment` will create
  30 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
  31 traffic to an appropriate container instance.
  32
  33 ## Pre-requisites
  34 ### Configuration
  35 #### Configuration file
  36 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.
  37 Here is an example:
  38 ```
  39 [consul]
  40 address=10.12.5.115:30270
  41 ```
  42 #### Configuration entry in Consul
  43 Additional configuration information is stored in the Consul KV store under the key `k8s-plugin`.
  44 The configuration is provided as JSON object with the following properties:
  45
  46     - `namespace`:  k8s namespace to use for DCAE
  47     - `consul_dns_name`: k8s internal DNS name for Consul (passed to containers)
  48     - `image_pull_secrets`: list of names of k8s secrets for accessing Docker registries, with the following properties:
  49     - `filebeat`:  object containing onfiguration for setting up filebeat container
  50             - `log_path`: mount point for log volume in filebeat container
  51             - `data_path`: mount point for data volume in filebeat container
  52             - `config_path`: mount point for config volume in filebeat container
  53             - `config_subpath`: subpath for config data in filebeat container
  54             - `config_map`: name of a ConfigMap holding the filebeat configuration file
  55             - `image`: Docker image to use for filebeat
  56     - `tls`: object containing configuration for setting up TLS init container
  57             - `cert_path`: mount point for the TLS certificate artifact volume in the init container
  58             - `image`: Docker image to use for the TLS init container
  59
  60
  61 #### Kubernetes access information
  62 The plugin accesses a Kubernetes cluster.  The information and credentials for accessing a cluster are stored in a "kubeconfig"
  63 file.  The plugin expects to find such a file at `/etc/cloudify/.kube/config`.
  64
  65 #### Additional Kubernetes configuration elements
  66 The plugin expects certain elements to be provided in the DCAE/ONAP environment, namely:
  67    - Kubernetes secret(s) containing the credentials needed to pull images from Docker registries, if needed
  68    - A Kubernetes ConfigMap containing the filebeat.yml file used by the filebeat logging container
  69    - An ExternalName service
  70
  71 ## Input parameters
  72
  73 ### `start` operation parameters
  74
  75 These input parameters are for the `start` `cloudify.interfaces.lifecycle` and are inputs into the variant task operations `create_and_start_container*`.
  76
  77 #### `envs`
  78
  79 A map of environment variables that is intended to be forwarded to the container as environment variables.  Example:
  80
  81 ```yaml
  82 envs:
  83   EXTERNAL_IP: '10.100.1.99'
  84 ```
  85
  86 These environment variables will be forwarded in addition to the *platform-related* environment variables like `CONSUL_HOST`.
  87
  88 #### `volumes`
  89
  90 List of maps used for setting up Kubernetes volume mounts.  Example:
  91
  92 ```yaml
  93 volumes:
  94   - host:
  95       path: '/var/run/docker.sock'
  96     container:
  97       bind: '/tmp/docker.sock'
  98       mode: 'ro'
  99 ```
 100
 101 The table below describes the fields.
 102
 103 key | description
 104 --- | -----------
 105 path | Full path to the file or directory on the host machine to be mounted
 106 bind | Full path to the file or directory in the container where the volume should be mounted to
 107 mode | Readable, writeable: `ro`, `rw`
 108
 109 #### `ports`
 110
 111 List of strings - Used to bind container ports to host ports. Each item is of the format: `<container port>:<host port>` or
 112 <container port>/<protocol>:<host port>, where <protocol> can be "TCP", "tcp", "UDP", or "udp".   If the first format is used, the
 113 protocol defaults to TCP.
 114
 115 Note that `ContainerizedPlatformComponent` has the property pair `host_port` and `container_port`. This pair will be merged with the input parameters ports.
 116
 117 ```yaml
 118 ports:
 119   - '8000:31000'
 120 ```
 121
 122 Default is `None`.
 123
 124 In the Kubernetes environment, most components will communicate over the Kubernetes network using private addresses. For those cases,
 125 setting the `<host port>` to 0 will expose the `<container port>` to other components on the Kubernetes network, but not will not expose any
 126 ports on the Kubernetes host's external interface.    Setting `<host port>` to a non-zero value will expose that port on the external interfaces
 127 of every Kubernetes host in the cluster.  (This uses the Kubernetes `NodePort` service type.)
 128
 129 #### `max_wait`
 130
 131 Integer - seconds to wait for component to become ready before throwing a `NonRecoverableError`. For example:
 132
 133 ```yaml
 134 max_wait:
 135     60
 136 ```
 137
 138 Default is 300 seconds.
 139
 140 ## Using DMaaP
 141
 142 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.
 143
 144 ### Node properties
 145
 146 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.
 147
 148 #### Message router
 149
 150 For message router publishers and subscribers, the objects look like:
 151
 152 ```yaml
 153 name: topic00
 154 location: mtc5
 155 client_role: XXXX
 156 type: message_router
 157 ```
 158
 159 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.
 160
 161 #### Data router
 162
 163 For data router publishers, the object looks like:
 164
 165 ```yaml
 166 name: feed00
 167 location: mtc5
 168 type: data_router
 169 ```
 170
 171 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`.
 172
 173 For data router subscribers, the object looks like:
 174
 175 ```yaml
 176 name: feed00
 177 location: mtc5
 178 type: data_router
 179 username: king
 180 password: "123456"
 181 route: some-path
 182 scheme: https
 183 ```
 184
 185 Where the relationship to use is `dcae.relationships.subscribe_to_files`.
 186
 187 If `username` and `password` are not provided, then the plugin will generate username and password pair.
 188
 189 `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.
 190
 191 `route` is the http path endpoint of the subscriber that will handle files from the associated feed.
 192
 193 `scheme` is either `http` or `https`.  If not specified, then the plugin will default to `http`.
 194
 195 ### Component configuration
 196
 197 The DMaaP plugin is responsible to provision the feed/topic and store into Consul the resulting DMaaP connection details.  Here is an example:
 198
 199 ```json
 200 {
 201     "topic00": {
 202         "client_role": "XXXX",
 203         "client_id": "XXXX",
 204         "location": "XXXX",
 205         "topic_url": "https://some-topic-url.com/events/abc"
 206     }
 207 }
 208 ```
 209
 210 This is to be merged with the templatized application configuration:
 211
 212 ```json
 213 {
 214     "some-param": "Lorem ipsum dolor sit amet",
 215     "streams_subscribes": {
 216         "topic-alpha": {
 217             "type": "message_router",
 218             "aaf_username": "user-foo",
 219             "aaf_password": "password-bar",
 220             "dmaap_info": "<< topic00 >>"
 221         },
 222     },
 223     "streams_publishes": {},
 224     "services_calls": {}
 225 }
 226 ```
 227
 228 To form the application configuration:
 229
 230 ```json
 231 {
 232     "some-param": "Lorem ipsum dolor sit amet",
 233     "streams_subscribes": {
 234         "topic-alpha": {
 235             "type": "message_router",
 236             "aaf_username": "user-foo",
 237             "aaf_password": "password-bar",
 238             "dmaap_info": {
 239                 "client_role": "XXXX",
 240                 "client_id": "XXXX",
 241                 "location": "XXXX",
 242                 "topic_url": "https://some-topic-url.com/events/abc"
 243             }
 244         },
 245     },
 246     "streams_publishes": {},
 247     "services_calls": {}
 248 }
 249 ```
 250
 251 This also applies to data router feeds.
 252
 253 ## Additional Operations Supported by the Plugin
 254 In addition to supporting the Cloudify `install` and `uninstall` workflows, the plugin provides two standalone operations that can be invoked using the Cloudify [`execute_operation` workflow](https://docs.cloudify.co/4.3.0/working_with/workflows/built-in-workflows/).  The `dcae.nodes.ContainerizedApplication`, `dcae.nodes.ContainerizedPlatformComponent`, `dcae.nodes.ContainerizedServiceComponent`, and `dcae.nodes.ContainerizedServiceComponentUsingDmaap` node types support these operations.
 255
 256 Currently, there's no convenient high-level interface to trigger these operations, but they could potentially be exposed through some kind of dashboard.
 257
 258 ### Scaling Operation (`scale`)
 259 The `scale` operation provides a way to change the number of replicas running for a node instance.  The operation is implemented by modifying the number of replicas in the Kubernetes Deployment specification associated with a node instance and submitting the updated specification to the Kubernetes API.  The scale operation works for increasing the number of replicas as well as decreasing the number of replications.  The minimum number of replicas is 1.
 260
 261 The `scale` operation takes two parameters:
 262 - `replicas`: Number of desired replicas. Integer, required.
 263 - `max_wait`: Number of seconds to wait for successful completion of the operation.  Integer, optional, defaults to 300 seconds.
 264
 265 One way to trigger a `scale` operation is by using the Cloudify command line.  For example:
 266 ```
 267 cfy executions start -d my_deployment -p scale_params.yaml execute_operation
 268 ```
 269 where `my_deployment` is the name of an existing Cloudify deployment and
 270 `scale_params.yaml` is a a file containing the operation parameters:
 271 ```
 272 operation: scale
 273 operation_kwargs:
 274     replicas: 3
 275 node_ids:
 276     - "web_server"
 277 ```
 278 Note that the `node_ids` list is required by the `execute_operation` workflow.  The list contains all of the nodes that are being targeted by the workflow.  If a blueprint contains more than one node, it's possible to scale all of them--or some subset--with a single workflow execution.
 279
 280 ### Image Update Operation (`image_update`)
 281 The `update_image` operation provides a way to change the Docker image running for a node instance, using the Kubernetes _rolling update_ strategy.  (See this [tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/) and this [discussion of the concept](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#updating-a-deployment) in the Kubernetes documentation.) The operation is implemented by modifying the image property in the Kubernetes Deployment specification associated with a node instance and submitting the updated specification to the Kubernetes API.
 282
 283 The `update_image` operation takes two parameters:
 284 - `image`: Full name (including registry, if not the default Docker registry, and tag) of the new image to use for the component.  String, required.
 285 - `max_wait`: Number of seconds to wait for successful completion of the operation.  Integer, optional, defaults to 300 seconds.
 286
 287 The `update_image` operation can be triggered using the Cloudify command line.  For example:
 288 ```
 289 cfy executions start -d my_deployment -p update_params.yaml execute_operation
 290 ```
 291 where `my_deployment` is the name of an existing Cloudify deployment and
 292 `update_params.yaml` is a a file containing the operation parameters:
 293 ```
 294 operation: update_image
 295 operation_kwargs:
 296     image: myrepository.example.com/server/web:1.15
 297 node_ids:
 298     - "web_server"
 299 ```
 300 Note that the `node_ids` list is required by the `execute_operation` workflow.  The list contains all of the nodes that are being targeted by the workflow.  For an `update_image` operation, the list typically has only one element.
 301
 302 Note also that the `update_image` operation targets the container running the application code (i.e., the container running the image specified in the `image` node property).  This plugin may deploy "sidecar" containers running supporting code--for example, the "filebeat" container that relays logs to the central log server.  The `update_image` operation does not touch any "sidecar" containers.