Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Stonebranch Integration Hub - Terms of Use.

Overview

OpenShift Jobs in the context of Kubernetes are resources designed for running finite tasks or batch jobs. They create and manage pods to execute these tasks, ensuring completion and termination upon success. Commonly used for operations like batch processing or periodic tasks.

This integration acts as an interface to OpenShift CLI (oc) enabling users to trigger the execution of OpenShift Jobs from the Universal Controller. OpenShift CLI (oc) is bundled within this integration and does not require separate installation.

Version Information

Template Name	Extension Name	Version	Status
OpenShift Jobs	ue-openshift-jobs	1 (Current 1.2.0)	Fixes and new Features are introduced.

Refer to the Changelog for version history information.

Key Features

Feature	Description
Run OpenShift Jobs	Run a single OpenShift Job using a resource file or a job resource URL and monitor its completion.
Delete OpenShift Jobs	Jobs can be deleted automatically after completion, manually during runtime, or as a single action.
Authentication Options	The supported authentication methods are Basic Authentication, Session Token Authentication, and Webconsole Token Authentication.
Containerization Support	Integration can be deployed on agents that live inside an OpenShift cluster.
Container Log Retrieval	Option to retrieve logs for all containers pertaining to a specific job.

Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Area	Details
Universal Agent & Python version	Requires Python version 3.11, 3.9 or 3.7. Only Agents of version >= 7.5 are supported.
Universal Controller	Universal Controller Version >= 7.5.0.0.
OpenShift and OpenShift CLI	This integration is bundled with Openshift CLI version 4.13.14, removing the need for manual installation of it. It is tested against the same OpenShift version. It should be compatible with later versions as long as backward compatibility is preserved.
Network and Connectivity	Connectivity towards OpenShift.

Supported Actions

Action: Run Job

The “Run Job” Action is used to run a job using a specific Job Resource Definition representing the definition of an OpenShift Job. The job definition resource can be a UC script, a local job definition file, or a URL pointing to a job definition.

Configuration examples


Scenario A Connect to a local OpenShift server with basic authentication, select the project “my_project” and run a job by applying a locally stored job definition. After, start the job poll for the job’s status for 10 poll cycles. If the job fails, retrieve container logs and print them to standard output.	Scenario B Connect to a local OpenShift server using a session token, select the project “my_project” and run a job by applying a job definition saved as a UC script. After starting the job, poll for the job’s status till it finishes, and then delete it. If the job gets stuck, the dynamic command "Delete Job" can be used to delete the job from the cluster.

Scenario C Connect to a local OpenShift server with basic authentication, select the project “my_project” and run a job by applying a job definition saved as a UC script. After the job is started, return.	Scenario D Connect to a local OpenShift server using a session token, select the project “my_project” and run a job that the definition of which is stored in GitHub. The token used to connect to GitHub is provided as an environment variable. After that, start polling for the job's status till it finishes, printing container logs to extension output in case it fails.

Action Output

Output Type

Description

Examples

EXTENSION

exit_code, status, status_description: General info regarding the task execution. In case of failure, it's set according to the specific error that happened during the execution. A list of possible values is provided in the exit codes table in this document.
invocation.fields: The task configuration used for this task execution.
result.jobs: The latest Information gathered related to the executed job/s. Information is retrieved from openshift, without additional processing. The output might vary depending on the OpenShift Version.
result.metadata.commands: A list that contains the oc commands executed. (Only the last oc get command is printed)
- command
- exit_code
result.logs: Log files from containers relevant to the executed job/s. Only included if specified in extension input.

Successful Execution Example

{
    "exit_code": 0,
    "status_description": "Task executed successfully",
    "invocation": {
        "extension": "ue-openshift-jobs",
        "version": "1.2.0",
        "fields": {...}
    },
    "result": {
        "jobs": [
            {
                "command": "oc get jobs/pi -o json --kubeconfig=/tmp/tmpbmj8kp2h_config",
                "return_code": 0,
                "job_description": {
                    "apiVersion": "batch/v1",
                    "kind": "Job",
                    "status": {
                        "completionTime": "xxx",
                        "conditions": [
                            {
                                "lastProbeTime": "xxx",
                                "lastTransitionTime": "xxx",
                                "status": "True",
                                "type": "Complete"
                            }
                        ],
                        "ready": 0,
                        "startTime": "xxx",
                        "succeeded": 1,
                        "uncountedTerminatedPods": {}
                    },
                    "name": "job_name"
                }
            }
        ],
        "metadata": {
            "commands": [
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc login https://10.120.23.59:6443 -u **** -p **** --insecure-skip-tls-verify --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc project uac --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc apply -f /home/ue-dev/lindev75a/data/tmp/0c0c9b1f-20fb-4c32-ac96-440ab110fff0 --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc get jobs/pi -o json --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc get pods --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc get pod pi-2f8tt --output=jsonpath={.spec.containers[*].name} --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc logs -f pi-2f8tt -c pi --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc logs -f pi-2f8tt -c piiii --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                },
                {
                    "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc delete job pi --kubeconfig=/tmp/tmpbmj8kp2h_config",
                    "exit_code": 0
                }
            ]
        },
        "logs": [
            {
                "pod": "pi-2f8tt",
                "container": "pi_first",
                "log": "3.14159265358"
            },
            {
                "pod": "pi-2f8tt",
                "container": "pi_second",
                "log": "3.14159265358"
            }
        ]
    }
}

