Plug-in Documentation

OpenShift for IBM UrbanCode Deploy

Overview

The OpenShift plug-in includes steps to interact with OpenShift applications in IBM UrbanCode Deploy.

Compatibility

This plug-in works with OpenShift CLI 3.1 and later.

The OpenShift server must be accessible from the IBM UrbanCode Deploy agent.

This plug-in requires version 6.0.1 or later of IBM UrbanCode Deploy.

Installation

No special steps are required for installation. See Installing plug-ins in IBM UrbanCode Deploy.

History

Version 17

  • Added the Expose step and change implementation for Patch Secret from REST API to oc command

Version 16

  • Allow using oc apply or oc create in Create Object From Template step. Indicate \deploy\ command is deprecated for later versions of Openshift. Introduces the New-App, Set Triggers, Set Image, Set Env, New Build, Start Build, Cancel Build, Create, Delete and Login steps. Remove login operation for every plugin step execution and if login parameters are given include them as part of the oc command

Version 14

  • Introduces token support for Create Secret, Patch Secret and Replace DeploymentConfig.

Version 13

  • Introduces the Rollout step which fixes APAR PH02968 OpenShift plug-in does not support oc rollout command.

Version 12

  • Introduces the Apply step.

Version 11

  • Updated to ensure all response texts are zOS compatible.

Version 10

  • Remove oc version check before oc login.

Version 9

  • Fix to parameter passing in Create Object From Template step.
  • Allows for pull secrets and app secrets to be patched at once.

Version 8

  • Create Object From Template step now allows for parameter file to be passed in.

Version 7

  • Fixes to Create Object from Template step. Plugin collects token automatically when using REST steps. JSON files can be passed in as well as JSON.

Version 6

  • Added step Create Object from Template.

Version 5

  • Added steps Create Secret, Patch Secret, Replace DeploymentConfig and Patch DeploymentConfig.

Version 4

  • Support property file encryption.

Version 3

  • Updated to work with oc CLI 3.1.
  • Changed Resource Type in Scale step to dropdown.

Version 2

  • A fix for an issue related to setting the oc script home.
  • The Resource Type field in the Scale step is now a drop-down list.

Version 1

  • The initial release of the plug-in includes steps to deploy, roll back, scale and tag an application in OpenShift.

Usage

Using the Create New-App step

Use the Create New-App step to generate OpenShift Container Platform objects that build, deploy, and run the application being created. For more information, see the Openshift documentation.

The following example demonstrates using the step to create an application using a remote git repository. While this demonstration uses a generic process, a component process part of a component can be created using the Openshift source configuration plug-in. The following image shows the plug-in step properties where we specify the source.

The source can be a local or remote git repository, source code path, image, template, and more. If the source is code, you can use the GitHub Source-to-Image (S2I) tool which creates a container image from source based on the source language. It creates build configurations, deployment configurations and services. You can see the output log below.

Using the Set Triggers step

Use the Set Triggers step to set or remove triggers for build configurations, deployment configurations, and other workload objects. The triggers can create a new build or deployment when an image changes. The image below shows the step properties. The RESOURCE/NAME property is used to specify which resource are needed to set triggers and the Step Flags property to specify options like manual, auto or remove triggers.

Output log

[Action] Executing set triggers Operation...
command: oc set triggers dc/alpine bc/cakephp-ex --auto
[Ok] Set triggers operation succeeded.
deploymentconfig.apps.openshift.io/alpine triggers updated
buildconfig.build.openshift.io/cakephp-ex triggers updated

Using the Set Image step

The Set Image step updates the existing container images of resources. The following image shows the configuration to update the deployment configuration image alpine which exists in Openshift.


[Action] Executing set image Operation...
command: oc set image dc/alpine alpine=alpine:3.10.0
[Ok] Set image operation succeeded.
deploymentconfig.apps.openshift.io/alpine image updated

Set Env step

The Set Env step updates environment variables on a pod template or a build configuration. The following image shows the step configuration to update environment variables for the Openshift cakephp-ex deployment configuration.


