The CI Operator allows for users to configure tests running in a single container
with the tests array. In many cases, however, running a command in a single
container will not suffice. For more complicated tests, the CI Operator supports
a --template option with which a test author may write black-boxed execution
targets using OpenShift Templates. This document explains the interfaces expected
for test Templates and best practices for how an author should configure their
Template.
The high-level contract for a Template execution target is that the Template
will be processed into the test's Namespace once prerequisite Builds have
occurred. Artifacts will be gathered from artifacts volumes on Pods in
the Template, if any are present. What work occurs in a Template's Pods is
a black box as far as the CI Operator is concerned.
A number of parameters are available to the Template and will be provided if
the Template is explicitly configured to consume them. The following parameters
will be provided to Templates:
The namespace in which your Template is processed. Target this namespace with
your objects.
| Example: | ci-op-<input-hash> |
|---|
The image repository URL template using which your job's release images can
be pulled, formatted for the OpenShift Ansible -e oreg_url parameter.
Templates depending on this parameter will be processed only after all
images are built.
| Example: | registry.svc.ci.openshift.org/ci-op-<input-hash>/stable:${component} |
|---|
The RPM repository URL from which your job's RPMs can be installed.
Templates depending on this parameter will be processed only after the
rpm image is built. The value of org and repo are uppercased and dashes
replaced with underscores.
| Example: | http://rpm-repo-ci-op-<input-hash>.svc.ci.openshift.org |
|---|
The image repository URL from which the <component> image can be pulled.
If a component name has hyphens, replace them with underscores. For instance,
the $IMAGE_SOME_NAME parameter would point to the registry URL for some-name.
Valid <component> images are any non-optional images defined in the images
array. Many parameters of this format can be provided for one Template.
Templates depending on these parameters will be processed only after the
<component> images are built.
| Example: | registry.svc.ci.openshift.org/ci-op-<input-hash>/stable:<component> |
|---|
The image repository URL from which the <pipeline-tag> image can be pulled.
If a component name has hyphens, replace them with underscores. For instance,
the $LOCAL_IMAGE_SOME_NAME parameter would point to the registry URL for
some-name. Valid <pipeline-tag> images are src, bin, test-bin, or
rpms. Many parameters of this format can be provided for one Template.
Templates depending on these parameters will be processed only after the
<pipeline-tag> images are built.
| Example: | registry.svc.ci.openshift.org/ci-op-<input-hash>/pipeline:<pipeline-tag> |
|---|
The job name as provided by Prow in the $JOB_SPEC.
The $JOB_NAME transformed to be a valid Kubernetes object identifier.
A short hash of the $JOB_NAME. Append this to the $NAMESPACE to create an
identifier that is unique across all jobs for the same inputs. Note that this
identifier will not be unique across multiple builds of the same job for the
same inputs.
The CI Operator attempts to determine the result of the Template's execution
as well as assembling output artifacts.
A Template definition is allowed to contain any number of Pods. A Template
is considered successful if every Container in every Pod in the Template
definition starts at least once and terminates with a 0 exit code.
As with any job, use the --artifact-dir flag on the ci-operator command-line
to enable artifact gathering. When artifact gathering is enabled, the CI Operator
will add a Container named artifacts to any Pod defined in the Template
that exposes a volume named artifacts. All files that are added to the volume
will be uploaded to the appropriate GCS bucket for the job build that executed
the Template. Failures to retrieve or upload artifacts will not impact the
overall result of the job.
ci-operator.openshift.io/wait-for-container-artifacts:
Comma-separated list of container names for which ci-operator will wait until complete,
to gather the artifacts.
ci-operator.openshift.io/save-container-logs:
Save all of the container outputs to artifacts. The value must be true to enable this feature.