Package: powershift-image
This package provides a plugin for thepowershiftcommand line client
which contains commands for assisting in the building and running of Python
S2I based images with OpenShift.This includes adding OpenShift V2 style action hooks and job scripts,
as well as extensions to additionally allow environment variables to be
dynamically set for both builds and deployments. Additional hooks
scripts can be provided related to verifying an image after a build,
performing initial setup of data required by an application, data
migration on deployments with updated application source code, readiness
checks and liveness checks. Commands are also provided for starting an
interactive shell or running programs with the same environment as an
application is deployed with.This package requires that thepowershift-clipackage also be installed.
To install thepowershift-clipackage, and thepowershiftcommand
line program contained in that package, along with this plugin, you should
usepipto install the packagepowershift-cli[image], rather than
justpowershift-image.Be aware that this package is only usable in the context of building and
deploying an application being built into an image using the Python S2I
builder. There is no point installing it in your personal development
environment as it is dependent on the specific environment of the Python
S2I builder image and how it adds application source code to that image
during the build process.The normal way which the package would be installed for use, would be to add
to the.s2i/bin/assemblescript of application source code being used
with the Python S2I builder:#!/bin/bash
pip install --no-cache-dir powershift-cli[image]
exec powershift image assembleA corresponding.s2i/bin/runscript would be also be created which
contains:#!/bin/bash
exec powershift image runBoth these scripts should be made executable.All other commands provided by the plugin would then always be executed in
the running container created by the Python S2I builder these scripts were
incorporated in.For more details on how to install thepowershiftcommand line program
and available plugins see:https://github.com/getwarped/powershift-cliAvailable commandsTo see all available commands you can use inbuilt help features of thepowershift image.Usage: powershift image [OPTIONS] COMMAND [ARGS]...

  Assemble S2I based image and run application.

  Extends S2I based image build and execution to incorporate action
  hooks which can customize installation and setup of the application,
  as well as the environment used when the application is run.

  Provides the means to create an interactive shell or run commands in
  the container with the same environment as the application.

  Also, allows the manual running of custom action hooks for initial
  setup of data, run data migration when updating to a new version of
  the application, verify an application after a build, test for
  readiness or liveness of an application.

Options:
  --help  Show this message and exit.

Commands:
  alive     Trigger action hook which tests if alive.
  assemble  Runs the build process for the image.
  exec      Run a command with application environment.
  jobs      Run job scripts in specified category.
  migrate   Triggers action hook to migrate any data.
  ready     Trigger action hook which tests if ready.
  run       Runs the application built into the image.
  setup     Triggers action hook to setup any data.
  shell     Create a shell with application environment.
  verify    Trigger action hook which verifies image.Types of Action HooksUnder OpenShift V2, the action hooks which were provided were:pre_build- Executed prior to building application artefacts.build- Executed after building application artefacts.deploy- Executed prior to starting the application.post_deploy- Executed after the application has been started.Equivalent hooks to all butpost_deploycan readily be implemented
