<!---
Copyright (c) Alianza, Inc. All rights reserved.
Highly Confidential Material
-->

# MVM V3 MOPs

## 1. Introduction

This directory contains templates and pre-requisite configuration and helper scripts that
are required to generate GMOPs and SMOPs for the MVM v3 Deployment.

**GMOP** and **SMOP** variants of the MOPs differ as follows:
* a Generic MOP contains no specific parameter values; all variables are specified in `<VARIABLE>` format and the operator running the MOP needs to fill in the correct values when they run the MOP.
* a Site-specific MOP containes values which are specific to the region/az that the MOP is targeted for. The advantage of this format is that the operator can copy commands directly out of the documentation and into their terminal.

## 2. Directory structure

-  `templates` contains the template files used to generate the MOPs. It contains one subdirectory for each supported process, as well as the `images` directory which contains the various images used by the MOPs.
- `configuration.example` contains example variable files for each of the the types of MOPs.
- `configuration` contains the configuration files for the SMOPs - this is populated by the operator.
- `scripts` contains the script, `render.py` that generates the various GMOPs and SMOPs.

## 3. `render.py`

`render.py` is the script that generates the MOPs from the corresponding template
files. If run with the `-h` option it generates the help message shown below.

```
$ ./scripts/render.py -h
usage: render.py [-h] [-g] [-f FILE] [-o OUTDIR] [-t TEMPLATES]

Generate markdown MOPs from Jinja2 templates.

optional arguments:
  -h, --help            show this help message and exit
  -g, --gmop            Generate a set of GMOPs
  -f FILE, --file FILE  Configuration filename (in configuration directory)
  -o OUTDIR, --outdir OUTDIR
                        Directory to write output files to
  -t TEMPLATES, --templates TEMPLATES
                        Directory containing templates to render (in templates directory)
```

### 3.1 Generating GMOPs

GMOPs are generic MOPs that contain no site specific information. When referenced,
parameters are specified in <>, e.g.
```
KEY_VAULT_NAME=<KEY_VAULT_NAME>
az keyvault secret list \
   --vault-name ${KEY_VAULT_NAME} \
   --query '[].name'
```

To generate a set of GMOPs run the following steps

1. cd to the top level directory

1. run `render.py` with the following parameters
   - `-g`
   - `-t <templates>`, e.g. `-t upgrade_main`

   This will generate a set of GMOPs in the output directory `<gmop.type>`, e.g. `gmop.upgrade_main`

   A sample output is shown below
   ```
   $ ./scripts/render.py -t upgrade_main -g
   2024-08-03 07:52:19,393 - INFO - Generating GMOPs
   2024-08-03 07:52:19,399 - INFO - Deleting previous output files in gmop.upgrade_main
   2024-08-03 07:52:19,871 - INFO - Processing template r11414tor11500upgradeoverview.md
   2024-08-03 07:52:19,907 - INFO - Processing template r115deletesas.md
   2024-08-03 07:52:19,947 - INFO - Processing template r115deletetimer.md
   2024-08-03 07:52:19,981 - INFO - Processing template r115upgradeadopipelineresources.md
   2024-08-03 07:52:20,023 - INFO - Processing template r115upgradeccm.md
   2024-08-03 07:52:20,107 - INFO - Processing template r115upgradeclitools.md
   2024-08-03 07:52:20,171 - INFO - Processing template r115upgradecmm.md
   2024-08-03 07:52:20,239 - INFO - Processing template r115upgradeconfigmanager.md
   2024-08-03 07:52:20,275 - INFO - Processing template r115upgradeconfiguration.md
   2024-08-03 07:52:20,320 - INFO - Processing template r115upgradedeploymentprereqs.md
   2024-08-03 07:52:20,379 - INFO - Processing template r115upgradeesc.md
   2024-08-03 07:52:20,491 - INFO - Processing template r115upgraderegionalprereqs.md
   2024-08-03 07:52:20,549 - INFO - Processing template r115upgradesas.md
   2024-08-03 07:52:20,656 - INFO - Processing template r115upgradeselfhostedagentvm.md
   2024-08-03 07:52:20,743 - INFO - Processing template r115upgradesimon.md
   2024-08-03 07:52:20,843 - INFO - Processing template r115upgradesimplcluster.md
   2024-08-03 07:52:20,926 - INFO - Processing template r115upgradetimer.md
   2024-08-03 07:52:20,972 - INFO - Processing template r115upgradetoolingvm.md
   2024-08-03 07:52:21,037 - INFO - Processing template r115uploadartifacts.md
   2024-08-03 07:52:21,076 - INFO - Processing template r115uploadperimeta.md
   2024-08-03 07:52:21,125 - INFO - Processing template r115uploadperimetaefixes.md
   2024-08-03 07:52:21,181 - INFO - Generated MOPs can be found in the directory gmop.upgrade_main
   ```