[Action] Executing set env Operation...
command: oc set env dc/cakephp-ex STORAGE_DIR=/local ENV2=val2
[Ok] Set env operation succeeded.
deploymentconfig.apps.openshift.io/cakephp-ex updated

Steps

Process steps in the OpenShift plug-in

Add Tag

Tag existing images into image streams.

Input properties for the Add Tag step
Name Type Description Required
Access Token Password The token used to authenicate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Destination Names String The image streams to tag. Separate multiple image streams with space characters. Use
the following format: <namespace>/<stream_name >:<tag>
Yes
Keep Updated Boolean Select to update the destination tag each time the source tag changes. No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the resource to tag. No
Source Name String The name of the source to tag. For example: <namespace>/<stream_name>:<tag>,
<name>@<id>
Yes
Source Type Enumeration:

  • none
  • istag
  • isimage
  • docker
Specify a source type to use. No
Step Flags String A list of flags to set when running the add tag command. Specify each flag on a new
line.
No
User Name String The user name used to authenicate with the OpenShift server. No

Apply

Apply a configuration to a resource by filename.

Input properties for the Apply step
Name Type Description Required
Access Token Password The token used to authenicate with the OpenShift API server. CYou can use either
this property or the User Name and Password properties to authenticate with the server.
No
File Name String The file to be applied. If a directory is specified, all files in that directory are
applied.
Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project where the resource is applied. No
Step Flags String A list of flags to set when running the apply process. For example:
–force=false. Specify each flag on a new line.
No
User Name String The user name to authenicate with the OpenShift server. No

Cancel Build

Request a graceful shutdown of a build. Running, pending, or new builds are canceled.

Input properties for the Cancel Build step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Build Config(s) String The builds to be cancelled created from specified Build Configs No
Build(s) String The build to be cancelled. No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to cancel a build. No
Step Flags String A list of flags to set when running the cancel-build command. Specify each flag on
a new line.
No
User Name String The user name used to authenicate with the OpenShift server. No

Create

Create a resource by filename.

Input properties for the Create step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
File Name String File to be created. Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project where the resource is created. No
Step Flags String A list of flags to set when running the create process. Specify each flag on a new
line.
No
User Name String The user name used to authenticate with the OpenShift server. No

Create New-App

Create a new application by specifying source code, templates, and/or images.

Input properties for the Create New-App step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to run the deployment on. No
Source String The source code path, source code repository URL, template, image or image stream No
Step Flags String A list of flags to set when running the new-app command. Specify each flag on a new
line.
No
User Name String The user name used to authenicate with the OpenShift server. No

Create Object From Template

Create object on OpenShift server from a JSON template.

Input properties for the Create Object From Template step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Do you want to use ‘apply’ or ‘create’? String Specify create to create the configuration if it does not exist. An error is displayed
if the create is specified and the configuration already exists. Specify apply
to update the configuration. The default value is apply. For more details, see the
Openshift/Kubernetes documentation.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Parameter File String The fully-qualified path of a newline-separated parameter file. No
Project String The OpenShift project that contains the application to run the deployment on. No
Step Flags String A list of flags to set when running the create object from template command. Specify
each flag on a new line.
No
Template String The fully-qualified path to the template JSON file to be used to create the object. Yes
User Name String The user name to access the OpenShift server. No

Create Secret

Create secret in OpenShift.

Input properties for the Create Secret step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Password Password The password used to authenicate with the OpenShift server. No
Project String The OpenShift project that contains the application to run the deployment on. No
Secret JSON String A JSON string or the fully-qualified path to the JSON file containing the JSON for
the secret to be created.
Yes
User Name String The user name used to authenicate with the OpenShift server. No

Delete

Delete resources by filenames, stdin, resources and names, or by resources and label
selector.

Input properties for the Delete step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to delete a resource. No
Resource(s)/resource names String Please check Openshift documentation on the format to specify for resource and resource
names
Yes
Step Flags String A list of flags to set when running the delete command. Specify each flag on a new
line.
No
User Name String The user name used to authenticate with the OpenShift server. No

