feat: add gitlab role to enable GitLab CI/CD

Add a new role `gitlab` to enable GitLab CI/CD for use in constructing
a CI/CD pipeline that is compatible with `kayobe-automation`.

Supports key features and workflows found within the `GitHub` role.

Author: jackhodgkiss

roles/gitlab/README.md

@@ -0,0 +1,120 @@
+Kayobe Automation Pipeline (GitLab)
+===================================
+
+This Ansible role is capable of generating Gitlab pipeline files for performing CI/CD related activities with OpenStack via Kayobe.
+See the table below for a full list of all the currently supported kayobe automation tasks.
+
+| **Name** | **Description** | **Stage** |
+|:---:|:---:|:---:|
+| **build kayobe docker image** | Build a new kayobe docker image whenever a new tag is pushed to the repository. The resulting image is then pushed to a docker registry such as [registry.gitlab.com/](registry.gitlab.com/). | build |
+| **overcloud container image build** | Build overcloud container images. | overcloud |
+| **overcloud container image pull** | Pull overcloud container images from a container registry. | overcloud |
+| **overcloud database backup** | Perform a backup of the database used by the overcloud. | overcloud |
+| **overcloud database recover** | Recover the database used by the overcloud. | overcloud |
+| **overcloud deployment image build** | Build the Ironic Python Agent (IPA) image. | overcloud |
+| **overcloud host command run** | Run a command against the overcloud hosts. | overcloud |
+| **overcloud host configure** | Perform an overcloud host configure. | overcloud |
+| **overcloud host image build** | Build the the image that would deployed to overcloud hosts during provisioning. | overcloud |
+| **overcloud host package update** | Perform an overcloud host package update. | overcloud |
+| **overcloud host upgrade** | Perform targeted upgrade of key services before an upgrade. | overcloud |
+| **overcloud inventory discover** | Get an inventory of nodes. | overcloud |
+| **overcloud provision** | Provision overcloud nodes. | overcloud |
+| **overcloud service configuration generate** | Generate the overcloud service configuration. | overcloud |
+| **overcloud service deploy** | Deploy overcloud services. | overcloud |
+| **overcloud service reconfigure** | Reconfigure overcloud services. | overcloud |
+| **overcloud service upgrade** | Perform an upgrade of overcloud services. | overcloud |
+| **seed container image build** | Build container images for seed. | overcloud |
+| **seed host configure** | Configure the seed host. | seed |
+| **seed host package update** | Update the system packages of the seed host. | seed |
+| **seed hypervisor host configure** | Configure the seed hypervisor host. | seed |
+| **seed hypervisor host package update** | Perform a package update of the seed hypervisor host. | seed |
+| **seed service deploy** | Deploy services on the seed. | seed |
+| **seed vm provision** | Provision the seed VM. | seed |
+| **infra vm host configure** | Perform a host configure of the infra VMs on demand. | infra vm |
+| **infra vm host package update** | Perform a package update of the infra VMs hosts on demand. | infra vm |
+| **infra vm provision** | Provision infra VMs on demand. | infra vm |
+| **infra vm service deploy** | Perform a service deploy against infra VMs on demand. | infra vm |
+| **network connectivity check** | Execute a network connectivity check to ensure all hosts are reachable and can reach `nc external ip ` & `nc external hostname`. | network |
+| **physical network configure** | Configure the physical network. | network |
+| **config diff** | When a pull request is opened generate diff showing the changes made to the configuration. | merge request |
+| **tempest** | Perform tests against the deployed openstack environment with tempest. | tempest |
+
+Also available in Kayobe Automation for GitLab are runbooks which are stages designed to complete complex task such as upgrading all hypervisors in safe and reliable manner.
+
+| **Name** | **Description** |
+|:---:|:---:|
+| **runbook overcloud service upgrade** | Perform an upgrade of overcloud services; pull containers, upgrade host, run tempest, backup database, upgrade services, run tempest and prune unused docker images. |
+| **runbook in place hypervisor host upgrade** | Perform an in place host upgrade of hypervisors; disable compute services, drain hypervisor, package update, reboot and renable compute services. |
+
+
+Role Variables
+--------------
+
+The following variables can be used to make small adjustments to the composition of the workflows.
+
+`gitlab_output_directory`: control the location where the workflows shall be written to.
+
+`gitlab_kayobe_environments`: list of environments the workflows should target.
+
+`gitlab_image_name`: name of the kayobe image defaults to `kayobe`.
+
+`gitlab_image_tag`: tag used to select kayobe image defaults to `latest`
+
+`gitlab_registry`: a string that either points to a registry or is `$CI_REGISTRY_URL` in the case of multiple environments that do not share the same registry.
+
+`gitlab_kayobe_base_image`: select the base image used when building the kayobe docker image. Default is `quay.io/rockylinux/rockylinux:9`.
+
+`gitlab_tempest_test_suites`: provide a list of load lists to be made available within the drop-down list for running tempest. Defaults to `default` and `tempest-full`.
+
+If you wish to make more impactful changes such as which jobs are built and what they contain then see the list of dictionaries called `jobs` in `defaults/main.yml`
+
+`gitlab_stages:` is a dictionary of dictionary that contains string blocks defining the job within a given stage. Any job maybe overwritten by editing the `gitlab_JOB_NAME` or a stage can be extended adding to the `gitlab_STAGE_NAME_extra` dictionary. If you require adding additional stages that add the stage to `gitlab_extra_stages`.
+
+```
+gitlab_infra_vm_host_configure: |
+  rules:
+    - !reference [.active_stage_web_rule, rules]
+  stage: infra-vm
+  resource_group: infra-vm
+  script:
+    - !reference [.get_secrets, script]
+    - .automation/pipeline/infra-vm-host-configure.sh
+  allow_failure: true
+```
+
+```
+gitlab_infra_vm_something_new: |
+  rules:
+    - !reference [.active_stage_web_rule, rules]
+  stage: infra-vm
+  resource_group: infra-vm
+  script:
+    - !reference [.get_secrets, script]
+    - .automation/pipeline/does_something_new.sh
+  allow_failure: true
+
+gitlab_stage_infra_vm_extra:
+  infra_vm_something_new: "{{ gitlab_infra_vm_something_new }}"
+```
+
+Example Playbook
+----------------
+
+The following example playbook will generate a `reference` pipeline which can be found under `.gitlab` and `.gitlab/..`
+
+```yaml
+- name: Write Kayobe Automation Pipeline for gitlab
+  hosts: localhost
+  roles:
+    - stackhpc.kayobe_workflows.gitlab
+```
+
+License
+-------
+
+Apache License 2.0
+
+Author Information
+------------------
+
+[StackHPC](https://www.stackhpc.com/)