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 |
---|---|---|
OpenShift Jobs | ue-openshift-jobs | 1.0.0 |
Refer to the Changelog for version history information.
This integration bundles Openshict CLI version 4.13.14.
Software 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 Linux Agents of version >= 7.5 are supported. |
Universal Controller | Universal Controller Version >= 7.5.0.0. |
OpenShift and OpenShift CLI | Openshift and Openshift CLI version = 4.13.14. It should be compatible with later versions as long as backward compatibility is preserved on future versions. |
Network and Connectivity | Connectivity towards OpenShift. |
Key Features
Feature | Description |
---|---|
Run OpenShift Jobs | Run a single OpenShift Job using a resource file and monitor its completion. |
Authentication Options | The supported authentication methods are Basic Authentication, Session Token Authentication, and Webconsole Token Authentication. |
Supported Actions
Action: Run Job
The “Run Job” Action is used to run a job using a specific Job Resource Definition which represents the definition of an OpenShift Job.
Configuration examples
Scenario A Connect to a local OpenShift server with session token authentication, select the project “my_project” and run a job by applying a job definition that is saved as a UC script. After starting the job poll for the job’s status till the job has finished. | Scenario B 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 starting the job poll for the job’s status for 10 poll cycles. |
Action Output
Output Type | Description | Example (Successful Execution) |
---|---|---|
EXTENSION
|
| { "exit_code": 0, "status_description": "Task executed successfully.", "invocation": { "extension": "ue-openshift-jobs", "version": "1.0.0", "fields": {...} }, "result": { "jobs": [ { "command": "oc get jobs/pi -o json --kubeconfig=/tmp/tmpa1293d_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://api.crc.testing:6443 -u **** -p **** --insecure-skip-tls-verify --kubeconfig=/tmp/tmpa1293d_config", "exit_code": 0 }, { "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc project my_project --kubeconfig=/tmp/tmpa1293d_config", "exit_code": 0 }, { "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc apply -f /var/opt/universal/tmp/62a23f72-955d-4a32-a3af-aa785146e394 --kubeconfig=/tmp/tmpa1293d_config", "exit_code": 0 }, { "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc get jobs/pi -o json --kubeconfig=/tmp/tmpa1293d_config", "exit_code": 0 }, { "command": "/var/opt/universal/uag/extensions/.ue-openshift-jobs/vendor/oc logout --kubeconfig=/tmp/tmpa1293d_config", "exit_code": 0 } ] } } } |
Example (Failed Execution) | ||
{ "exit_code": 1, "status_description": "Command Execution Error: Could not start job.", "invocation": { "extension": "ue-openshift-jobs", "version": "1.0.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 Task Instance STDOUT. | 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 Logged "****" out on "https://localhost:6443" |
Input Fields
Field | Type | Default Value | Mandatory | Description | Introduced in Version |
---|---|---|---|---|---|
Action | Choice | Run Job | Yes | The action to be executed. Default Option “Run Job” executes an OpenShift Job | 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 | 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. | 1.0.0 | |
Login Method | Choice | Basic Authentication | Yes | The Login Method used
| 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:
In case field Login Methon is set to “Webconsole Token“ the definition of the credential should be:
| 1.0.0 | |
Job Resource Definition Source | Choice | UAC Script | Yes | Job Resource can be retrieved in multiple ways. Users can select either a path on the local filesystem or use a UAC Script. Possible options:
| 1.0.0 |
Job Resource Definition | Script | No | The actual UAC Script containing the Job definition. This field is 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. | 1.0.0 | |
Job Resource Definition File | Text | No | The Agent’s local full filename path from which the Job definition is retrieved. This field is 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. | 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. | 1.0.0 | |
Wait for Completion | Bool | true | Yes | A Switch that controls whether the UAC task will wait until the Job is completed. | 1.0.0 |
Polling Interval (sec) | Integer | 15 | No | The time between retries for getting the status of the run command Mandatory if Wait for Success or Failure is “true” 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. | 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 to Polling Interval (sec)) 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. | 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 choices are available:
| 1.0.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.
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. |
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
During the execution of the task, several “oc” commands are executed. The command outputs will be printed to STDOUT.
Note: 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.
STDOUT and STDERR provide additional information to the User. The populated content can be changed in future versions without notice. Backward compatibility is not guaranteed.
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.Success/Failure exit codes need to be respected.
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 |
---|---|
User documentation for creating, working with, and understanding Universal Templates and Integrations. | |
User documentation for creating Universal Tasks in the Universal Controller user interface. |
Changelog
ue-openshift-jobs-1.0.0 (2024-01-04)
Initial Release