docs/sections/services/ves-http/installation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 Installation
   5 ============
   6
   7 VESCollector is installed via cloudify blueprint by DCAE bootstrap process on typical ONAP installation.
   8 As the service is containerized, it can be started on stand-alone mode also.
   9
  10
  11 To run VES Collector container on standalone mode, following parameters are required
  12
  13     ``docker run -d -p 8080:8080/tcp -p 8443:8443/tcp -P -e DMAAPHOST='10.0.11.1' nexus.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector:1.4.5``
  14
  15
  16 DMAAPHOST is required for standalone; for normal platform installed instance the publish URL are obtained from Consul. Below parameters are exposed for DCAE platform (cloudify) deployed instance
  17
  18
  19 - COLLECTOR_IP
  20 - DMAAPHOST - should contain an address to DMaaP, so that event publishing can work
  21 - CBSPOLLTIMER - it should be put in here if we want to automatically fetch configuration from CBS.
  22 - CONSUL_PROTOCOL - Consul protocol by default set to **http**, if it is need to change it then that can be set to different value
  23 - CONSUL_HOST - used with conjunction with CBSPOLLTIMER, should be a host address (without port! e.g my-ip-or-host) where Consul service lies
  24 - CBS_PROTOCOL - Config Binding Service protocol by default set to **http**, if it is need to change it then that can be set to different value
  25 - CONFIG_BINDING_SERVICE - used with conjunction with CBSPOLLTIMER, should be a name of CBS as it is registered in Consul
  26 - HOSTNAME - used with conjunction with CBSPOLLTIMER, should be a name of VESCollector application as it is registered in CBS catalog
  27
  28 These parameters can be configured either by passing command line option during `docker run` call or by specifying environment variables named after command line option name
  29
  30
  31 Authentication Support
  32 ----------------------
  33
  34 VES Collector support following authentication types
  35
  36     * *auth.method=noAuth* default option - no security (http)
  37     * *auth.method=certOnly* is used to enable mutual TLS authentication (https)
  38     * *auth.method=certBasicAuth* is used to enable mutual TLS authentication or/and basic HTTPs authentication
  39     * *auth.method=basicAuth* is used to enable basic HTTPs authentication
  40
  41 Default ONAP deployed VESCOllector is configured for "noAuth". If VESCollector instance need to be deployed with authentication enabled, follow below setup
  42
  43
  44 - Update existing VESCollector deployment to remove nodeport conflict by editing service definition
  45     .. code-block:: bash
  46
  47         kubectl edit svc -n onap xdcae-ves-collector
  48
  49 and remove following entry and save the changes; K8S will update the  service definition default VES instance
  50
  51     .. code-block:: bash
  52
  53               - name: xport-t-8443
  54                 nodePort: 30417
  55                 port: 8443
  56                 protocol: TCP
  57                 targetPort: 8443
  58
  59 - Execute into Bootstrap POD using kubectl command
  60
  61 - Copy blueprint content into DCAE bootstrap POD under /blueprints directory under same file name.
  62
  63 ``k8s-ves-tls.yaml``
  64 --------------------
  65
  66
  67 ::
  68
  69     # ============LICENSE_START====================================================
  70     # =============================================================================
  71     # Copyright (c) 2019 AT&T Intellectual Property. All rights reserved.
  72     # =============================================================================
  73     # Licensed under the Apache License, Version 2.0 (the "License");
  74     # you may not use this file except in compliance with the License.
  75     # You may obtain a copy of the License at
  76     #
  77     #      http://www.apache.org/licenses/LICENSE-2.0
  78     #
  79     # Unless required by applicable law or agreed to in writing, software
  80     # distributed under the License is distributed on an "AS IS" BASIS,
  81     # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  82     # See the License for the specific language governing permissions and
  83     # limitations under the License.
  84     # ============LICENSE_END======================================================
  85
  86     tosca_definitions_version: cloudify_dsl_1_3
  87
  88     imports:
  89       - "http://www.getcloudify.org/spec/cloudify/3.4/types.yaml"
  90       - https://nexus.onap.org/service/local/repositories/raw/content/org.onap.dcaegen2.platform.plugins/R4/k8splugin/1.4.13/k8splugin_types.yaml
  91
  92     inputs:
  93       ves_other_publish_url:
  94         type: string
  95         default: "http://message-router.onap.svc.cluster.local:3904/events/unauthenticated.SEC_OTHER_OUTPUT"
  96       ves_heartbeat_publish_url:
  97         type: string
  98         default: "http://message-router.onap.svc.cluster.local:3904/events/unauthenticated.SEC_HEARTBEAT_OUTPUT"
  99       ves_fault_publish_url:
 100         type: string
 101         default: "http://message-router.onap.svc.cluster.local:3904/events/unauthenticated.SEC_FAULT_OUTPUT"
 102       ves_measurement_publish_url:
 103         type: string
 104         default: "http://message-router.onap.svc.cluster.local:3904/events/unauthenticated.VES_MEASUREMENT_OUTPUT"
 105       ves_notification_publish_url:
 106         type: string
 107         default: "http://message-router.onap.svc.cluster.local:3904/events/unauthenticated.VES_NOTIFICATION_OUTPUT"
 108       ves_pnfRegistration_publish_url:
 109         type: string
 110         default: "http://message-router.onap.svc.cluster.local:3904/events/unauthenticated.VES_PNFREG_OUTPUT"
 111       tag_version:
 112         type: string
 113         default: "nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector:1.4.5"
 114       external_port:
 115         type: string
 116         description: Kubernetes node port on which collector is exposed
 117         default: "30235"
 118       external_tls_port:
 119         type: string
 120         description: Kubernetes node port on which collector is exposed for https
 121         default: "30417"
 122       replicas:
 123         type: integer
 124         description: number of instances
 125         default: 1
 126     node_templates:
 127       ves:
 128         interfaces:
 129           cloudify.interfaces.lifecycle:
 130             start:
 131               inputs:
 132                ports:
 133                  - concat: ["8443:", { get_input: external_tls_port }]
 134         properties:
 135           application_config:
 136             collector.dmaap.streamid: fault=ves-fault|syslog=ves-syslog|heartbeat=ves-heartbeat|measurementsForVfScaling=ves-measurement|measurement=ves-measurement|mobileFlow=ves-mobileflow|other=ves-other|stateChange=ves-statechange|thresholdCrossingAlert=ves-thresholdCrossingAlert|voiceQuality=ves-voicequality|sipSignaling=ves-sipsignaling|notification=ves-notification|pnfRegistration=ves-pnfRegistration
 137             collector.keystore.file.location: /opt/app/VESCollector/etc/keystore
 138             collector.keystore.passwordfile: /opt/app/VESCollector/etc/passwordfile
 139             collector.schema.checkflag: "1"
 140             collector.schema.file: "{\"v1\":\"./etc/CommonEventFormat_27.2.json\",\"v2\":\"./etc/CommonEventFormat_27.2.json\",\"v3\":\"./etc/CommonEventFormat_27.2.json\",\"v4\":\"./etc/CommonEventFormat_27.2.json\",\"v5\":\"./etc/CommonEventFormat_28.4.1.json\",\"v7\":\"./etc/CommonEventFormat_30.0.1.json\"}"
 141             collector.service.port: "8080"
 142             collector.service.secure.port: "8443"
 143             event.transform.flag: "0"
 144             auth.method: certBasicAuth
 145             header.authlist: "sample1,$2a$10$0buh.2WeYwN868YMwnNNEuNEAMNYVU9.FSMJGyIKV3dGET/7oGOi6"
 146             streams_publishes:
 147                 ves-fault:
 148                   dmaap_info:
 149                     topic_url:
 150                       get_input: ves_fault_publish_url
 151                   type: message_router
 152                 ves-measurement:
 153                   dmaap_info:
 154                     topic_url:
 155                       get_input: ves_measurement_publish_url
 156                   type: message_router
 157                 ves-notification:
 158                   dmaap_info:
 159                     topic_url:
 160                       get_input: ves_notification_publish_url
 161                   type: message_router
 162                 ves-pnfRegistration:
 163                   dmaap_info:
 164                     topic_url:
 165                       get_input: ves_pnfRegistration_publish_url
 166                   type: message_router
 167                 ves-heartbeat:
 168                   dmaap_info:
 169                     topic_url:
 170                       get_input: ves_heartbeat_publish_url
 171                   type: message_router
 172                 ves-other:
 173                   dmaap_info:
 174                     topic_url:
 175                       get_input: ves_other_publish_url
 176                   type: message_router
 177             collector.dynamic.config.update.frequency: "5"
 178           #docker_config:
 179           #  healthcheck:
 180           #    endpoint: /healthcheck
 181           #    interval: 15s
 182           #    timeout: 1s
 183           #    type: https
 184           image:
 185             get_input: tag_version
 186           replicas: {get_input: replicas}
 187           name: 'dcae-ves-collector-tls'
 188           dns_name: 'dcae-ves-collector-tls'
 189           log_info:
 190             log_directory: "/opt/app/VESCollector/logs/ecomp"
 191         type: dcae.nodes.ContainerizedPlatformComponent
 192
 193
 194
 195 - Validate blueprint
 196     .. code-block:: bash
 197
 198         cfy blueprints validate /blueprints/k8s-ves-tls.yaml
 199
 200 - Deploy blueprint
 201     .. code-block:: bash
 202
 203         cfy install -b ves-tls -d ves-tls /blueprints/k8s-ves-tls.yaml
 204
 205 To undeploy ves-tls, steps are noted below
 206
 207 - Uninstall running ves-tls and delete deployment
 208     .. code-block:: bash
 209
 210         cfy uninstall ves-tls
 211
 212 The deployment uninstall will also delete the blueprint. In some case you might notice 400 error reported indicating active deployment exist such as below
 213 ** An error occurred on the server: 400: Can't delete blueprint ves-tls - There exist deployments for this blueprint; Deployments ids: ves-tls**
 214
 215 In this case blueprint can be deleted explicitly using this command.
 216
 217     .. code-block:: bash
 218
 219         cfy blueprint delete ves-tls
 220
 221 Known Issue : When VESCollector is required to be deployed with authentication enabled *auth.method=certOnly* or *auth.method: certBasicAuth* or *auth.method: basicAuth*
 222 the blueprint currently disables healthcheck parameters configuration (below). This causes no readiness probe to be deployed in K8S when VES Collector is deployed with authentication enabled.
 223
 224
 225         .. code-block:: bash
 226
 227             docker_config:
 228                 healthcheck:
 229                   endpoint: /healthcheck
 230                   interval: 15s
 231                   timeout: 1s
 232                   type: https
 233
 234
 235 The healthcheck support when VESauthentication is enabled needs a different solution to be worked. This will be worked as future enhancement  (DCAEGEN2-1594)