Deploy

(Deprecated)Start, cancel, retry or view a deployment on an OpenShift server.

Input properties for the Deploy step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either
this property or the User Name and Password properties to authenticate with the server.
No
Deployment Action Enumeration:

  • latest
  • retry
  • cancel
  • triggers
  • history
Select deployment action. No
Deployment Config String The deployment configuration to use. Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to run the deployment on. No
Step Flags String A list of flags to set when running the deploy command. Specify each flag on a new
line.
No
User Name String The user name to access the OpenShift server. No

Expose

Expose containers internally as services or externally through routes.

Input properties for the Expose step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to expose a resource as a route
or a service.
No
Resource(s)/resource names String Please check Openshift documentation on the format to specify for resource and resource
names
Yes
Step Flags String A list of flags to set when running the expose command. Specify each flag on a new
line.
No
User Name String The user name to access the OpenShift server. No

Login

Log in to your Openshift server and save login for subsequent use.

Input properties for the Login step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Certificate Authority String The path to a certificate file for the certificate authority. No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Password Password The password used to authenticate with the OpenShift server. No
Project String The OpenShift project that contains the application to login. No
Skip TLS Verification Boolean Select to not validate the server certificate. If selected, HTTPS connections are
not secure.
No
Step Flags String A list of flags to set when running the login command. Specify each flag on a new
line.
No
User Name String The user name used to authenticate with the OpenShift server. No

New Build

Create a new build by specifying source code

Input properties for the New Build step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to create a new build. No
Sourcecode/Image path String The sourcecode used to create the build. It can be a combination of image~sourcecode No
Step Flags String A list of flags to set when running the new-build command. Specify each flag on a
new line.
No
User Name String The user name used to authenicate with the OpenShift server. No

Patch DeploymentConfig

Patch/Update a Deployment Config.

Input properties for the Patch DeploymentConfig step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Deployment Config String The name of the current deployment configuration. Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Patch JSON String The JSON or the fully-qualified path to the JSON file containing the JSON to be used. Yes
Project String The OpenShift project that contains the application to run the deployment on. No
Step Flags String A list of flags to set when running the patch deployment config command. Specify each
flag on a new line.
No
User Name String The user name used to authenicate with the OpenShift server. No

Patch Secret

Patch secret in OpenShift.

Input properties for the Patch Secret step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
App Secrets String A list of app secrets to patch. Specify each list item on a new line. At least one
Secrets field must be specified.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Password Password The password used to authenticate with the OpenShift server. No
Project String The OpenShift project that contains the application to run the deployment on. No
Pull Secrets String A list of pull secrets to patch. Specify each list item on a new line. At least one
Secrets field must be specified.
No
ServiceAccount Name String The name of ServiceAccount to create secret for. Yes
Step Flags String A list of flags to set when running the patch secret command. Specify each flag on
a new line.
No
User Name String The user name used to authenicate with the OpenShift server. No

Replace DeploymentConfig

Deploy using a new deployment configuration for an existing application in OpenShift.

Input properties for the Replace DeploymentConfig step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Deployment Config String The name of the current deployment configuration. Yes
New Deployment Config JSON String The JSON or the fully-qualified path to the JSON file for the new deployment configuration
to use.
Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Password Password The password to authenicate with the OpenShift server. No
Project String The OpenShift project that contains the application to run the deployment on. No
User Name String The user name to authenicate with the OpenShift server. No

Rollback

Roll back an application to a previous deployment.

Input properties for the Rollback step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Change Scaling Settings Boolean Include the replication controller replica count and selector of the previous deployment
in the rollback.
No
Change Strategy Boolean Include the strategy of the previous deployment in the rollback. No
Change Triggers Boolean Include the triggers of the previous deployment in the rollback. No
Deployment Name/Config String The name of the previous deployment or deployment configuration to roll back to. Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to run the roll back on. No
Step Flags String A list of flags to set when running the rollback command. Specify each flag on a new
line.
No
User Name String The user name used to authenicate with the OpenShift server. No
Version String The specific configuration version to roll back to. Leave blank to roll back to the
last successfully completed deployment. This field
is ignored when rolling back to a deployment instead
of a deployment config.
No

