Workshop runtime

Your workshop content can script the steps a user must run for a workshop. In some cases, you must parameterize that content with information from the runtime environment. Data variables in workshop content allow this to a degree, but you can automate this by using scripts executed in the workshop container to set up configuration files.

Do this by supplying setup scripts that run when the container is started. You can also run persistent background processes in the container that perform extra work for you while a workshop is being run.

Predefined environment variables

When you create the workshop content, you can use data variables to automatically insert values corresponding to the specific workshop session or environment. For example: the name of the namespace used for the session and the ingress domain when creating an ingress route.

These data variables can display a YAML/JSON resource file in the workshop content with values already filled out. You can have executable commands that have the data variables substituted with values given as arguments to the commands.

For commands run in the shell environment, a number of predefined environment variables are also available that can be referenced directly.

Key environment variables are:

  • WORKSHOP_NAMESPACE - The name of the namespace used for the workshop environment.
  • SESSION_NAMESPACE - The name of the namespace the workshop instance is linked to and into which any deployed applications run.
  • INGRESS_DOMAIN - The host domain that must be used in any generated host name of ingress routes for exposing applications.
  • INGRESS_PROTOCOL - The protocol (http/https) used for ingress routes created for workshops.

Instead of having an executable command in the workshop content, use:

```execute
kubectl get all -n %session_namespace%
```

With the value of the session namespace filled out when the page is rendered, you can use:

```execute
kubectl get all -n $SESSION_NAMESPACE
```

The shell inserts the value of the environment variable.

Running steps on container start

To run a script that makes use of the earlier environment variables when the container is started, and to perform tasks such as pre-create YAML/JSON resource definitions with values filled out, you can add an executable shell script to the workshop/setup.d directory. The name of the executable shell script must have a .sh suffix to be recognized and run.

If the container is restarted, the setup script runs again in the new container. If the shell script is performing actions against the Kubernetes REST API using kubectl or by using another means, the actions it performs must be tolerant of running more than once.

When using a setup script to fill out values in resource files, a useful utility is envsubst. You can use this in a setup script as follows:

#!/bin/bash

envsubst < frontend/ingress.yaml.in > frontend/ingress.yaml

A reference of the form ${INGRESS_DOMAIN} in the input file is replaced with the value of the INGRESS_DOMAIN environment variable.

Setup scripts have the /home/eduk8s directory as the current working directory.

If you are creating or updating files in the file system and using a custom workshop image, ensure that the workshop image is created with correct file permissions to allow updates.

Running background applications

The setup scripts run once on container startup. You can use the script to start a background application needed to run in the container for the life of the workshop, but if that application stops, it does not restart.

If you must run a background application, you can integrate the management of the background application with the supervisor daemon run within the container. To have the supervisor daemon manage the application for you, add a configuration file snippet for the supervisor daemon in the workshop/supervisor directory. This configuration file must have a .conf extension.

The form of the configuration file snippet must be:

[program:myapplication]
process_name=myapplication
command=/opt/myapplication/sbin/start-myapplication
stdout_logfile=/proc/1/fd/1
stdout_logfile_maxbytes=0
redirect_stderr=true

The application must send any logging output to stdout or stderr, and the configuration snippet must direct log output to /proc/1/fd/1 so it is captured in the container log file. If you must restart or shut down the application within the workshop interactive terminal, you can use the supervisorctl control script.

Terminal user shell environment

Neither the setup scripts that run when the container starts nor background applications affect the user environment of the terminal shell. The shell environment makes use of bash and the $HOME/.bash_profile script is read to perform added setup for the user environment. Because some default setup is included in $HOME/.bash_profile, you must not replace it, because you can loose that configuration.

To provide commands to initialize each shell environment, you can provide the file workshop/profile. When this file exists, it is sourced at the end of the $HOME/.bash_profile file when it is processed.

Overriding terminal shell command

The user starts each terminal session by using the bash terminal shell. A terminal prompt dialog box displays, allowing the user to manually enter commands or perform clickable actions targetting the terminal session.

To specify the command to run for a terminal session, you can supply an executable shell script file in the workshop/terminal directory.

The name of the shell script file for a terminal session must be of the form <session>.sh, where <session> is replaced with the name of the terminal session. The session names of the default terminals configured to be displayed with the dashboard are 1, 2, and 3.

The shell script file might be used to run a terminal-based application such as k9s, or to create an SSH session to a remote system.

#!/bin/bash

exec k9s

If the command that is run exits, the terminal session is marked as exited and you need to reload that terminal session to start over again. Alternatively, you could write the shell script file as a loop so it restarts the command you want to run if it ever exits.

#!/bin/bash

while true; do
    k9s
    sleep 1
done

If you want to run an interactive shell and output a banner at the start of the session with special information for the user, use a script file to output the banner and then run the interactive shell:

#!/bin/bash

echo
echo "Your session namespace is "$SESSION_NAMESPACE".
echo

exec bash
check-circle-line exclamation-circle-line close-line
Scroll to top icon