in V3. The reason thatpost_deploycannot be implemented is that
when using Docker, the application is generally left running as process
ID 1. That is, no process manager is usually used within a running
Docker container.That there is no overarching process manager makes it somewhat difficult to
run something after the application has been started as the application
actually keeps control and is not running in background. Solutions such as
runningpost_deployin the background, delayed by a sleep, isn’t
practical as you can’t be sure the application has actually been started
properly before running it.If required, anything likepost_deployis better implemented outside of
the container, using features of OpenShift such as lifecycle hooks.As well as not implementingpost_deploy, personal experience from
working in Python suggests that the action hooks are better off modelled a
bit differently than in V2 with additional functionality added. For this
implementation though we have to keep reasonably close to the original in
OpenShift V2 as it isn’t possible to break open the original S2Iassembleandrunscripts to insert additional hook points. This
does impose certain limitations onpre_buildas explained below.Two new action hooks that are added though arebuild_envanddeploy_env. Technically these aren’t hook scripts in the way the
existing OpenShift V2 actions are. This is because they will not be
executed as a distinct process, but inline to the replacementassembleandrunscripts. Their purpose is to allow additional environment
variables to be dynamically set. This can be important when needing to set
environment variables dynamically based on information extracted from
packages installed as part of the build process.Finally arunaction hook is also allowed. This if supplied will
supersede therunscript provided in the S2I builder. It is expected
that it runs the application to be deployed. It must not return and
must ensure the application run inherits the process ID of the script.Using the Action HooksTo add your own action hooks, create the following files as necessary:.s2i/action_hooks/pre_build.s2i/action_hooks/build_env.s2i/action_hooks/build.s2i/action_hooks/deploy_env.s2i/action_hooks/deploy.s2i/action_hooks/runThepre_build,build,deployandrunscripts must all be
executable. This is necessary due to a bug in Docker support for some file
systems. It is not possible for theassemblescript to dochmod +xon scripts prior to running. If you forget the implementation of actions
hooks provided will warn you.Thepre_build,build,deployandrunscripts would normally
be shell scripts, but could technically be any executable program you can
run to do what you need. If using a shell script, it is recommended to
set:set -eo pipefailso that the scripts will fail fast, with an error propagated back up to theassembleorrunscript. You can print out messages from these
scripts if necessary to help debugging.Thebuild_envanddeploy_envscripts must be shell scripts. They do
not need to be executable nor have a#!line. They will be executed
inline to theassembleandrunscripts, being interpreted as abashscript.Thesebuild_envanddeploy_envscripts can be used to set any
environment variables you need to set. It is not necessary to export
variables as any variables set in the scripts will be automatically
exported. Being evaluated as a shell script, you can include shell logic or
use inline parameter substitution. You can thus do things like:LOGLEVEL=${LOGLEVEL:-1}Just keep in mind that if including complicated logic that requires
temporary variables, that they will be automatically exported. You may wish
to use shell functions and bash local variables to restrict what is
exported to whatever is set at global scope.You should not print any messages fromdeploy_envas that will be
executed for any shell session and the output may interfere with the result
when running one off commands usingpowershift image exec.In the case of thepre_buildaction hook, be aware that unlike in V2,
the application source code will not have been copied into place at that
point. If this script needs to reference any files which are provided with
the application source code, it will need to access them from the/tmp/srcdirectory where they are held before being moved into the
correct location by the originalassemblescript.Running Action CommandsIn addition to the action hooks which will be executed during the build and
deployment of the application, you can also provide additional action hooks
which can be executed with specific commands. These are:verify- Commands to verify an image. Would be run frompostCommitaction of a build configuration to test an image before it
is used in a deployment.ready- Commands to test whether the application is ready to accept
requests. Would be run from a readiness health check of a deployment
configuration.alive- Commands to test whether the application is still running
okay. Would be run from a liveness health check of a deployment
configuration.setup- Commands to initialize any data for an application, including
perhaps setting up a database. Would be run manually, or if guarded by
a check against being run multiple times, could be run from adeployaction hook script.migrate- Commands to perform any data migration, including perhaps
updating a database. Would be run from a mid lifecycle hook if using the
recreate deployment strategy, or from adeployaction hook script if
it is not a scaled application and not using rolling deployments.An appropriate executable script with corresponding names would be added to
the.s2i/action_hooksdirectory. It would be run with the corresponding
sub command ofpowershift image. In all cases thedeploy_envscript
will be sourced to ensure that the same environment variables as would be
used for the deployment of the application are also used for these.The benefit of using these action hooks triggered by a command, is that
only the unchanging action command need be listed in build or deployment
configurations if required. This makes it possible to make changes to what
is run from the hook script and you do not need to ensure you update the
build or deployment configuration in sync with the changes to the
application source code.Executing Cron Job ScriptsUnder OpenShift V2, in addition to the action hooks mechanism, it was also
possible to provide sets of scripts to be executed at regular intervals bycronrunning in the OpenShift environment.This script doesn’t provide a replacement forcron, but does provide
a helper command for executing a set of scripts under a specified
category, such as ‘hourly’. This command could be run in a distinct
container to the running application from an OpenShiftCronJob, or by a
daemon process running in the application container which implements
cron like functionality.There is no restriction on the category names for the job scripts, but
as a starting point it is suggested you use the same names supported under
OpenShift V2. For each category you want to use, create a sub directory
under.s2i/jobs. For example:.s2i/jobs/minutely.s2i/jobs/hourly.s2i/jobs/daily.s2i/jobs/weekly.s2i/jobs/monthlyIn that sub directory, add your jobs script and make the script file
executable. For example, if you were running a web application which used
Django, you might create the cron job script:.s2i/jobs/hourly/clearsessionswhere the contents of the executable script file contains:#!/bin/bash

set -eo pipefail

python manage.py clearsessionsThe command used with the OpenShiftCronJobset to be executed hourly
would then be:powershift image jobs hourlyInteractive Shell and CommandsIf needing to start an interactive shell with the same environment as the
deployed application, usepowershift image shell. To execute a one off
command with the same environment, usepowershift image execand supply
the program and options as arguments.