Update markdown files to some standard

ADVANCED.md

@@ -1,11 +1,17 @@
-# Use terraform variable files
+# Advanced usage
 
-To avoid using multiple main.tf having the same deployment and just some variables differences, use the tfvars files with a main template to deploy environment.
-For this example, we will have four type of files : 
- - main.tf template, deployment description using variables for environment specific parameters
+## Use terraform variable files
+
+To avoid using multiple `main.tf` files having the same deployment and just some variables differences, use the `tfvars` files with a main template to deploy environment.
+For this example, we will have four types of files:
+
+### main.tf
+
+Deployment description using variables for environment specific parameters
 
 __Example :__
-```terraform
+
+```hcl
     server = {
       provider_settings = {
         mac = var.ENVIRONMENT_CONFIGURATION[var.ENVIRONMENT].mac["server"]
@@ -20,9 +26,13 @@ __Example :__
       server_mounted_mirror = var.MIRROR
     }
 ```
- - variable.tf file, remove all the variables from the main.tf and move it to a specific file
+
+### variable.tf
+
+Remove all the variables from the `main.tf` file and move it to a specific one.
    __Example :__
-```terraform
+
+```hcl
 variable "BRIDGE" {
   type = string
 }
@@ -38,14 +48,17 @@ variable "ENVIRONMENT_CONFIGURATION" {
 
 variable "DOWNLOAD_ENDPOINT" {
   type = string
-  description = "Download enpoint to get build images and set custom_download_endpoint. This value is equal to platform mirror"
+  description = "Download endpoint to get build images and set custom_download_endpoint. This value is equal to platform mirror"
 }
 ```
 
- - XXXX.tfvars, you can have as many as you want. Specify the variables depending on the environment. For example mac addresses depending on NUE or PRV environment
+### Custom terraform variable files (XXX.tfvars)
 
-__Example :__ 
-```terraform
+You can have as many as you want. Specify the variables depending on the environment. For example mac addresses depending on NUE or PRV environment
+
+__Example :__
+
+```'hcl'
 ############ Nuremberg unique variables ###########
 
 DOMAIN            = "mgr.suse.de"
@@ -72,15 +85,13 @@ ENVIRONMENT_CONFIGURATION = {
     additional_network = "192.168.111.0/24"
   }
 }
-
 ```
 
-# Deploying environment depending on the product version, environment 
+## Deploying environment depending on the product version, environment 
 
 ```bash
-                        sh "rm -f ${env.resultdir}/sumaform/terraform.tfvars"
-                        sh "cat ${tfvars_manager43} ${tfvars_nuremberg} >> ${env.resultdir}/sumaform/terraform.tfvars"
-                        sh "echo 'ENVIRONMENT = \'${env_number}\'' >> ${env.resultdir}/sumaform/terraform.tfvars"
-                        sh "cp ${tf_local_variables} ${env.resultdir}/sumaform/"
-
-```
+sh "rm -f ${env.resultdir}/sumaform/terraform.tfvars"
+sh "cat ${tfvars_manager43} ${tfvars_nuremberg} >> ${env.resultdir}/sumaform/terraform.tfvars"
+sh "echo 'ENVIRONMENT = \'${env_number}\'' >> ${env.resultdir}/sumaform/terraform.tfvars"
+sh "cp ${tf_local_variables} ${env.resultdir}/sumaform/"
+```

EXAMPLE.md

@@ -1,10 +1,12 @@
-These examples will assume you will be using libvirt, and a `main.tf` file `examples/main.tf-jenkins` that will launch an Uyuni environment, the Uyuni testsuite and emulate mails as sent for reports served from Jenkins.
+# Examples
+
+These examples assume that you will be using `libvirt` and a `main.tf` file based on `examples/main.tf-jenkins` that will launch an Uyuni environment, the Uyuni test suite and emulate emails as sent for reports served from Jenkins.
 
 Not all the parameters included on the examples ar mandatory, but some are added for clarity.
 
 Check the help if you want to make the CLI calls shorter by using default values.
 
