GitHub V1

galaxy.yml

@@ -8,7 +8,7 @@ namespace: stackhpc
 name: kayobe_automation_workflows
 
 # The version of the collection. Must be compatible with semantic versioning
-version: 0.1.0
+version: 1.0.0
 
 # The path to the Markdown (.md) readme file. This path is relative to the root of the collection
 readme: README.md
@@ -47,7 +47,7 @@ tags:
 dependencies: {}
 
 # The URL of the originating SCM repository
-repository: https://github.com/jackhodgkiss/kayobe-automation-workflows
+repository: https://github.com/stackhpc/ansible-collection-kayobe-workflows
 
 # The URL to any online docs
 # documentation: http://docs.example.com

roles/github/README.md

@@ -1,4 +1,4 @@
-Kayobe Automation Workflow (GitHub)
+Kayobe Automation Workflows (GitHub)
 =========
 
 This Ansible role is capable of generating GitHub workflow files for performing CI/CD related activities with OpenStack via Kayobe.
@@ -16,11 +16,10 @@ See the table below for a full list of all the currently supported kayobe automa
 | **run-overcloud-container-image-pull** | Pull container images from a container registry. |
 | **run-overcloud-database-backup** | Perform a backup of the database used by the overcloud. |
 | **run-overcloud-host-configure** | Perform an overcloud host configure. |
-| **run-overcloud-host-package-update** | Update system packages on the overcloud hosts. |
+| **run-overcloud-host-package-update** | Perform an overcloud host package update. |
 | **run-overcloud-inventory-discover** | Get an inventory of nodes. |
 | **run-overcloud-provision** | Provision overcloud nodes. |
 | **run-overcloud-service-deploy** | Deploy overcloud services. |
-| **run-overcloud-service-reconfigure** | Reconfigure services across the overcloud. |
 | **run-overcloud-service-upgrade** | Perform an upgrade of overcloud services. |
 | **run-seed-host-configure** | Configure the seed host. |
 | **run-seed-host-package-update** | Update the system packages of the seed host. |
@@ -35,19 +34,23 @@ Role Variables
 
 The following variables can be used to make small adjustments to the composition of the workflows.
 
-`output_directory`: control the location where the workflows shall be written to.
+`github_output_directory`: control the location where the workflows shall be written to.
 
