docs/installation/oom.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5
   6 Policy/ACM OOM Installation
   7 ---------------------------
   8
   9 .. contents::
  10     :depth: 2
  11
  12 Notes
  13 *****
  14 * This guide assumes that you have access to a Kubernetes cluster.
  15 * The examples for this guide were carried out on a 3 node Ubuntu-based cluster. However, cluster software such as microk8s should work just as well.
  16
  17 Cluster Used in this Guide
  18 **************************
  19 * Ubuntu-based cluster using Ubuntu 20.04.1 LTS
  20 * 3 nodes - each having 8GB RAM and 4CPU
  21
  22 Prerequisites
  23 *************
  24 * K8s Cluster capable of running kubectl commands
  25 * Both kubectl client and the server use v1.22.4
  26 * Helm version v3.6.3 is installed
  27 * There should be a running chart repo called "local"
  28 * Chartmuseum used to create the chart repo
  29
  30 Deploy Policy/ACM OOM & Required Charts
  31 ***************************************
  32 The policy K8S charts are located in the `OOM repository <https://gerrit.onap.org/r/gitweb?p=oom.git;a=tree;f=kubernetes/policy;h=78576c7a0d30cb87054e9776326cdde20986e6e3;hb=refs/heads/master>`_.
  33
  34 Install Helm Plugins
  35 ^^^^^^^^^^^^^^^^^^^^
  36 Chart museum's **helm-push** plugin should be installed
  37
  38 .. code-block:: bash
  39
  40     helm plugin install https://github.com/chartmuseum/helm-push --version 0.10.3
  41
  42 And then we should install the **deploy** and **undeploy** plugins from oom. so, navigate to the oom/kubernetes directory in the above cloned oom gerrit repo.
  43
  44 .. code-block:: bash
  45
  46     helm plugin install helm/plugins/deploy
  47     helm plugin install helm/plugins/undeploy
  48
  49 Package and Upload Charts to Repo
  50 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  51 Navigate to the same oom/kubernetes directory. The **make** command can be used here to package and upload (among other things) the charts to the local chart repo. This command is slow as it has to package and upload all of the helm charts in oom. However, we are skipping linting of the charts and using the **-j** flag to allow us to use multiple threads - this will maximize the speed.
  52
  53 .. code-block:: bash
  54
  55     make all SKIP_LINT=TRUE -j$(nproc)
  56
  57 Once this is completed, we should be able to see all of the charts in the local helm repo.
  58
  59 .. code-block:: bash
  60
  61     helm search repo local
  62
  63     local/policy                        12.0.0                          ONAP Policy
  64     local/policy-apex-pdp               12.0.0                          ONAP Policy APEX PDP
  65     local/policy-api                    12.0.0                          ONAP Policy Design API
  66     local/policy-clamp-ac-a1pms-ppnt    12.0.0                          ONAP Policy Clamp A1PMS Participant
  67     local/policy-clamp-ac-http-ppnt     12.0.0                          ONAP Policy Clamp Controlloop Http Participant
  68     local/policy-clamp-ac-k8s-ppnt      12.0.0                          ONAP Policy Clamp Controlloop K8s Participant
  69     local/policy-clamp-ac-kserve-ppnt   12.0.0                          ONAP Policy Clamp Kserve Participant
  70     local/policy-clamp-ac-pf-ppnt       12.0.0                          ONAP Policy Clamp Controlloop Policy Participant
  71     local/policy-clamp-runtime-acm      12.0.0                          ONAP Policy Clamp Controlloop Runtime
  72     local/policy-distribution           12.0.0                          ONAP Policy Distribution
  73     local/policy-drools-pdp             12.0.0                          ONAP Drools Policy Engine (PDP-D)
  74     local/policy-pap                    12.0.0                          ONAP Policy Administration (PAP)
  75     local/policy-xacml-pdp              12.0.0                          ONAP Policy XACML PDP (PDP-X)
  76
  77 .. note::
  78     Only the policy/acm charts are shown above - there will be many others.
  79
  80 Strimzi Kafka and Cert Manager Install
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82 Install Cert Manager
  83
  84 .. code-block:: bash
  85
  86     kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.2.0/cert-manager.yaml
  87
  88 Currently, the following policy/acm components use Strimzi Kafka by default:
  89
  90 * policy-ppnt
  91 * k8s-ppnt
  92 * http-ppnt
  93 * a1Policy-mgmt-ppnt
  94 * kserve-ppnt
  95 * acm runtime
  96
  97 There is a future plan to move all components to Strimzi Kafka. However, in the meantime, our deployments require both DMAAP message-router and Strimzi Kafka
  98 |
  99 Install Strimzi Kafka Operator
 100
 101 .. code-block:: bash
 102
 103     helm repo add strimzi https://strimzi.io/charts/
 104     helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version 0.32.0 --set watchAnyNamespace=true --create-namespace
 105
 106 Once these are installed and running, we can move on to the installation of the policy and related helm charts
 107
 108 Policy and Related Helm Chart Install
 109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 110 At this stage, we have all the required charts that we need for either Policy Framework or ACM installation. The command to deploy the charts is below
 111
 112 .. code-block:: bash
 113
 114     helm deploy dev local/onap --namespace onap -f ~/override.yaml --create-namespace
 115
 116 In the above **helm deploy** command we provide an override file called **override.yaml**. In this file, we can turn on/off different parts of the onap installation. we have provided 2 different override files below in the collapsable code. One is for just the policy components and requirements. One is for the ACM components and requirements. These are provided just as examples - you can adjust any way you see fit.
 117
 118 .. collapse:: Policy Chart Override
 119
 120     .. code-block:: yaml
 121
 122         global:
 123           repository: nexus3.onap.org:10001
 124           pullPolicy: IfNotPresent
 125           masterPassword: password
 126           serviceMesh:
 127             enabled: false
 128           cmpv2Enabled: false
 129           addTestingComponents: false
 130         robot:
 131           enabled: false
 132         so:
 133           enabled: false
 134         cassandra:
 135           enabled: false
 136         mariadb-galera:
 137           enabled: true
 138           replicaCount: 1
 139         appc:
 140           enabled: false
 141         sdnc:
 142           enabled: false
 143           replicaCount: 1
 144           config:
 145             enableClustering: false
 146         aaf:
 147           enabled: false
 148         aai:
 149           enabled: false
 150         clamp:
 151           enabled: false
 152         cli:
 153           enabled: false
 154         cds:
 155           enabled: false
 156         consul:
 157           enabled: false
 158         contrib:
 159           enabled: false
 160         awx:
 161           enabled: false
 162         netbox:
 163           enabled: false
 164         dcaegen2:
 165           enabled: false
 166         pnda:
 167           enabled: false
 168         dmaap:
 169           enabled: true
 170           message-router:
 171             enabled: true
 172           dmaap-bc:
 173             enabled: false
 174           dmaap-dr-prov:
 175             enabled: false
 176           dmaap-dr-node:
 177             enabled: false
 178           dmaap-strimzi:
 179             enabled: false
 180         esr:
 181           enabled: false
 182         log:
 183           enabled: false
 184         sniro-emulator:
 185           enabled: false
 186         oof:
 187           enabled: false
 188         msb:
 189           enabled: false
 190         multicloud:
 191           enabled: false
 192         nbi:
 193           enabled: false
 194         pomba:
 195           enabled: false
 196         portal:
 197           enabled: false
 198         platform:
 199           enabled: false
 200         sdc:
 201           enabled: false
 202         uui:
 203           enabled: false
 204         vfc:
 205           enabled: false
 206         vid:
 207           enabled: false
 208         modeling:
 209           enabled: false
 210         cps:
 211           enabled: false
 212         vnfsdk:
 213           enabled: false
 214         vvp:
 215           enabled: false
 216         strimzi:
 217           enabled: true
 218           replicaCount: 1
 219           persistence:
 220             kafka:
 221               size: 1Gi
 222             zookeeper:
 223               size: 256Mi
 224           strimzi-kafka-bridge:
 225             enabled: false
 226         policy:
 227           enabled: true
 228           policy-clamp-ac-a1pms-ppnt:
 229             enabled: false
 230           policy-clamp-ac-k8s-ppnt:
 231             enabled: false
 232           policy-clamp-ac-http-ppnt:
 233             enabled: false
 234           policy-clamp-ac-pf-ppnt:
 235             enabled: false
 236           policy-clamp-runtime-acm:
 237             enabled: false
 238           policy-gui:
 239             enabled: false
 240           policy-apex-pdp:
 241             enabled: true
 242           policy-nexus:
 243             enabled: false
 244           policy-api:
 245             enabled: true
 246           policy-pap:
 247             enabled: true
 248           policy-xacml-pdp:
 249             enabled: true
 250           policy-drools-pdp:
 251             enabled: true
 252           policy-distribution:
 253             enabled: true
 254
 255 .. collapse:: ACM Chart Override
 256
 257     .. code-block:: yaml
 258
 259         global:
 260           repository: nexus3.onap.org:10001
 261           pullPolicy: IfNotPresent
 262           masterPassword: password
 263           serviceMesh:
 264             enabled: false
 265           cmpv2Enabled: false
 266           addTestingComponents: false
 267         robot:
 268           enabled: false
 269         so:
 270           enabled: false
 271         cassandra:
 272           enabled: false
 273         mariadb-galera:
 274           enabled: true
 275           replicaCount: 1
 276         appc:
 277           enabled: false
 278         sdnc:
 279           enabled: false
 280           replicaCount: 1
 281           config:
 282             enableClustering: false
 283         aaf:
 284           enabled: false
 285         aai:
 286           enabled: false
 287         clamp:
 288           enabled: false
 289         cli:
 290           enabled: false
 291         cds:
 292           enabled: false
 293         consul:
 294           enabled: false
 295         contrib:
 296           enabled: false
 297         awx:
 298           enabled: false
 299         netbox:
 300           enabled: false
 301         dcaegen2:
 302           enabled: false
 303         pnda:
 304           enabled: false
 305         dmaap:
 306           enabled: true
 307           message-router:
 308             enabled: true
 309           dmaap-bc:
 310             enabled: false
 311           dmaap-dr-prov:
 312             enabled: false
 313           dmaap-dr-node:
 314             enabled: false
 315           dmaap-strimzi:
 316             enabled: false
 317         esr:
 318           enabled: false
 319         log:
 320           enabled: false
 321         sniro-emulator:
 322           enabled: false
 323         oof:
 324           enabled: false
 325         msb:
 326           enabled: false
 327         multicloud:
 328           enabled: false
 329         nbi:
 330           enabled: false
 331         pomba:
 332           enabled: false
 333         portal:
 334           enabled: false
 335         platform:
 336           enabled: false
 337         sdc:
 338           enabled: false
 339         uui:
 340           enabled: false
 341         vfc:
 342           enabled: false
 343         vid:
 344           enabled: false
 345         modeling:
 346           enabled: false
 347         cps:
 348           enabled: false
 349         vnfsdk:
 350           enabled: false
 351         vvp:
 352           enabled: false
 353         strimzi:
 354           enabled: true
 355           replicaCount: 1
 356           persistence:
 357             kafka:
 358               size: 1Gi
 359             zookeeper:
 360               size: 256Mi
 361           strimzi-kafka-bridge:
 362             enabled: false
 363         policy:
 364           enabled: true
 365           policy-clamp-ac-a1pms-ppnt:
 366             enabled: true
 367           policy-clamp-ac-k8s-ppnt:
 368             enabled: true
 369           policy-clamp-ac-http-ppnt:
 370             enabled: true
 371           policy-clamp-ac-pf-ppnt:
 372             enabled: true
 373           policy-clamp-runtime-acm:
 374             enabled: true
 375           policy-gui:
 376             enabled: false
 377           policy-apex-pdp:
 378             enabled: false
 379           policy-nexus:
 380             enabled: false
 381           policy-api:
 382             enabled: true
 383           policy-pap:
 384             enabled: true
 385           policy-xacml-pdp:
 386             enabled: false
 387           policy-drools-pdp:
 388             enabled: false
 389           policy-distribution:
 390             enabled: false
 391
 392 |
 393
 394 Policy/ACM Pods
 395 ***************
 396 To get a listing of the Policy or ACM Pods, run the following command:
 397
 398 .. code-block:: bash
 399
 400   kubectl get pods -n onap | grep dev-policy
 401
 402   dev-policy-59684c7b9c-5gd6r                        2/2     Running            0          8m41s
 403   dev-policy-apex-pdp-0                              1/1     Running            0          8m41s
 404   dev-policy-api-56f55f59c5-nl5cg                    1/1     Running            0          8m41s
 405   dev-policy-distribution-54cc59b8bd-jkg5d           1/1     Running            0          8m41s
 406   dev-policy-mariadb-0                               1/1     Running            0          8m41s
 407   dev-policy-xacml-pdp-765c7d58b5-l6pr7              1/1     Running            0          8m41s
 408
 409 .. note::
 410    To get a listing of the Policy services, run this command:
 411    kubectl get svc -n onap | grep policy
 412
 413 Accessing Policy/ACM Containers
 414 *******************************
 415 Accessing the policy docker containers is the same as for any kubernetes container. Here is an example:
 416
 417 .. code-block:: bash
 418
 419   kubectl -n onap exec -it dev-policy-policy-xacml-pdp-584844b8cf-9zptx bash
 420
 421 .. _install-upgrade-policy-label:
 422
 423 Installing or Upgrading Policy/ACM
 424 **********************************
 425 The assumption is you have cloned the charts from the OOM repository into a local directory.
 426
 427 **Step 1** Go into local copy of OOM charts
 428
 429 From your local copy, edit any of the values.yaml files in the policy tree to make desired changes.
 430
 431 The policy schema will be installed automatically as part of the database configuration using ``db-migrator``.
 432 By default the policy schema is upgraded to the latest version.
 433 For more information on how to change the ``db-migrator`` setup please see
 434 :ref:`Using Policy DB Migrator <policy-db-migrator-label>`.
 435
 436 **Step 2** Build the charts
 437
 438 .. code-block:: bash
 439
 440   make policy -j$(nproc)
 441   make SKIP_LINT=TRUE onap -j$(nproc)
 442
 443 .. note::
 444    SKIP_LINT is only to reduce the "make" time. **-j** allows the use of multiple threads.
 445
 446 **Step 3** Undeploy Policy/ACM
 447 After undeploying policy, loop on monitoring the policy pods until they go away.
 448
 449 .. code-block:: bash
 450
 451   helm undeploy dev-policy
 452   kubectl get pods -n onap | grep dev-policy
 453
 454
 455 **Step 4** Re-Deploy Policy pods
 456
 457 After deploying policy, loop on monitoring the policy pods until they come up.
 458
 459 .. code-block:: bash
 460
 461   helm deploy dev-policy local/onap --namespace onap
 462   kubectl get pods -n onap | grep dev-policy
 463
 464 .. note::
 465    If you want to purge the existing data and start with a clean install,
 466    please follow these steps after undeploying:
 467
 468    **Step 1** Delete NFS persisted data for Policy
 469
 470    .. code-block:: bash
 471
 472      rm -fr /dockerdata-nfs/dev/policy
 473
 474    **Step 2** Make sure there is no orphan policy database persistent volume or claim.
 475
 476    First, find if there is an orphan database PV or PVC with the following commands:
 477
 478    .. code-block:: bash
 479
 480      kubectl get pvc -n onap | grep policy
 481      kubectl get pv -n onap | grep policy
 482
 483    If there are any orphan resources, delete them with
 484
 485    .. code-block:: bash
 486
 487        kubectl delete pvc <orphan-policy-mariadb-resource>
 488        kubectl delete pv <orphan-policy-mariadb-resource>
 489
 490
 491 Restarting a faulty component
 492 *****************************
 493 Each policy component can be restarted independently by issuing the following command:
 494
 495 .. code-block:: bash
 496
 497     kubectl delete pod <policy-pod> -n onap
 498
 499 Exposing ports
 500 **************
 501 For security reasons, the ports for the policy containers are configured as ClusterIP and thus not exposed. If you find you need those ports in a development environment, then the following will expose them.
 502
 503 .. code-block:: bash
 504
 505   kubectl -n onap expose service policy-api --port=7171 --target-port=6969 --name=api-public --type=NodePort
 506
 507 Additional PDP-D Customizations
 508 *******************************
 509
 510 Credentials and other configuration parameters can be set as values
 511 when deploying the policy (drools) subchart.  Please refer to
 512 `PDP-D Default Values <https://git.onap.org/oom/tree/kubernetes/policy/components/policy-drools-pdp/values.yaml>`_
 513 for the current default values.  It is strongly recommended that sensitive
 514 information is secured appropriately before using in production.
 515
 516 Additional customization can be applied to the PDP-D.  Custom configuration goes under the
 517 "resources" directory of the drools subchart (oom/kubernetes/policy/charts/drools/resources).
 518 This requires rebuilding the policy subchart
 519 (see section :ref:`install-upgrade-policy-label`).
 520
 521 Configuration is done by adding or modifying configmaps and/or secrets.
 522 Configmaps are placed under "drools/resources/configmaps", and
 523 secrets under "drools/resources/secrets".
 524
 525 Custom configuration supportes these types of files:
 526
 527 * **\*.conf** files to support additional environment configuration.
 528 * **features\*.zip** to add additional custom features.
 529 * **\*.pre.sh** scripts to be executed before starting the PDP-D process.
 530 * **\*.post.sh** scripts to be executed after starting the PDP-D process.
 531 * **policy-keystore** to override the PDP-D policy-keystore.
 532 * **policy-truststore** to override the PDP-D policy-truststore.
 533 * **aaf-cadi.keyfile** to override the PDP-D AAF key.
 534 * **\*.properties** to override or add properties files.
 535 * **\*.xml** to override or add xml configuration files.
 536 * **\*.json** to override json configuration files.
 537 * **\*settings.xml** to override maven repositories configuration .
 538
 539 Examples
 540 ^^^^^^^^
 541 To *override the PDP-D keystore or trustore*, add a suitable replacement(s) under
 542 "drools/resources/secrets".  Modify the drools chart values.yaml with
 543 new credentials, and follow the procedures described at
 544 :ref:`install-upgrade-policy-label` to redeploy the chart.
 545
 546 To *disable https* for the DMaaP configuration topic, add a copy of
 547 `engine.properties <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server/config/engine.properties>`_
 548 with "dmaap.source.topics.PDPD-CONFIGURATION.https" set to "false", or alternatively
 549 create a ".pre.sh" script (see above) that edits this file before the PDP-D is
 550 started.
 551
 552 To use *noop topics* for standalone testing, add a "noop.pre.sh" script under
 553 oom/kubernetes/policy/charts/drools/resources/configmaps/:
 554
 555 .. code-block:: bash
 556
 557     #!/bin/bash
 558     sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties
 559