Step Registry - Workflow Guide

Table of Contents

What is a Workflow?

A workflow can be thought of as a set of chains and refs. Any of these steps can be defined as either a pre step, test step, or post step.

Workflows can be useful in many situations, but CSPI currently uses them mainly as cluster provisioning and deprovisioning steps. It is possible that our use of workflows will expand as we continue to grow in OpenShift CI.

Here is an example of using a workflow in the MTR scenario:

tests:
- as: mtr-interop-aws
  cron: 0 1 * * 1
  steps:
    cluster_profile: aws-cspi-qe
    env:
      BASE_DOMAIN: aws.interop.ccitredhat.com
      RESULTS_FILE: windup-ui-results.xml
      SUB_CHANNEL: alpha
    test:
    - chain: mtr-install
    - ref: mtr-deploy-windup
    - chain: mtr-execute-interop-ui-tests
    - ref: lp-interop-tooling-archive-results
    workflow: ipi-aws

The ipi-aws workflow specified above has a pre and post step that runs before and after the tests runs. These steps are responsible for provisioning the test cluster on AWS before the tests and deprovisioning that cluster after it has completed (pass or fail).

How to Create a Workflow

A workflow is only comprised of 4 files:

  • Configuration File: A YAML file used to define the name and the steps of a workflow.

  • OWNERS file: A file used by OpenShift GitHub robots as a list of users who are allowed to approve or deny changes to a step.

  • README.md (CSPI requirement): A documentation file written in Markdown. While not required by OpenShift CI, this is a CSPI requirement.

  • OpenShift CI Metadata file: An autogenerated file used by OpenShift CI internally.

Preparation

  1. In the openshift/release repository, create a folder for your workflow under ci-operator/step-registry/ if a suitable folder does not exist already.

    • Example: ci-operator/step-registry/new-step

  2. Create the following files in your new folder.

    • new-step-workflow.yaml

    • OWNERS

    • README.md

IMPORTANT:

When creating the .yaml file in step 2 above, please keep in mind that it must follow a naming standard or OpenShift CI will not accept it. You'll notice the folder I created is named "new-step", the .yaml file needs to start with that name and end with -workflow.yaml.

If you create the new folder for your workflow in an existing folder under ci-operator/step-registry/, you must include the name of the parent folder in the name as well. For example, if you created the new-step folder under ci-operator/step-registry/existing-folder, the name of your file would be existing-folder-new-step-workflow.yaml.

Populating the Files

new-step-workflow.yaml

This file is meant to serve as the configuration file for the new workflow being created. This file outlines:

  • The name of the workflow.

  • The steps you'd like the workflow to run prior to and after a test executes.

Please use the mock-up and the guide below to populate your workflow's configuration file:

workflow:
  as: new-step
  steps:
    pre:
    - chain: some-setup-chain
    - ref: some-setup-ref
    post:
    - chain: some-cleanup-chain
    - ref: some-cleanup-ref
  documentation: |-
    A sample workflow that runs a chain before a test and a ref after the test.

The workflow configuration above runs both chain and ref before and after a test is run.

Here is how we define and get each of the values in the configuration file above:

  • as: This is the name of the workflow. You'll notice it is just the name of the configuration file sans the -workflow.yaml ending. This is also how you will call this workflow to be executed in test configuration files.

  • steps: This stanza defines the pre and post steps to be executed.

    • pre: This list of steps is to be executed prior to a test.

      • chain: Defines the name of a chain to execute.

      • ref: Defines the name of a ref to execute.

    • post: This list of steps is to be executed following a test execution, pass or fail.

      • chain: Defines the name of a chain to execute.

      • ref: Defines the name of a ref to execute.

  • documentation: The value of this should be a short description of the workflow to be used in the autogenerated documentation in OpenShift CI.

OWNERS

See the official Kubernetes documentation.

README.md

Follow the instructions in the Step Registry Documentation Policy document.

Finalization

Once you have populated all of the files for your workflow, make sure to run the make update command in the root of your local clone of the openshift/release repository. This command will create all of the necessary metadata files that OpenShift CI uses to execute your new workflow. This command will also alert you to any errors in your configuration file and tell you how to fix them.

NOTE:

If running this command returns a permissions error, please try to run it using sudo.

PreviousStep Registry - Chain GuideNextTriggering

Last updated