external-schema-repo-generator/README.md

   1 StndDefined schemas ConfigMap generator
   2 =======================================
   3
   4 ## Description
   5 StndDefined schemas Kubernetes ConfigMap generator is a Makefile with shell scripts: 'generate', 'install', 'clean' ane 'utils'.
   6 This Makefile may be used by VES Collector users to generate and install ConfigMap containing schemas
   7 and mapping file for stndDefined validation in VES pod. Additionally script creates file with snippets containing
   8 auto-generated configuration of volumes finally mounted in VES deployment. Process of generation of ConfigMap spec file
   9 is configurable via environment.config file.
  10
  11 Generator files are available in oom/utils ONAP Gerrit repository under external-schema-repo-generator folder.
  12
  13 ## Requirements and limitations
  14
  15 ### Environment
  16 Target *generate* from Makefile requires stable internet connection to properly clone Git repositories.
  17 Target *install* should be ran on the RKE node, so it can create ConfigMap in the same Kubernetes environment as VES Pod
  18 is installed. It is possible to generate a spec in one environment and move it together with all ConfigMap generator
  19 files to the RKE environment.
  20
  21 ### Repository limitations
  22 When running the script branches from selected repository are being downloaded. Time of script execution depends mostly
  23 on repository size and number of schemas. All .yaml files from selected directory in Git repository will be considered
  24 as schemas and attached to ConfigMap spec.
  25
  26 ### Generator tool files integration
  27 It is recommended to consider files of this tool as a unity and not split them when moving generator through
  28 environments. Generator tool files that are required are located in `generator` directory:
  29 - Makefile
  30 - install.sh
  31 - generate.sh
  32 - utils.sh
  33 - clean.sh
  34 - environment.config
  35 - bin_packing.awk
  36
  37 ## Instruction
  38
  39 ### Parameters description
  40 Before running any target from Makefile, configuration in *environment.config* must be properly prepared. Description of
  41 the configurable properties is below.
  42
  43 - **GENERATION_DIRECTORY** - Directory in which generated files will be located.
  44 - **EXTERNAL_REPO_CONFIGMAP_FILENAME_PREFIX** - Prefix for file name of ConfigMap spec, that will be generated.
  45 - **EXTERNAL_REPO_CONFIGMAP_DIRECTORY** - Directory inside *GENERATION_DIRECTORY*, in which generated specs will be located.
  46 - **EXTERNAL_REPO_CONFIGMAP_NAME_PREFIX** - Prefix for Kubernetes name of ConfigMap, that will be generated and installed.
  47 - **SNIPPET_FILENAME** - Filename of snippet with autogenerated content that should be added to VES deployment.
  48 - **REPOSITORY_URL_HTTPS** - URL to remote Git repository which lets cloning repository via HTTPS.
  49 - **REPOSITORY_BRANCH** - Valid OPEN API branch from selected Git repository which contains schemas desired to mount. Script
  50 accepts an array of branches from which schemas will be collected. To pass an array split branch names with space and
  51 cover list in quotation marks. User can put here 5G_API specific repository tag name related to OPEN API schema branch after colon
  52 for example: Rel-16-SA-91:TSG91-Rel16. Having such information script will clone this specific 5G API branch and merge it
  53 with OPEN API schema. If 5G_API specific repository branch after colon will not be set by user, then script will parse
  54 OPEN API if any reference to 5G_API specific repository is present and get branch name for 5G_API from this reference.
  55 Next clone parsed 5G API branch and merge it with OPEN API schema
  56 - **SCHEMAS_LOCATION** - Path to schemas directory on selected Git repo. All YAML files from this repository will be
  57 considered as schema and added to ConfigMap.
  58
  59 - **VENDOR_NAME** - Name of organisation delivering schemas, used only for naming of schemas destination directory in
  60 VES.
  61
  62 ### Running commands
  63
  64
  65 #### All
  66
  67 To generate and install ConfigMaps run:
  68
  69 ```
  70 make all
  71 ```
  72
  73 #### Generation
  74
  75 To run ConfigMaps spec generation as well as snippet file used for mounting ConfigMap to specific Deployment use:
  76
  77 ```
  78 make generate
  79 ```
  80
  81 #### Installation
  82
  83 To run ConfigMaps installation in Kubernetes use:
  84
  85 **NOTE**: Remember about running this command on RKE node.
  86
  87 ```
  88 make install
  89 ```
  90
  91 **NOTE**: It is possible that ConfigMap with selected K8S_CONFIGMAP_NAME already exists in Kubernetes.
  92 In such situation existing ConfigMap will be replaced.
  93
  94 **NOTE**: If ConfigMap is bigger than one megabyte it won't be installed
  95 and warning will be displayed during installation.
  96
  97 #### Cleaning
  98
  99 To remove generated files use:
 100
 101 ```
 102 make clean
 103 ```
 104
 105 ## ConfigMap validation
 106 After running the script ConfigMap spec file is generated in selected (be default `genereted`) directory.
 107 Spec files can be manually validated via any text editor. The last generated file includes in spec is schema-map.json file with
 108 mappings of external URLs to prepared local URLs.
 109
 110 To check whether it has been created use command:
 111
 112 ```
 113 kubectl -n onap get configmap | grep <CONFIGMAP_NAME>
 114 ```
 115
 116 A ConfigMaps with configured name should be visible on the list.
 117
 118 ## Mounting ConfigMap into VES Collector
 119
 120 To mount created ConfigMaps in VES, its deployment must be edited. It can be done with:
 121 ```
 122 kubectl -n onap edit deployment dep-dcae-ves-collector
 123 ```
 124
 125 Snippets with content that should be added to VES deployment are generated in file with name setup in configuration file
 126 under SNIPPET_FILENAME property. No extra configuration in VES is needed when using them.
 127
 128 **NOTE**: When using Vi text editor for deployment edition, correct input mode must be set to keep proper indentation
 129 when pasting snippets. Use ``:set paste `` to turn paste mode on. To close paste mode use ``:set nopaste``
 130
 131 1. Add volumeMounts element
 132
 133     In spec.template.spec.containers[0].volumeMounts add new list element:
 134
 135     **NOTE**: spec.template.spec.containers[0] should be a container with the image:
 136         *nexus3.onap.org:10001/onap/org.onap.dcaegen2.collectors.ves.vescollector::x.x.x*.
 137         It should be the first container, but make sure that the correct container is being edited.
 138
 139     ```
 140     volumeMounts:
 141         - mountPath: /opt/app/VESCollector/etc/externalRepo
 142           name: custom-3gpp-schemas
 143         - mountPath: /opt/app/VESCollector/etc/externalRepo/3gpp/rep/sa5/MnS/tree/branch/OpenAPI
 144           name: branch-custom-3gpp-schemas
 145         - ...
 146     ```
 147
 148     - mountPath - Directory context for schemas. **NOTE**: must be the same as configuration of VES Collector property
 149     *collector.externalSchema.schemasLocation* in *collector.properties*. This property might be modified via Consul UI,
 150     later after changes in deployment.
 151
 152    - name - Name of ConfigMap volume. For schema map must be the same as set in the 2. step in *name* field.
 153
 154 2. Add volumes element
 155
 156     In spec.template.spec.volumes add a new list element with all desired to mount schemas from ConfigMap in
 157     *items* list. *key* are file names from generated previously spec and *path* is relative path from directory set up
 158     in step 1 as *mountPath*.
 159
 160     Sample spec.template.spec.volumes content:
 161
 162     ```
 163     volumes:
 164       - configMap:
 165           defaultMode: 420
 166           name: schema-map-stnd-defined-configmap
 167         name: custom-3gpp-schemas
 168       - configMap:
 169           defaultMode: 420
 170           name: branch-stnd-defined-configmap
 171         name: branch-custom-3gpp-schemas
 172       - ...
 173     ```
 174    Fields description:
 175    - name - Name of ConfigMap volume. Consist of branch name and *name* field. Must be same as name in 1. step
 176    - configMap.name - name of installed Kubernetes ConfigMap consist of schema-map or branch name
 177      and K8S_CONFIGMAP_NAME from configuration setting
 178
 179 3. Save and close an editor, K8S will automatically detect changes, terminate old VES Pod and deploy new one with
 180 mounted ConfigMap. Correctness of new VES Pod initialization and mounting ConfigMap can be tracked using
 181 `kubectl -n onap describe pod <VES_POD_NAME>`.
 182
 183 To check if mounted schemas and VES properties configuration are correctly aligned see logs of VES. Each schema which is
 184 present in mapping file, but is not detected by VES will be logged on application startup e.g.:
 185 ```
 186 2020-10-01 11:46:55.872  WARN 24 [       Thread-5] o.o.d.s.s.s.e.s.m.s.UrlMapperFactory     : Local schema resource missing. Schema file with path /opt/app/VESCollector/etc/externalRepoCustom/3gpp/rep/sa5/MnS/tree/master/OpenAPI/5gcNrm.yaml has not been found.
 187 2020-10-01 11:46:55.872  WARN 24 [       Thread-5] o.o.d.s.s.s.e.s.m.s.UrlMapperFactory     : Mapping for publicURL ("https://forge.3gpp.org/rep/sa5/MnS/tree/master/OpenAPI/5gcNrm.yaml") will not be added to validator.
 188 ```
 189
 190 To see logs of VES use:
 191 ```
 192 kubectl -n onap logs <VES_POD_NAME>
 193 ```