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 VM using Ubuntu 22.04.1 LTS
  20 * VM has 16GB RAM and 150 GB HDD and 4CPU
  21 * microk8s-based cluster is used
  22
  23 Prerequisites
  24 *************
  25 * Microk8s Cluster capable of running kubectl commands
  26 * Both kubectl client and the server use v1.30.4
  27 * Helm version v3.15.4 is installed
  28 * There should be a running chart repo called "local"
  29 * Chartmuseum used to create the chart repo
  30
  31 Deploy Policy/ACM OOM & Required Charts
  32 ***************************************
  33 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>`_.
  34
  35 Install Helm Plugins
  36 ^^^^^^^^^^^^^^^^^^^^
  37 Chart museum's **helm-push** plugin should be installed
  38
  39 .. code-block:: bash
  40
  41     helm plugin install https://github.com/chartmuseum/helm-push --version 0.10.3
  42
  43 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.
  44
  45 .. code-block:: bash
  46
  47     helm plugin install helm/plugins/deploy
  48     helm plugin install helm/plugins/undeploy
  49
  50 Package and Upload Charts to Repo
  51 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  52 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.
  53
  54 .. code-block:: bash
  55
  56     make all SKIP_LINT=TRUE -j$(nproc)
  57
  58 Once this is completed, we should be able to see all of the charts in the local helm repo.
  59
  60 .. code-block:: bash
  61
  62     helm search repo local
  63
  64     local/policy                        14.0.5                          ONAP Policy
  65     local/policy-apex-pdp               14.0.1                          ONAP Policy APEX PDP
  66     local/policy-api                    14.0.2                          ONAP Policy Design API
  67     local/policy-clamp-ac-a1pms-ppnt    14.0.1                          ONAP Policy Clamp A1PMS Participant
  68     local/policy-clamp-ac-http-ppnt     14.0.1                          ONAP Policy Clamp Controlloop Http Participant
  69     local/policy-clamp-ac-k8s-ppnt      14.0.1                          ONAP Policy Clamp Controlloop K8s Participant
  70     local/policy-clamp-ac-kserve-ppnt   14.0.1                          ONAP Policy Clamp Kserve Participant
  71     local/policy-clamp-ac-pf-ppnt       14.0.1                          ONAP Policy Clamp Controlloop Policy Participant
  72     local/policy-clamp-runtime-acm      14.0.2                          ONAP Policy Clamp Controlloop Runtime
  73     local/policy-distribution           14.0.1                          ONAP Policy Distribution
  74     local/policy-drools-pdp             14.0.2                          ONAP Drools Policy Engine (PDP-D)
  75     local/policy-pap                    14.0.2                          ONAP Policy Administration (PAP)
  76     local/policy-xacml-pdp              14.0.3                          ONAP Policy XACML PDP (PDP-X)
  77
  78 .. note::
  79     Only the policy/acm charts are shown above - there will be many others.
  80
  81 Strimzi Kafka and Cert Manager Install
  82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  83 Install Cert Manager
  84
  85 .. code-block:: bash
  86
  87     kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.2.0/cert-manager.yaml
  88
  89 Currently, the following policy/acm components use Strimzi Kafka by default:
  90
  91 * policy-ppnt
  92 * k8s-ppnt
  93 * http-ppnt
  94 * a1Policy-mgmt-ppnt
  95 * kserve-ppnt
  96 * acm runtime
  97
  98 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
  99 |
 100 Install Strimzi Kafka Operator
 101
 102 .. code-block:: bash
 103
 104     helm repo add strimzi https://strimzi.io/charts/
 105     helm install strimzi-kafka-operator strimzi/strimzi-kafka-operator --namespace strimzi-system --version 0.43.0 --set watchAnyNamespace=true --create-namespace
 106
 107 Once these are installed and running, we can move on to the installation of the policy and related helm charts
 108
 109 Policy and Related Helm Chart Install
 110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 111 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
 112
 113 .. code-block:: bash
 114
 115     helm deploy dev local/onap --namespace onap -f ~/override.yaml --create-namespace
 116
 117 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 an file below in the collapsable code. This is provided just as examples - you can adjust any way you see fit. The choice between postgres and mariadb is controlled by **global.mariadbGalera.localCluster & global.mariadbGalera.useInPolicy** for mariadb and **global.postgres.localCluster & global.postgres.useInPolicy** for postgres
 118
 119 .. collapse:: Policy/ACM Chart Override
 120
 121     .. code-block:: yaml
 122
 123         global:
 124           repository: nexus3.onap.org:10001
 125           pullPolicy: IfNotPresent
 126           masterPassword: password
 127           serviceMesh:
 128             enabled: false
 129           cmpv2Enabled: false
 130           addTestingComponents: false
 131           useStrimziKafka: true
 132           useStrimziKafkaPf: false
 133           mariadbGalera:
 134             # flag to enable the DB creation via mariadb-operator
 135             useOperator: false
 136             # if useOperator set to "true", set "enableServiceAccount to "false"
 137             # as the SA is created by the Operator
 138             enableServiceAccount: true
 139             localCluster: true
 140             # '&mariadbConfig' means we "store" the values for  later use in the file
 141             # with '*mariadbConfig' pointer.
 142             config: &mariadbConfig
 143               mysqlDatabase: policyadmin
 144             service: &mariadbService policy-mariadb
 145             internalPort: 3306
 146             nameOverride: *mariadbService
 147             # (optional) if localCluster=false and an external secret is used set this variable
 148             #userRootSecret: <secretName>
 149             useInPolicy: true
 150           prometheusEnabled: false
 151           postgres:
 152             localCluster: false
 153             service:
 154               name: pgset
 155               name2: policy-pg-primary
 156               name3: policy-pg-replica
 157             container:
 158               name: postgres
 159             useInPolicy: false
 160         robot:
 161           enabled: false
 162         so:
 163           enabled: false
 164         cassandra:
 165           enabled: false
 166         mariadb-galera:
 167           enabled: false
 168           replicaCount: 1
 169         appc:
 170           enabled: false
 171         sdnc:
 172           enabled: false
 173           replicaCount: 1
 174           config:
 175             enableClustering: false
 176         aaf:
 177           enabled: false
 178         aai:
 179           enabled: false
 180         clamp:
 181           enabled: false
 182         cli:
 183           enabled: false
 184         cds:
 185           enabled: false
 186         consul:
 187           enabled: false
 188         contrib:
 189           enabled: false
 190         awx:
 191           enabled: false
 192         netbox:
 193           enabled: false
 194         dcaegen2:
 195           enabled: false
 196         pnda:
 197           enabled: false
 198         dmaap:
 199           enabled: false
 200           message-router:
 201             enabled: false
 202           dmaap-bc:
 203             enabled: false
 204           dmaap-dr-prov:
 205             enabled: false
 206           dmaap-dr-node:
 207             enabled: false
 208           dmaap-strimzi:
 209             enabled: false
 210         esr:
 211           enabled: false
 212         log:
 213           enabled: false
 214         sniro-emulator:
 215           enabled: false
 216         oof:
 217           enabled: false
 218         msb:
 219           enabled: false
 220         multicloud:
 221           enabled: false
 222         nbi:
 223           enabled: false
 224         pomba:
 225           enabled: false
 226         portal:
 227           enabled: false
 228         platform:
 229           enabled: false
 230         sdc:
 231           enabled: false
 232         uui:
 233           enabled: false
 234         vfc:
 235           enabled: false
 236         vid:
 237           enabled: false
 238         modeling:
 239           enabled: false
 240         cps:
 241           enabled: false
 242         vnfsdk:
 243           enabled: false
 244         vvp:
 245           enabled: false
 246         strimzi:
 247           enabled: true
 248           replicaCount: 1
 249           persistence:
 250             kafka:
 251               size: 1Gi
 252             zookeeper:
 253               size: 256Mi
 254           strimzi-kafka-bridge:
 255             enabled: false
 256         policy:
 257           enabled: true
 258           policy-clamp-ac-a1pms-ppnt:
 259             enabled: true
 260           policy-clamp-ac-kserve-ppnt:
 261             enabled: true
 262           policy-clamp-ac-k8s-ppnt:
 263             enabled: true
 264           policy-clamp-ac-http-ppnt:
 265             enabled: true
 266           policy-clamp-ac-pf-ppnt:
 267             enabled: true
 268           policy-clamp-runtime-acm:
 269             enabled: true
 270           policy-gui:
 271             enabled: false
 272           policy-apex-pdp:
 273             enabled: true
 274           policy-nexus:
 275             enabled: false
 276           policy-api:
 277             enabled: true
 278           policy-pap:
 279             enabled: true
 280           policy-xacml-pdp:
 281             enabled: true
 282           policy-drools-pdp:
 283             enabled: true
 284           policy-distribution:
 285             enabled: false
 286
 287 |
 288
 289 Policy/ACM Pods
 290 ***************
 291 To get a listing of the Policy or ACM Pods, run the following command:
 292
 293 .. code-block:: bash
 294
 295   kubectl get pods -n onap | grep dev-policy
 296
 297   dev-policy-59684c7b9c-5gd6r                        2/2     Running            0          8m41s
 298   dev-policy-apex-pdp-0                              1/1     Running            0          8m41s
 299   dev-policy-api-56f55f59c5-nl5cg                    1/1     Running            0          8m41s
 300   dev-policy-distribution-54cc59b8bd-jkg5d           1/1     Running            0          8m41s
 301   dev-policy-mariadb-0                               1/1     Running            0          8m41s
 302   dev-policy-xacml-pdp-765c7d58b5-l6pr7              1/1     Running            0          8m41s
 303
 304 .. note::
 305    To get a listing of the Policy services, run this command:
 306    kubectl get svc -n onap | grep policy
 307
 308 Accessing Policy/ACM Containers
 309 *******************************
 310 Accessing the policy docker containers is the same as for any kubernetes container. Here is an example:
 311
 312 .. code-block:: bash
 313
 314   kubectl -n onap exec -it dev-policy-policy-xacml-pdp-584844b8cf-9zptx bash
 315
 316 .. _install-upgrade-policy-label:
 317
 318 Installing or Upgrading Policy/ACM
 319 **********************************
 320 The assumption is you have cloned the charts from the OOM repository into a local directory.
 321
 322 **Step 1** Go into local copy of OOM charts
 323
 324 From your local copy, edit any of the values.yaml files in the policy tree to make desired changes.
 325
 326 The policy/acm schemas will be installed automatically as part of the database configuration using ``db-migrator``.
 327 By default the policy/acm schemas is upgraded to the latest version.
 328 For more information on how to change the ``db-migrator`` setup please see
 329 :ref:`Using Policy DB Migrator <policy-db-migrator-label>`.
 330
 331 **Step 2** Build the charts
 332
 333 .. code-block:: bash
 334
 335   make policy -j$(nproc)
 336   make SKIP_LINT=TRUE onap -j$(nproc)
 337
 338 .. note::
 339    SKIP_LINT is only to reduce the "make" time. **-j** allows the use of multiple threads.
 340
 341 **Step 3** Undeploy Policy/ACM
 342 After undeploying policy, loop on monitoring the policy pods until they go away.
 343
 344 .. code-block:: bash
 345
 346   helm undeploy dev
 347   kubectl get pods -n onap | grep dev
 348
 349
 350 **Step 4** Re-Deploy Policy pods
 351
 352 After deploying policy, loop on monitoring the policy pods until they come up.
 353
 354 .. code-block:: bash
 355
 356   helm deploy dev local/onap --namespace onap -f override.yaml
 357   kubectl get pods -n onap | grep dev
 358
 359 .. note::
 360    If you want to purge the existing data and start with a clean install,
 361    please follow these steps after undeploying:
 362
 363    **Step 1** Delete NFS persisted data for Policy
 364
 365    .. code-block:: bash
 366
 367      rm -fr /dockerdata-nfs/dev/policy
 368
 369    **Step 2** Make sure there is no orphan policy database persistent volume or claim.
 370
 371    First, find if there is an orphan database PV or PVC with the following commands:
 372
 373    .. code-block:: bash
 374
 375      kubectl get pvc -n onap | grep policy
 376      kubectl get pv -n onap | grep policy
 377
 378    If there are any orphan resources, delete them with
 379
 380    .. code-block:: bash
 381
 382        kubectl delete pvc <orphan-policy-mariadb-resource>
 383        kubectl delete pv <orphan-policy-mariadb-resource>
 384
 385
 386 Restarting a faulty component
 387 *****************************
 388 Each policy component can be restarted independently by issuing the following command:
 389
 390 .. code-block:: bash
 391
 392     kubectl delete pod <policy-pod> -n onap
 393
 394 Exposing ports
 395 **************
 396 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.
 397
 398 .. code-block:: bash
 399
 400   kubectl -n onap expose service policy-api --port=7171 --target-port=6969 --name=api-public --type=NodePort
 401
 402 Additional PDP-D Customizations
 403 *******************************
 404
 405 Credentials and other configuration parameters can be set as values
 406 when deploying the policy (drools) subchart.  Please refer to
 407 `PDP-D Default Values <https://git.onap.org/oom/tree/kubernetes/policy/components/policy-drools-pdp/values.yaml>`_
 408 for the current default values.  It is strongly recommended that sensitive
 409 information is secured appropriately before using in production.
 410
 411 Additional customization can be applied to the PDP-D.  Custom configuration goes under the
 412 "resources" directory of the drools subchart (oom/kubernetes/policy/charts/drools/resources).
 413 This requires rebuilding the policy subchart
 414 (see section :ref:`install-upgrade-policy-label`).
 415
 416 Configuration is done by adding or modifying configmaps and/or secrets.
 417 Configmaps are placed under "drools/resources/configmaps", and
 418 secrets under "drools/resources/secrets".
 419
 420 Custom configuration supportes these types of files:
 421
 422 * **\*.conf** files to support additional environment configuration.
 423 * **features\*.zip** to add additional custom features.
 424 * **\*.pre.sh** scripts to be executed before starting the PDP-D process.
 425 * **\*.post.sh** scripts to be executed after starting the PDP-D process.
 426 * **policy-keystore** to override the PDP-D policy-keystore.
 427 * **policy-truststore** to override the PDP-D policy-truststore.
 428 * **aaf-cadi.keyfile** to override the PDP-D AAF key.
 429 * **\*.properties** to override or add properties files.
 430 * **\*.xml** to override or add xml configuration files.
 431 * **\*.json** to override json configuration files.
 432 * **\*settings.xml** to override maven repositories configuration .
 433
 434 Examples
 435 ^^^^^^^^
 436 To *override the PDP-D keystore or trustore*, add a suitable replacement(s) under
 437 "drools/resources/secrets".  Modify the drools chart values.yaml with
 438 new credentials, and follow the procedures described at
 439 :ref:`install-upgrade-policy-label` to redeploy the chart.