Failed Execution Example

{
    "exit_code": 1,
    "status_description": "Command Execution Error: Could not start job.",
    "invocation": {
        "extension": "ue-openshift-jobs",
        "version": "1.1.0",
        "fields": {...}
    },
    "result": {
        "command": "oc apply -f /var/opt/universal/tmp/3cb9e580-0a9e-4d36-98a9-09454c09636d --kubeconfig=/tmp/tmpa1293d_config",
        "return_code": 1
    }
}

STDOUT

The STDOUT output of the oc commands is displayed on the Universal Task Instance STDOUT. If selected, there is an option to also include container logs to STDOUT.

STDOUT Example

WARNING: Using insecure TLS client config. Setting this option is not supported!
Login successful.
You have one project on this server: "my_project"
Using project "my_project".
Already on project "my_project" on server "https://localhost:6443".
job.batch/my_job created
Container Logs: 

Pod: pi-6bdbg
Container: pi-first
Log: 3.14159265358979
Pod: pi-6bdbg
Container: pi-second
Log: 3.14159265358979
Pod: pi-z4k9l
Logged "****" out on "https://localhost:6443"

Action: Delete Job

The “Delete Job” Action is used to delete a job from a namespace.

Configuration examples

Scenario

Connect to a local OpenShift server using a session token, select the project “my_project” and delete the job name “valid.job”.

Action Output

Same as the output of the "Run Job" action.

Input Fields

Field	Type	Mandatory	Description	Version Information
Action	Choice	Yes	The action to be executed. Default Option “Run Job” executes an OpenShift Job. The following options are available. Run Job (Default) Delete Job	Introduced in 1.0.0
OpenShift Server and Port URL	Text	Yes	The OpenShift Server and Port information. Used by oc to communicate with the OpenShift Server.	Introduced in 1.0.0
Project	Text	No	The OpenShift Project under which the jobs will be executed. If left empty the default configured project of the OpenShift will be used.	Introduced in 1.0.0
Login Method	Choice	Yes	The Login Method used. The following options are available. Basic Authentication (Default) Webconsole Token Session Token	Introduced in 1.0.0
OpenShift Credentials	Credentials	Yes	The credentials used to login to OpenShift. In case field Login Methon is set to “Basic Authentication“ or “Session Token“ the definition of the Credential should be: The Username as the Credential’s “Runtime User” The Password as the Credential’s “Runtime Password” In case field Login Methon is set to “Webconsole Token“ the definition of the credential should be: The Token as the Credential’s “Token”	Introduced in 1.0.0
Additional Login Parameters	Text	No	Additional parameters for login command. If used, they will be appended to the oc login command execution, during login operation.	Introduced in 1.0.0
Job Name	Dynamic Choice	No	The name of the job to be deleted. Available if Action is “Delete Job”	Introduced in 1.1.0
Job Resource Definition Source	Choice	No	Job Resource can be retrieved in multiple ways. Users can select either a path on the local filesystem or use a UAC Script. The following options are available. UAC Script (Default) Local File Available if Action is “Run Job”	Introduced in 1.0.0
Job Resource Definition	Script	No	The actual UAC Script containing the Job definition. Mandatory in case the Job Resource Definition Source is set to “UAC Script” The content of the script should be in YAML or JSON format and should contain one and only one job definition.	Introduced in 1.0.0
Job Resource Definition File	Text	No	The Agent’s local full filename path from which the Job definition is retrieved. Mandatory in case the Job Resource Definition Source is set to “Local File” The content of the file should be in YAML or JSON format and should contain one and only one job definition.	Introduced in 1.0.0
Wait for Completion	Bool	Yes	A Switch that controls whether the UAC task will wait until the Job is completed. Available if Action is “Run Job”. Defaults to "true"	Introduced in 1.0.0
Delete After Completion	Bool	No	A switch that controls whether the OpenShift job will be deleted after it finishes. Available if Wait for Completion is “true”. Defaults to "false"	Introduced in 1.1.0
Polling Interval (sec)	Integer	No	The time between retries for getting the status of the run command Available if Wait for Completion is “true”. Default value is 15. As a best practice, if the Job expected completion duration is long, set the polling Interval to a larger value. A short value will trigger frequent checks towards Openshift which in the case of long-duration jobs is inefficient in terms of resources.	Introduced in 1.0.0
Max Number of Polls	Integer	No	Maximum number of polls. Can be used to control the approximate expected duration of the Job (in relation also to Polling Interval (sec)). Available if Wait for Completion is “true” If left empty the UAC Task will poll indefinitely checking whether the Job is completed or resulted in failure. If the Maximum Number of Polls is reached the exit code of the task will be 40.	Introduced in 1.0.0
Extension Output Options	Choice	No	Controls whether additional information is printed on Extension output. One or more choices can be selected. The following options are available. Include Openshift Job Specification and Metadata: Includes the Openshift Job Specification and metadata as retrieved through the oc get command. Include Task Metadata: includes a list of oc commands executed along with their metadata Include Container Logs: Includes logs for every container pertaining to run job. Available if Action is “Run Job”	Introduced in 1.0.0
Standard Output Options	Choice	No	Controls whether additional information is printed on Standard output. One or more choices can be selected. Currently, only the following option is available. Include Container Logs: Includes logs for every container pertaining to run job. Available if Action is “Run Job”	Introduced in 1.2.0
Only Retrieve Container Logs on Failure	Bool	No	A switch that controls whether container logs should be printed to specified streams (Extension Output, Standard output) depending on job completion status. If set to True, logs are printed only if job fails	Introduced in 1.2.0