### 3.2 Generating SMOPs

SMOPs are specific MOPs that contain information specific to the task being performed.
Parameter variables are specified in a configuration file and substituted as appropriate, e.g.
```
KEY_VAULT_NAME=ra-mvm-leus2-dev-kv0
az keyvault secret list \
   --vault-name ${KEY_VAULT_NAME} \
   --query '[].name'
```

To generate a set of SMOPs run the following steps

1. cd to the `configuration` directory

1. Make a copy of the appropriate example configuration file, e.g.
   ```
   cp vars_main_example.yaml vars_main_eus2.yaml'
   ```

1. Edit the file and configure the parameters with the values specific to the specific task.

   If a parameter is not known then comment the line out by specifying `#` in column 1.
   This will result in the corresponding parameter being specified as `<PARAMETER_NAME>` in
   the resultant SMOP

1. run `render.py` with the following parameters
   - `-f <configuration file>`, e.g. `-f vars_main_eus2.yaml`
   - `-t <templates>`,          e.g. `-t main`
   - `-o <output directory>`,   e.g. `-o main.eus2`

   A sample output is shown below
   ```
   $ ./scripts/render.py  -t main -o main.eus2 -f vars_main_eus2.yaml
   2024-08-03 07:54:34,001 - INFO - Deleting previous output files in main.eus2
   2024-08-03 07:54:34,338 - INFO - Processing template r11414tor11500upgradeoverview.md
   2024-08-03 07:54:34,357 - INFO - Processing template r115deletesas.md
   2024-08-03 07:54:34,378 - INFO - Processing template r115deletetimer.md
   2024-08-03 07:54:34,399 - INFO - Processing template r115upgradeadopipelineresources.md
   2024-08-03 07:54:34,424 - INFO - Processing template r115upgradeccm.md
   2024-08-03 07:54:34,451 - INFO - Processing template r115upgradeclitools.md
   2024-08-03 07:54:34,463 - INFO - Processing template r115upgradecmm.md
   2024-08-03 07:54:34,488 - INFO - Processing template r115upgradeconfigmanager.md
   2024-08-03 07:54:34,501 - INFO - Processing template r115upgradeconfiguration.md
   2024-08-03 07:54:34,522 - INFO - Processing template r115upgradedeploymentprereqs.md
   2024-08-03 07:54:34,538 - INFO - Processing template r115upgradeesc.md
   2024-08-03 07:54:34,579 - INFO - Processing template r115upgraderegionalprereqs.md
   2024-08-03 07:54:34,596 - INFO - Processing template r115upgradesas.md
   2024-08-03 07:54:34,621 - INFO - Processing template r115upgradeselfhostedagentvm.md
   2024-08-03 07:54:34,641 - INFO - Processing template r115upgradesimon.md
   2024-08-03 07:54:34,674 - INFO - Processing template r115upgradesimplcluster.md
   2024-08-03 07:54:34,710 - INFO - Processing template r115upgradetimer.md
   2024-08-03 07:54:34,731 - INFO - Processing template r115upgradetoolingvm.md
   2024-08-03 07:54:34,758 - INFO - Processing template r115uploadartifacts.md
   2024-08-03 07:54:34,771 - INFO - Processing template r115uploadperimeta.md
   2024-08-03 07:54:34,784 - INFO - Processing template r115uploadperimetaefixes.md
   2024-08-03 07:54:34,794 - INFO - Generated MOPs can be found in the directory main.eus2
   ```