docs/sections/guides/development_guides/oom_dev_helm_chart_info.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright 2018-2020 Amdocs, Bell Canada, Orange, Samsung
   5 .. Modification copyright (C) 2022 Nordix Foundation
   6
   7 .. Links
   8 .. _Helm Charts: https://artifacthub.io/packages/search
   9 .. _aai: https://github.com/onap/oom/tree/master/kubernetes/aai
  10 .. _name.tpl: https://github.com/onap/oom/blob/master/kubernetes/common/common/templates/_name.tpl
  11 .. _namespace.tpl: https://github.com/onap/oom/blob/master/kubernetes/common/common/templates/_namespace.tpl
  12
  13 .. _oom_helm_chart_info:
  14
  15 Helm Charts
  16 ###########
  17
  18 A Helm chart is a collection of files that describe a related set of Kubernetes
  19 resources. A simple chart might be used to deploy something simple, like a
  20 memcached pod, while a complex chart might contain many micro-service arranged
  21 in a hierarchy as found in the `aai`_ ONAP component.
  22
  23 Charts are created as files laid out in a particular directory tree, then they
  24 can be packaged into versioned archives to be deployed. There is a public
  25 archive of `Helm Charts`_ on ArtifactHUB that includes many technologies applicable
  26 to ONAP. Some of these charts have been used in ONAP and all of the ONAP charts
  27 have been created following the guidelines provided.
  28
  29 An example structure of the OOM common helm charts is shown below:
  30
  31 .. code-block:: bash
  32
  33   common
  34   ├── cassandra
  35   │   ├── Chart.yaml
  36   │   ├── resources
  37   │   │   ├── config
  38   │   │   │   └── docker-entrypoint.sh
  39   │   │   ├── exec.py
  40   │   │   └── restore.sh
  41   │   ├── templates
  42   │   │   ├── backup
  43   │   │   │   ├── configmap.yaml
  44   │   │   │   ├── cronjob.yaml
  45   │   │   │   ├── pv.yaml
  46   │   │   │   └── pvc.yaml
  47   │   │   ├── configmap.yaml
  48   │   │   ├── pv.yaml
  49   │   │   ├── service.yaml
  50   │   │   └── statefulset.yaml
  51   │   └── values.yaml
  52   ├── common
  53   │   ├── Chart.yaml
  54   │   ├── templates
  55   │   │   ├── _createPassword.tpl
  56   │   │   ├── _ingress.tpl
  57   │   │   ├── _labels.tpl
  58   │   │   ├── _mariadb.tpl
  59   │   │   ├── _name.tpl
  60   │   │   ├── _namespace.tpl
  61   │   │   ├── _repository.tpl
  62   │   │   ├── _resources.tpl
  63   │   │   ├── _secret.yaml
  64   │   │   ├── _service.tpl
  65   │   │   ├── _storage.tpl
  66   │   │   └── _tplValue.tpl
  67   │   └── values.yaml
  68   ├── ...
  69   └── postgres-legacy
  70       ├── Chart.yaml
  71       ├── charts
  72       └── configs
  73
  74 The common section of charts consists of a set of templates that assist with
  75 parameter substitution (`name.tpl`_, `namespace.tpl`_, etc) and a set of
  76 charts for components used throughout ONAP.  When the common components are used
  77 by other charts they are instantiated each time or we can deploy a shared
  78 instances for several components.
  79
  80 All of the ONAP components have charts that follow the pattern shown below:
  81
  82 .. code-block:: bash
  83
  84   name-of-my-component
  85   ├── Chart.yaml
  86   ├── component
  87   │   └── subcomponent-folder
  88   ├── charts
  89   │   └── subchart-folder
  90   ├── resources
  91   │   ├── folder1
  92   │   │   ├── file1
  93   │   │   └── file2
  94   │   └── folder1
  95   │       ├── file3
  96   │       └── folder3
  97   │           └── file4
  98   ├── templates
  99   │   ├── NOTES.txt
 100   │   ├── configmap.yaml
 101   │   ├── deployment.yaml
 102   │   ├── ingress.yaml
 103   │   ├── job.yaml
 104   │   ├── secrets.yaml
 105   │   └── service.yaml
 106   └── values.yaml
 107
 108 Note that the /components sub dir may include a hierarchy of sub
 109 components and in themselves can be quite complex.
 110
 111 You can use either `charts` or `components` folder for your subcomponents.
 112 `charts` folder means that the subcomponent will always been deployed.
 113
 114 `components` folders means we can choose if we want to deploy the subcomponent.
 115
 116 This choice is done in root `values.yaml`:
 117
 118 .. code-block:: yaml
 119
 120   ---
 121   global:
 122     key: value
 123
 124   component1:
 125     enabled: true
 126   component2:
 127     enabled: true
 128
 129 Then in `Chart.yaml` dependencies section, you'll use these values:
 130
 131 .. code-block:: yaml
 132
 133   ---
 134   dependencies:
 135     - name: common
 136       version: ~x.y-0
 137       repository: '@local'
 138     - name: component1
 139       version: ~x.y-0
 140       repository: 'file://components/component1'
 141       condition: component1.enabled
 142     - name: component2
 143       version: ~x.y-0
 144       repository: 'file://components/component2'
 145       condition: component2.enabled
 146
 147 Configuration of the components varies somewhat from component to component but
 148 generally follows the pattern of one or more `configmap.yaml` files which can
 149 directly provide configuration to the containers in addition to processing
 150 configuration files stored in the `config` directory.  It is the responsibility
 151 of each ONAP component team to update these configuration files when changes
 152 are made to the project containers that impact configuration.
 153
 154 The following section describes how the hierarchical ONAP configuration system
 155 is key to management of such a large system.
 156
 157
 158 .. MISC
 159 .. ====
 160 .. Note that although OOM uses Kubernetes facilities to minimize the effort
 161 .. required of the ONAP component owners to implement a successful rolling
 162 .. upgrade strategy there are other considerations that must be taken into
 163 .. consideration.
 164 .. For example, external APIs - both internal and external to ONAP - should be
 165 .. designed to gracefully accept transactions from a peer at a different
 166 .. software version to avoid deadlock situations. Embedded version codes in
 167 .. messages may facilitate such capabilities.
 168 ..
 169 .. Within each of the projects a new configuration repository contains all of
 170 .. the project specific configuration artifacts.  As changes are made within
 171 .. the project, it's the responsibility of the project team to make appropriate
 172 .. changes to the configuration data.