-# Running step by step
+## Running step by step
 
 First of all, create a copy of the `main.tf` example for Jenkins:
 
@@ -19,83 +21,99 @@ sed -i -e 's/use_avahi    = false/use_avahi    = true/' examples/main.tf-jenkins
 ```
 
 Also adjust the email to receive the reports. You should use an address local to your machine (`yourusername@localhost`)
+
 ```bash
 sed -i -e 's/default = "juliogonzalez@localhost"/default = "YOUREMAIL"/' examples/main.tf-jenkins.mycopy
 ```
 
 Export SCC credentials:
+
 ```bash
 export TF_VAR_SCC_USER=<ID>
 export TF_VAR_SCC_PASSWORD=<PASSWORD>
 ```
 
 Export a variable `BUILD_TIMESTAMP` to be used by all the steps (when running on Jenkins this is not needed and `BUILD_NUMBER` provided by Jenkins can be used automatically):
+
 ```bash
 export BUILD_TIMESTAMP=$(date '+%Y-%m-%d-%H-%M-%S')
 ```
 
 Create a folder for the outputs (not required if ìt already exists):
+
 ```bash
 mkdir /tmp/sumaform_outputs
 ```
 
 Clone or update the repository with the terraform code (sumaform in our case):
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-jenkins.mycopy --outputdir /tmp/sumaform_outputs --gitrepo https://github.com/uyuni-project/sumaform.git --gitfolder /tmp/sumaform --gitref master --runstep gitsync
 ```
 
 Create the terraform environment:
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-jenkins.mycopy --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/sumaform.log  --gitfolder /tmp/sumaform --init --runstep provision
 ```
 
-Run an Uyuni testsuite step (iterate for more steps if needed):
-```
+Run an Uyuni test suite step (iterate for more steps if needed):
+
+```bash
 ./terracumber-cli --tf examples/main.tf-jenkins.mycopy --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep cucumber --cucumber-cmd "TERRAFORM=/usr/bin/terraform TERRAFORM_PLUGINS=/usr/bin; export PRODUCT=Uyuni; cd /root/spacewalk/testsuite; rake cucumber:core"
 ```
 
 When you are done with the tests, get the results:
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-jenkins.mycopy --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep getresults
 ```
 
 And, finally, send an email (optional):
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-jenkins.mycopy --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep mail
 
 ```
 
-If you want to start again, run the `gitsync` step if you want to fetch changes, and then run the `provision` step without `--init` and providing a list of resources to be tained (the example includes instances and their disks):
-```
+If you want to start again, run the `gitsync` step if you want to fetch changes, and then run the `provision` step without `--init` and providing a list of resources to be tainted (the example includes instances and their disks):
+
+```bash
 ./terracumber-cli --tf examples/main.tf-jenkins.mycopy --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/sumaform.log  --gitfolder /tmp/sumaform  --runstep provision --taint '.*(domain|main_disk).*'
 ```
 
-# Salt Shaker executions
+## Salt Shaker executions
+
 The same `gitsync`, `provision` steps detailed above also apply when running Salt Shaker, then you have the following steps that are only for Salt Shaker:
 
 Run Salt Shaker unit tests:
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-salt-shaker --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep saltshaker --saltshaker-cmd "/usr/bin/salt-test --package-flavor bundle --skiplist https://raw.githubusercontent.com/openSUSE/salt-test-skiplist/main/skipped_tests.toml unit -- --core-tests --ssh-tests --slow-tests --run-expensive --run-destructive --junitxml /root/results_junit/junit-report-unit.xml -vvv --tb=native"
 ```
 
 Run Salt Shaker integration tests:
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-salt-shaker --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep saltshaker --saltshaker-cmd "/usr/bin/salt-test --package-flavor bundle --skiplist https://raw.githubusercontent.com/openSUSE/salt-test-skiplist/main/skipped_tests.toml integration -- --core-tests --ssh-tests --slow-tests --run-expensive --run-destructive --junitxml /root/results_junit/junit-report-integration.xml -vvv --tb=native"
 ```
 
 Run Salt Shaker functional tests:
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-salt-shaker --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep saltshaker --saltshaker-cmd "/usr/bin/salt-test --package-flavor bundle --skiplist https://raw.githubusercontent.com/openSUSE/salt-test-skiplist/main/skipped_tests.toml functional -- --core-tests --ssh-tests --slow-tests --run-expensive --run-destructive --junitxml /root/results_junit/junit-report-functional.xml -vvv --tb=native"
 ```
 
 **NOTE:** You can use `--package-flavor classic` when triggering the Salt Shaker in order to test using the classic Salt package instead of the Salt Bundle.
 
 When you are done with the Salt Shaker tests, get the results:
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-salt-shaker --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep saltshaker_getresults
 ```
 
 And, finally, send an email (optional):
-```
+
+```bash
 ./terracumber-cli --tf examples/main.tf-salt-shaker --outputdir /tmp/sumaform_outputs --logfile /tmp/sumaform/testsuite.log --gitfolder /tmp/sumaform --runstep saltshaker_mail
 ```

