Naming your CI Jobs

Job naming guidelines

Job names should indicate to the reader the purpose of the specific job, as well as noting where the job deviates from OpenShift defaults for that release. The guidelines contained in this document are based on the way the majority of jobs are named today. The general format of a job name should be as follows:

[JOB TYPE]-ci-[GITHUB ORG]-[GITHUB REPO]-[GITHUB BRANCH]-[STREAM]-[RELEASES]-[TEST SUITE]-[PLATFORM]-[CNI]-[OTHER DEVIATIONS]

When using multi-stage generated jobs, the first part of the name is generated for you, and the second part that begins with “releases” is determined by the job creator.

Job name fields

Generated fields

For multi-stage jobs, these fields are generated for you and aren’t needed in the name set in your YAML configuration.

Job type: Will be either “periodic” or “pull”. Jobs that begin with other prefixes like “release” or “promote” are template-style jobs and mostly not used any more.

GitHub org/repo/branch: The GitHub org, repo and branch the job is configured for. Release periodics typically use openshift/release, but teams may put them under their own control subject to the guidelines below.

Stream: Which release stream is being tested, such as nightly or ci.

User selected fields

Releases: The X.Y release being used is typically already in the job name by way of the GitHub branch (i.e. release-4.13). For minor upgrades, you do need to add the context of the initial release in the format “X.Y-upgrade-from-stable-4.(Y-1)”. Upgrades that test multiple versions are listed in sequence, i.e. “4.10-to-4.11-to-4.12-to-4.13-ci”. Micro upgrades do not need any special designation other than the X.Y. All upgrade jobs should specify “upgrade” under “other deviations.”

Test Suite: If it is running a test suite from openshift/origin (openshift-tests binary), this value should be “e2e.” openshift/conformance/parallel is the assumed suite for “e2e” jobs, unless otherwise specified in “other deviations” (such as “serial”). If it is running something else such as tests from your own repo, you can give it a descriptive name of your choice, but do not use the e2e value. The OpenShift console tests use the value “console" for example.

Platform: This should be the cloud platform type. When the kind of infrastructure (IPI, UPI, Assisted) is specified in the job name, this must be conjoined with the platform (i.e., aws-upi). Typically IPI is assumed and is omitted.

CNI: The CNI provider, such as “ovn” or “sdn”

Other deviations: Where the job deviates from OpenShift defaults for that release, these should be noted in the job name. Example deviations include: “rt” (realtime kernel), “proxy”, “ipv6”, and non-amd64 architectures like “arm64”. If an e2e job that is running a suite other than the parallel conformance suite, this should also be included here. For example, “serial” or “csi”. Upgrade jobs should specify “upgrade” at the end of the job name, whether it be a micro or minor upgrade.

Multiarch Payload fields

When creating a job that utilizes the multiarch payload, there are many different architectures and configurations that can be used for deploying a cluster. Creating the job name with a specific pattern will help others understand more about the deployment structure with just a glance. See this README for more information on appropriate formatting.

Example job names

• periodic-ci-openshift-release-master-nightly-4.13-console-aws
• periodic-ci-openshift-release-master-nightly-4.13-e2e-azure-ovn-etcd-scaling
• periodic-ci-openshift-release-master-nightly-4.13-e2e-metal-ipi-serial-ovn-dualstack
• periodic-ci-openshift-release-master-ci-4.13-e2e-gcp-sdn-techpreview-serial
• periodic-ci-openshift-release-master-ci-4.13-upgrade-from-stable-4.12-e2e-azure-sdn-upgrade

When defaults change

For a particular release, a default may change. For example, it’s expected that we will soon move from runc to crun as the default container runtime. Today, there are jobs that contain crun in their name because they deviate from the current default of runc.

Once the default changes the process should be to:

• Create a list of all jobs containing crun in their name.
• Ensure there is a matching job in the current set of CI jobs not specifically running crun. For example, if there is a FIPS crun job, make sure there is such a job using OpenShift defaults.
• Remove the crun-specific jobs
• Create runc jobs, if needed, to test the older functionality

Periodics outside of openshift/release

Typically, release payload informing and blocking jobs are configured in the openshift/release repo under the openshift/release configuration directory. However, because teams may want more control over their periodics, they may want to place them in their own repository’s configuration. Periodics should be placed in their own configuration YAML file away from presubmit configuration, and the release information should be set to the appropriate release version and stream. You may have multiple configurations per release branch by using the variants feature of ci-operator.

An example of this configuration is available here, where you can see the periodics are stored in the __periodics.yaml files.

For these jobs to show up in TestGrid and Sippy, the ci-tools configuration needs to be updated manually.