The Web Terminal Operator is a useful tool that provides users with a shell environment from the Red Hat OpenShift web console. Within the shell environment, preinstalled tools such as oc and kubectl help you manage your OpenShift resources without leaving the web console. Figure 1 shows an instance of the web terminal.
In this introductory article, we will go through noteworthy nuances within the web terminal lifecycle, as well as how to further customize your web terminal to your liking using the built-in wtoctl tool.
This article is an overview of the web terminal from a user’s perspective. For an article introducing the Web Terminal Operator from a more technical and design standpoint, check out this article here.
The web terminal lifecycle
When you open a web terminal for the first time, a DevWorkspace custom resource (CR) is created. Every web terminal has its own DevWorkspace custom resource. It’s where details such as the web terminal tooling image, persistent storage details, and environment variables for your web terminal live.
From the OpenShift cluster’s perspective, this is what happens when a web terminal is running in your namespace (Figure 2).
When the web terminal is closed, the DevWorkspace CR and web terminal pod still exist (Figure 3).
The web terminal continues to run until the idle timeout, which is 15 minutes by default. After the idle timeout, the pod terminates (Figure 4).
Note:
If opening your web terminal is quite slow, this could be because the web terminal pod isn’t running yet, therefore you’re likely waiting for the pod to be up and running.
To summarize, here are a couple of key takeaways:
- Your web terminal is tied to a single DevWorkspace CR in your namespace. This ensures that your web terminal is separate from another user’s web terminal.
- Just because your web terminal isn’t open in the console, doesn’t mean that the web terminal isn’t running. The pod itself could still be running in your namespace if it hasn’t idled like in Figure 3.
Customizing the web terminal with wtoctl
What if you don't want the web terminal pod to timeout after 15 minutes? wtoctl is a tool installed in the default web terminal tooling image that allows for customizing the web terminal.
You can run wtoctl --help in your web terminal for more details.
If you want to revert the customizations performed in this article to the defaults, you can run wtoctl reset <timeout|shell|storage>. Alternatively, if you want to start a new web terminal from scratch, you can simply delete your terminal-* DevWorkspace CR within your namespace. In this case, a new DevWorkspace CR will be created the next time you open the web terminal.
Setting a new timeout
The first change we will make is the idle timeout of our web terminal, which is 15 minutes by default.
Here are some examples of how to run the command, which accepts the time formatting used by Go’s time package:
$ wtoctl set timeout 30m
$ wtoctl set timeout 1h30m
$ wtoctl set timeout 1.5hChanging the shell
The default configuration for the web terminal provides a bash shell environment. The web terminal also provides the ability to change the shell to zsh:
$ wtoctl set shell zshAfter this command is run, the web terminal will restart and will be using the zsh shell for your web terminal from now on. See Figure 5.
Enabling persistent storage
Creating a persistent volume for your web terminal is a great way to store user data such as git repositories, commonly used OpenShift templates or scripts. Do note that if you delete your web terminal's terminal-* DevWorkspace CR, the PVC used for persistent storage will also be deleted automatically.
To enable persistent storage in your web terminal, run the following command:
$ wtoctl set storage
Enter desired storage size (default: '100Mi'):
Enter desired mount path (default: '/home/user/storage'):
Adding persistent volume with size 100Mi to /home/user/storage. Is this okay? (y/N): y
devworkspace.workspace.devfile.io/terminal-vvauwn configured
Updated Web Terminal storage. Terminal may restartThe sequence above creates a PVC in your namespace, mounts it to /home/user/storage in your web terminal tooling container, and restarts the web terminal pod to apply the new change.
Additionally, wtoctl get storage specifies the configured storage for the web terminal if present, and wtoctl reset storage removes the volume from the web terminal and optionally deletes the PVC too:
$ wtoctl get storage
Persistent storage (100Mi) is mounted to /home/user/storage
$ wtoctl reset storage
Would you like to also delete the persistent volume claim used for storage (name: storage-workspace939f8f4fc6aa4130)? (y/N): y
devworkspace.workspace.devfile.io/terminal-vvauwn configured
persistentvolumeclaim "storage-workspace939f8f4fc6aa4130" deleted
Deleted persistent volume claim storage-workspace939f8f4fc6aa4130
Reset Web Terminal storage. Terminal may restartConclusion
Knowledge of the web terminal lifecycle is useful when working with and debugging web terminals. Within the default web terminal tooling image, the ever-evolving wtoctl tool can be used to further customize your web terminal environment.
In the next article, we plan to dive into the wtoctl set image command which replaces your web terminal’s tooling image with a custom image allowing for further shell customizations to tailor your web terminal experience.