Cancellation and Rerun

In case of cancellation, the extension logs out of OpenShift. If the job has already started it will not be stopped or deleted by the extension.
In case of rerun the extension executes all commands from the beginning. That means that the extension will try to start the job even if the same job is currently running.

Dynamic Commands

Command Name	Allowed Task Instance Status	Description
Delete Job	RUNNING	Delete the running OpenShift Job.

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	“Task executed successfully.“	Exit code that Successful Execution.
1	Failure	“Execution Failed: <<Error Description>>”	This exit code is used in case of failure and in case no other failure exit code is applicable.
1	Failure	“Job Deletion Error: <<Error Description>>“	An error occurred when trying to delete the selected job.
1	Failure	“Pod Retrieval Error: <<Error Description>>“	An error occurred while trying to retrieve pod names
1	Failure	“Log Retrieval Error: <<Error Description>>“	An error occurred while trying to retrieve logs for a specific container
2	Failure	“Authentication Error: Account cannot be authenticated.“	Bad Credentials.
3	Failure	“Authorization Error: Account is not authorized to perform the requested action.“	Insufficient permissions.
20	Failure	“Data Validation Error: <<Error Description>>“	Input fields validation error.
40	Failure	“Polling Timeout Error: Could not get job status after max number of polls.“	Maximum number of polls is reached.

STDOUT and STDERR

STDOUT and STDERR provide additional information to the User. During the execution of the task, several “oc” commands are executed. The command outputs will be printed to STDOUT of the Universal Task Instance.

Only the first and the last oc get commands are tracked on STDOUT (used for polling), so as not to cause a large STDOUT output.
Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice

How To

Import Universal Template

To use the Universal Template, you first must perform the following steps.

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications, below.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

Python code modifications should not be done.
Template Modifications
- General Section
  - "Name", "Extension", "Variable Prefix", and "Icon" should not be changed.
- Universal Template Details Section
  - "Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
  - Success and Failure Exit codes should not be changed.
  - Success and Failure Output processing should not be changed.
- Fields Restriction Section
  The template setup does not impose any restrictions concerning the "Exit Code Processing Fields" section.
  1. Success/Failure exit codes need to be respected.
  2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered reliable sources for determining the success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents:

Document Link	Description
Universal Templates	User documentation for creating, working with, and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.

Changelog

ue-openshift-jobs-1.2.0 (2024-08-29)

Enhancements

Added: Ability to retrieve log files for containers pertaining to the executed job and print to desired output stream (#41071).

ue-openshift-jobs-1.1.0 (2024-04-11)

Enhancements

Added: Compatibility with Windows (#35711).
Added: Ability to delete registered jobs (#36109).
Added: Ability to automatically delete finished jobs (#36256).
Added: New dynamic command named "Delete Job" that enables the deletion of running jobs during task execution (#36108).
Added: Support for job definitions as URLs, handy when job definitions are stored in source code repositories (#36011).

ue-openshift-jobs-1.0.0 (2024-01-04)

Initial Release