-`runner_name`: name of the GitHub runner used by the workflows see [runs-on](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
+`github_runs_on`: control which runner can accept this workflow. See GitHub for more information on [runs-on](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
 
-`image_url`: full URL of the kayobe container image complete with registry and tag.
+`github_image_url`: full URL of the kayobe container image complete with registry and tag.
 
-`registry_password`: password used to authenticate with the docker registry.
+`github_registry_username`: username used to authenticate with the docker registry.
 
-`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_ENVIRONMENT` from its default of `production` you can simply add `KAYOBE_ENVIRONMENT` to this dictionary and it will take precedence over the defaults.
+`github_registry_password`: password used to authenticate with the docker registry.
+
+`github_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_ENVIRONMENT` from its default of `production` you can simply add `KAYOBE_ENVIRONMENT` to this dictionary and it will take precedence over the defaults.
+
+`github_*_hook:` see section [Template Hooks](#template-hooks)  for information about this variables
 
 If you wish to make more impactful changes such as which workflows are built and what they contain then see the list of dictionaries called `workflows` in `defaults/main.yml`
 
-`workflows:` is a list of dictionaries that contains each of the workflows described above. A given list element is made up of the following:
+`github_workflows:` is a list of dictionaries that contains each of the workflows described above. A given list element is made up of the following:
 
 - `name`: the name which the workflow shall refer to itself as within GitHub workflows user interface.
 
@@ -57,62 +60,69 @@ If you wish to make more impactful changes such as which workflows are built and
 
 - `arguments`: list of arguments keys used by the automation task the contents will be acquired from `kayobe_arguments` or the defaults.
 
-The following will override `workflows` to ensure only `Run overcloud database backup` is generated.
+- `path_override`: Some workflows benefit from a dedicated workflow template as the `generic.yml.j2` cannot meet the requirements of all workflows. Therefore it might be beneficial to create specific templates within the `{{ playbook_dir }}/templates/` directory and set this variable to that specific path.
+
+- `use_bespoke`: As mentioned in `path_override` some workflows require a more specific template to meet their needs. Setting this to true would create a workflow from a bespoke template if one exists within the roles `templates` directory. Note this is intended for **internal use only**.
+
+The following will override `github_workflows` to ensure only `Build Kayobe Image` and `Run Kolla Config Diff` is generated.
 
 ```yaml
-workflows:
-  - name: Run overcloud database backup
-    file_name: run-overcloud-database-backup.yml
-    trigger:
-      workflow_dispatch: *combined_inputs
-      schedule:
-        cron: "30 0 * * *"
-    arguments:
-      - KOLLA_TAGS
-      - KOLLA_LIMIT
-      - KAYOBE_TAGS
-      - KAYOBE_LIMIT
-      - HOME
+github_workflows:
+  - "{{ build_kayobe_image }}"
+  - "{{ run_kolla_config_diff }}"
 ```
 
-Example Playbook
-----------------
-
-The following example playbook will generate a series of `reference` workflows which can be found under `.github/workflows`
+In the following example `github_build_kayobe_image` has been changed to use a user provided template stored within their `{{ playbook_dir }}/templates`
 
 ```yaml
-- name: Write Kayobe Automation Workflows
-  hosts: localhost
-  collections:
-    - stackhpc.kayobe_automation_workflows
+github_build_kayobe_image:
+  file_name: build-kayobe-docker-image.yml
+  path_override: "{{ playbook_dir }}/templates/build-kayobe-docker-image.yml.j2"
 ```
 
-Hooks [Experimental]
---------------------
 
-> :warning: This feature is marked as `experimental` at the moment as it is not clear how to configure `ansible.builtin.template` to look at the `${{ playbook_dir }}/templates/hooks/`.
 
-Workflows can be expanded with the use of `hooks` which are templates that if provided can be inserted into the appropriate location enabling the introduction of additional steps within the workflow job.
-This could include the use of HashiCorp Vault or installing and configuring a network proxy.
+Template Hooks
+--------------
+
+Workflows can be expanded with the use of hooks which are variables that if provided can be inserted into the appropriate location enabling the introduction of additional steps within the workflow job. This could include the use of HashiCorp Vault or installing and configuring a network proxy.
+
+There are currently three hooks available
+
+- `github_checkout_hook`: a hook that occurs before the repository is cloned by the `checkout` action.
 
+- `github_kayobe_hook`: a hook that occurs after the the repository has been cloned and before the kayobe automation task has started.
 
+- `github_final_hook`: a hook that occurs after the kayobe automation task has finished.
+
+A hook must be defined as a variable and should be a scalar block string.
 
 ```yaml
+github_checkout_hook: |
+  - name: Import secrets via Hashicorp Vault
+    id: secrets
+    uses: hashicorp/vault-action@v2.5.0
+    with:
+      url: https://vault.stackhpc.com:8200
+      method: approle
+      roleId:  ${{ secrets.ROLE_ID }}
+      secretId: ${{ secrets.SECRET_ID }}
+      tlsSkipVerify: true
+      secrets: |
+        stackhpc/data/github kayobe_vault_password_${{ needs.env.outputs.environment }} | KAYOBE_VAULT_PASSWORD ;
+        stackhpc/data/github kayobe_automation_ssh_private_key_${{ needs.env.outputs.environment }} | KAYOBE_AUTOMATION_SSH_PRIVATE_KEY ;
+```
 
-- name: Import secrets via Hashicorp Vault
-  id: secrets
-  uses: hashicorp/vault-action@v2.5.0
-  with:
-    url: https://vault.stackhpc.com:8200
-    method: approle
-    roleId:  ${{ secrets.ROLE_ID }}
-    secretId: ${{ secrets.SECRET_ID }}
-    tlsSkipVerify: true
-    secrets: |
-      stackhpc/data/github kayobe_vault_password_${{ needs.env.outputs.environment }} | KAYOBE_VAULT_PASSWORD ;
-      stackhpc/data/github kayobe_automation_ssh_private_key_${{ needs.env.outputs.environment }} | KAYOBE_AUTOMATION_SSH_PRIVATE_KEY ;
+Example Playbook
+----------------
 
+The following example playbook will generate a series of `reference` workflows which can be found under `.github/workflows`
 
+```yaml
+- name: Write Kayobe Automation Workflows for GitHub
+  hosts: localhost
+  roles:
+    - stackhpc.kayobe_automation_workflows.github
 ```
 
 License