Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

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“, “status“, “status_description“: General info regarding the task execution. In case of failure, ththat ey are 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” > “job_info”: The latest Information gathered related to the executed job. 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

{
    "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

  • Basic Authentication

  • Webconsole Token

  • Session Token

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”

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:

  • UAC Script

  • Local File

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:

  • 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

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.

  1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

  2. To import the Universal Template into your Controller, follow these instructions.

  3. 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.0.0 (2024-01-04)

Initial Release

  • No labels