Skip to main contentIBM ST4SD

Using the OpenShift CLI

This page shows how to use the OpenShift CLI to interact ST4SD.

iPython notebooks make it easy to run and work with virtual experiments. However there is often a need to go deeper, especially for developers. In this case using the OpenShift CLI via a terminal is invaluable.

  • For: Researchers, Developers and Administrators
  • Use-When:
    • Researchers: You want to go deeper into the outputs of a particular workflow using standard terminal tools
    • Developers: Debugging virtual experiments. Inspecting and deleting workflows.
    • Administrators: Inspecting and deleting workflows.
  • Skill Requirements:
    • Being comfortable with working with command-line technologies
    • Some knowledge of OpenShift/K8s CLI tools

Software Requirements

The basic requirements are:

  • Access to an OpenShift instance with the ST4SD stack installed (see first steps for more information)
  • OpenShift command line tools installed

Getting Started

Terminology

In the following we use

  • component to refer to a task/step in a workflow.
  • workflow to mean a particular encoding of a set of steps
  • workflow instance to mean a particular execution of a workflow

Logging-In to the Cluster

To run from a terminal you first need to login to the OpenShift cluster you want to run on. You can use user/password e.g.

oc login -u $USERNAME $CLUSTER

or copy the login command from the OpenShift console of the cluster you want to run in:

  1. Navigate to the console, login,
  2. Click on your name in upper right corner
  3. Click Copy Login Command
  4. Paste the copied command into the terminal and run it

Running a Workflow

Running from a terminal involves two steps

  1. Writing a short file in YAML that describes the workflow you want to run
    • We call it workflow.yaml here but you can call it anything
  2. Executing oc apply -f workflow.yaml

Here is an example yaml for launching the sum-numbers toy workflow. You can use this as a template for your writing your own workflow yaml. This document gives a detailed description of all the available fields.

You can also try running the sum-numbers workflow via this yaml

oc apply -f docs/examples/sum-numbers.yaml

This currently assumes that various objects in the target ST4SD instance you want to run on have been named following the conventions outlined in the ST4SD installation guide. We hope to remove this requirement shortly.

If the above works it will create a workflow object called sn - this is determined by the value of the name field in the workflow yaml.

I get st4sd.ibm.com/sn unchanged

This means someone already has run a workflow with the same name in the same instance of ST4SD. Execute

oc delete workflow sn

to remove the old version and try the apply command again.

The oc delete command does not affect the files that the workflow instance has already generated under the persistent volume storage. However, it does trigger the workflow instance, and any components that are still running, to terminate. It also deletes any Kubernetes objects that have been created by the workflow instance. See Querying a workflow kubernetes object for more information on retrieving the status of a workflow via oc.

Names and Labels

Every kubernetes object