Disclaimer

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

Version Information

Template Name	Extension Name	Version	Status
OpenShift CLI	ue-openshift-cli	1 (Current 1.0.0)	Fixes and new Features are introduced.

Refer to the Changelog for version history information.

This integration bundles Openshict CLI version 4.13.14.

Overview

This integration acts as an interface to OpenShift CLI (oc) enabling users to run any OpenShift command from the Universal Agent. OpenShift CLI (oc) is bundled within this integration and does not require separate installation.

Key Features

Feature	Description
Run OpenShift Commands	Run any OpenShift command in the selected OpenShift cluster.
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.

Software Requirements

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

Area	Details
Python Version	Requires Python of version 3.11, 3.9 or 3.7.
Universal Agent Compatibility	Compatible with Universal Agent for Windows x64 and version >= 7.5.0.0. Compatible with Universal Agent for Linux and version >= 7.5.0.0.
Universal Controller Compatibility	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. 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: Execute Command

The “Execute Command” Action is used to execute an OpenShift command.

Commands should start with the 'oc' keyword.

Configuration examples


Scenario A: Connect to a local OpenShift server with basic authentication and select the project “uac”.	Scenario B: Connect to a local OpenShift server using a web console token and get the list of registered jobs in JSON format.

Action Output

Output Type

Description

Executions

EXTENSION

The extension output provides the following information:

exit_code, status_description: General info regarding the task execution. For more information, users can refer to the exit code table.
invocation.fields: The task configuration used for this task execution.
result.metadata.commands: A list containing all the oc commands executed.
- command
- exit_code
result.openshift_json_output: The OpenShift JSON result, in case the command output is in JSON format.

Successful Execution

{
    "exit_code": 0,
    "status_description": "Task executed successfully.",
    "invocation": {
        "extension": "ue-openshift-cli",
        "version": "1.0.0",
        "fields": {...}
    },
    "result": {
        "openshift_json_output": null,
        "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
                }
            ]
        }
    }
}

Failed Execution

{
    "exit_code": 1,
    "status_description": "Command Execution Error: project.project.openshift.io "cookbook" already exists.",
    "invocation": {
        "extension": "ue-openshift-cli",
        "version": "1.0.0",
        "fields": {...}
    },
    "result": {
        "openshift_json_output": null,
        "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 new-project my_project --kubeconfig=/tmp/tmpa1293d_config",
                    "exit_code": 1
                }
            }
        }
    }
}

STDOUT

The STDOUT output of the oc commands is displayed on the Task Instance STDOUT.

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".
Logged "****" out on "https://localhost:6443"

Input Fields

Name	Type	Description	Version Information
Action	Choice	The action performed upon the task execution. Run Command (default).	Introduced in 1.0.0
OpenShift Server and Port URL	Text	The OpenShift Server and Port information. Used by oc to communicate with the OpenShift Server.	Introduced in 1.0.0
Login Method	Choice	The Login Method to be used. The following options are available. Basic Authentication (default). Web Console Token. Session Token.	Introduced in 1.0.0
OpenShift Credentials	Credentials	The credentials used to login to OpenShift. In case the 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 the field Login Methon is set to “Web Console Token“ the definition of the credential should be: The Token as the Credential’s “Token”.	Introduced in 1.0.0
Additional Login Parameters	Text	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
Command	Large Text	The OpenShift command to be executed. Commands should begin with the “oc” word.	Introduced in 1.0.0
Extension Output Options	Multiple Choice	Controls whether additional information is printed on Extension output. One or more choices can be selected. The following options are available. Include Task Metadata: includes a list of oc commands executed along with their metadata.	Introduced in 1.0.0

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	“SUCCESS: Task executed successfully.“	Successful Execution.
1	Failure	“Execution Failed: <<Error Description>>”	Generic Error. Raised when not falling into the other Error Codes.
1	Failure	“Command Execution Error: <<Error Description>>”	Raised when an OpenShift command fails.
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.

STDOUT and STDERR

During the execution of the task, several “oc” commands are executed. The oc command STDOUT is printed to UAC task instance STDOUT.

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.

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 setup of the template does not impose any restrictions. However, 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-cli-1.0.0 (2024-05-16)

Initial Release.