README.md

@@ -6,7 +6,7 @@ This is exactly what [Uyuni](https://www.uyuni-project.org/) and [SUSE Manager](
 
 Until [SUSE's Hackweek 18](https://hackweek.suse.com/projects/terracumber-python-replacement-for-sumaform-test-runner) we were using a set of bash scripts, completely ad-hoc and hard to maintain and extend, and that is how Terracumber was born.
 
-# Does this only work with sumaform?
+## Does this only work with sumaform?
 
 No. It should work with any other environment as long as:
 
@@ -28,11 +28,11 @@ No. It should work with any other environment as long as:
 
 **[1]** We hope to make this configurable in the future.
 
-# How should I use it?
+## How should I use it?
 
-## Software requirements
+### Software requirements
 
-- Python3
+- Python 3
 - [pyhcl](https://pypi.org/project/pyhcl/) module installed
 - [paramiko](https://www.paramiko.org/) module installed
 - [pygit2](https://www.pygit2.org/) module installed
@@ -42,19 +42,18 @@ No. It should work with any other environment as long as:
 
 Terraform must be configured as needed to run the terraform templates you are going to use.
 
-
-## Quickstart
+### Quickstart
 
 See [EXAMPLE.md](EXAMPLE.md) for a quick intro about the calls to `terracumber-cli`
 
-
 ## Advanced usage
 
 ### Create/adjust your .tf file
 
-You will need to create at least one `.tf` file to use it to launch your environment, as well as configuring everything else (such as what command to run for the testsuite).
+You will need to create at least one `.tf` file to use it to launch your environment, as well as configuring everything else (such as what command to run for the test suite).
 
 Keep in mind:
+
 1. There are some mandatory variables for the `.tf` file (see one of the [examples](examples/)
 2. You can add extra variables to your `.tf` file, so you can use it when creating the environment. Those variables will need to be exported before running `terracumber-cli` as `TF_VAR_`, as explained at the [terraform doc](https://learn.hashicorp.com/terraform/getting-started/variables.html#from-environment-variables). Our example adds SCC credentials to pass them to Uyuni/SUSE Manager, and GitHub credentials to use them to clone the GitHub cucumber repository **[1]**
 
@@ -75,11 +74,11 @@ The email templates are plain text files with some variables to be replaced by `
 * `$skipped` - Number of tests skipped by cucumber
 * `$failures_log` - A list of failed tests, the number of failures is determined by `terracumber-cli` `--nlines` parameter
 
-# Bonus: clean old results
+## Bonus: clean old results
 
 The script `clean-old-results` can be used to get rid of undesired old results (use `-h` to get help)
 
-# How to contribute
+## How to contribute
 
 It is easy: just create a Pull Request with your contribution, and make sure that the unit tests are passing.