Rollout

Start a new rollout, view its status or history, rollback to a previous revision of
your app.

Input properties for the Rollout step
Name Type Description Required
Access Token Password The token to authenicate with the OpenShift API server. You can use either this property
or the User Name and Password properties to authenticate with the server
No
Deployment Config or Name String The deployment configuration or the name of a deployment depending on the rollout
type to use.
Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to run the deployment on. No
Rollout type Enumeration:

  • cancel
  • history
  • latest
  • pause
  • resume
  • retry
  • status
  • undo
Select a rollout subcommand. No
Step Flags String A list of flags to set when running the rollout command. Specify each flag on a new
line.
No
User Name String The user name to authenicate with the OpenShift server. No

Scale

Set a new size for a deployment or replication controller.

Input properties for the Scale step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Number of Replicas String The number of replicas to scale to. Yes
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to scale. No
Resource Name String The name of the resource to scale in OpenShift. Yes
Resource Type Enumeration:

  • dc
  • replicationcontrollers
The type of resource to scale in OpenShift. Yes
Step Flags String A list of flags to set when running the scale command. Specify each flag on a new
line.
No
User Name String The user name to access the OpenShift server. No

Set Env

Update environment variables on a pod template or a build config

Input properties for the Set Env step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
File Path String The filename, directory, or URL to files to use to edit the resource. No
KEY=VALUE/KEY- String A list of keys and associated value. Specify each list item in the format key=value
on a new line. You can remove the environment variable
with KEY-.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to update the environment. No
RESOURCE/NAME String A list of resource type and associated object name pairs. Specify each pair in the
format resource_type/name on a new line.
No
RESOURCES String A list of resource types, separate each resource type with a comma. For example: resource1,resource2,…resourex. No
Step Flags String A list of flags to set when running the set env command. Specify each flag on a new
line.
No
User Name String The user name used to authenticate with the OpenShift server. No

Set Image

Update existing container images of resources

Input properties for the Set Image step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
CONTAINER_NAME=IMAGE_NAME String A list of container and assocaited image name. Specify each pair in the format: container_name=image_name.
Specify each list item on a new line. You can update
image of all containers with *=image_name.
No
File Path String The filename, directory, or URL to files used to identify the resource to obtain from
the server.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to update the image. No
RESOURCE/NAME String A list of resource type and object name pair. Specify each pair in the format: resource/name.
Specify each list item on a new line.
No
RESOURCES String A list of resource types to be specified in the format resource1,resource2,…resourcex. No
Step Flags String A list of flags to set when running the set image command. Specify each flag on a
new line.
No
User Name String The user name used to authenticate with the OpenShift server. No

Set Triggers

Set or remove triggers

Input properties for the Set Triggers step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to set/update the triggers. No
RESOURCE/NAME String A list of resource type/object name to be specified in the format as shown in the
label. Specify each list item on a new line.
Yes
Step Flags String A list of flags to set when running the set triggers command. Specify each flag on
a new line.
No
User Name String The user name used to authenticate with the OpenShift server. No

Start Build

Start a new build for the provided build configuration or copy an existing build.

Input properties for the Start Build step
Name Type Description Required
Access Token Password The token used to authenticate with the OpenShift API server. You can use either this
property or the User Name and Password properties to authenticate with the server.
No
Build Config String The build configuration to be used No
From Build String The name of a build to run again. No
OpenShift URL String The URL of the Red Hat OpenShift server. For example: https://192.0.2.0:8443 No
Project String The OpenShift project that contains the application to start a build. No
Step Flags String A list of flags to set when running the start-build command. Specify each flag on
a new line.
No
User Name String The user name used to authenicate with the OpenShift server. No