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,103 @@
+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 pipelines which are stages designed to complete complex task such as upgrading all hypervisors in safe and reliable manner.
+
+| **Name** | **Description** |
+|:---:|:---:|
+| **proc-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. |
+| **proc-hypervisor-host-upgrade** | Perform a host upgrade of hypervisors; disable compute services, drain hypervisor, host configure, 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_environment_selector`: control the type of environment support the workflows should be generated with. Either `single` for fixed environment or `input` whereby the environment is controlled when the pipeline is created. No environment is the default by setting `gitlab_environment_selector` to no value or `Null`.
+
+`gitlab_kayobe_environments`: list of environments the workflows should target. Only has effect when `gitlab_environment_selector` is `input` or `single`.
+
+`gitlab_runs_on`: control which runner can accept this workflow. Default is `[kayobe, openstack]` See gitlab for more information on [tags](https://docs.gitlab.com/ee/ci/yaml/#tags).
+
+`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`: dictionary containing keys that correspond to `url` and `share` for the registry to be used by the workflows. By default it uses repository variables and settings `REGISTRY_URL`. The key `share` is to indiciate if the registry is shared between all environments.
+
+`gitlab_kayobe_base_image`: select the base image used when building the kayobe docker image. Default is `quay.io/rockylinux/rockylinux:9`.
+
+`gitlab_kayobe_arguments`: a dictionary of arguments that can be used to override the default arguments found within `vars/main.yml`. For example if you wanted to change the value of `KAYOBE_AUTOMATION_PR_TITLE` from its default, you can do by simply adding `KAYOBE_AUTOMATION_PR_TITLE` to this dictionary and it will take precedence over the default.
+
+`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_jobs:` is a list of dictionaries that contains each of the job described above. A given list element is made up of the following:
+
+- `name`: the name which the job shall refer to itself as within gitlab job user interface.
+
+- `stage`: name of the stage the job belongs to and thus the file.
+
+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/)