About the web terminal in the web console

You can launch an embedded command line terminal instance in the web console. You must first install the Web Terminal Operator to use the web terminal.

Cluster administrators can access the web terminal in OKD 4.7 and later.

This terminal instance is preinstalled with common CLI tools for interacting with the cluster, such as oc, kubectl,odo, kn, tkn, helm, kubens, and kubectx. It also has the context of the project you are working on and automatically logs you in using your credentials.

Web terminal is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

Installing the web terminal

You can install the web terminal using the Web Terminal Operator listed in the OKD OperatorHub. When you install the Web Terminal Operator, the custom resource definitions (CRDs) that are required for the command line configuration, such as the DevWorkspace CRD, are automatically installed. The web console creates the required resources when you open the web terminal.

Prerequisites

  • Access to an OKD cluster using an account with cluster-admin permissions.

Procedure

  1. In the Administrator perspective of the web console, navigate to Operators → OperatorHub.

  2. Use the Filter by keyword box to search for the Web Terminal Operator in the catalog, and then click the Web Terminal tile.

  3. Read the brief description about the Operator on the Web Terminal page, and then click Install.

  4. On the Install Operator page, retain the default values for all fields.

    • The fast option in the Update Channel menu enables installation of the latest release of the Web Terminal Operator.

    • The All namespaces on the cluster option in the Installation Mode menu enables the Operator to watch and be available to all namespaces in the cluster.

    • The openshift-operators option in the Installed Namespace menu installs the Operator in the default openshift-operators namespace.

    • The Automatic option in the Approval Strategy menu ensures that the future upgrades to the Operator are handled automatically by the Operator Lifecycle Manager.

  5. Click Install.

  6. In the Installed Operators page, click the View Operator to verify that the Operator is listed on the Installed Operators page.

    Prior to OKD 4.8, the Web Terminal Operator bundled all its functionality in a single Operator. As of OKD 4.8, the Web Terminal Operator installs the DevWorkspace Operator as a dependency to provide the same features.

  7. After the Operator is installed, refresh your page to see the command line terminal icon on the upper right of the console.

Using the web terminal

After the Web Terminal Operator is installed, you can use the web terminal as follows:

  1. To launch the web terminal, click the command line terminal icon (odc wto icon) on the upper right of the console. A web terminal instance is displayed in the Command line terminal pane. This instance is automatically logged in with your credentials.

  2. Select the project where the DevWorkspace CR must be created from the Project drop-down list. By default, the current project is selected.

    • The DevWorkspace CR is created only if it does not already exist.

    • The openshift-terminal project is the default project used for cluster administrators. They do not have the option to choose another project.

  3. Click Start to initialize the web terminal using the selected project.

After the web terminal is initialized, you can use the preinstalled CLI tools like oc, kubectl, odo, kn, tkn, helm, kubens, and kubectx in the web terminal.

Uninstalling the web terminal

Uninstalling the web terminal is a two-step process:

  1. Uninstall the Web Terminal Operator and related custom resources (CRs) that were added when you installed the Operator.

  2. Uninstall the DevWorkspace Operator and its related custom resources that were added as a dependency of the Web Terminal Operator.

Uninstalling the Web Terminal Operator does not remove any of its custom resource definitions (CRDs) or managed resources that are created when the Operator is installed. These components must be manually uninstalled for security purposes. Removing these components also allows you to save cluster resources by ensuring that terminals do not idle when the Operator is uninstalled.

Prerequisites

  • Access to an OKD cluster using an account with cluster-admin permissions.

Removing the Web Terminal Operator and the custom resources that support it

Use the console and the CLI to delete any existing web terminals and CRs that were created during the installation of the Web Terminal Operator.

Prior to OKD 4.8, the Web Terminal Operator used different CRDs to provide Web Terminal capabilities. To uninstall versions 1.2.1 and below of the Web Terminal Operator, refer to the documentation for OKD 4.7.

Procedure

  1. Uninstall the Web Terminal Operator using the web console:

    1. In the Administrator perspective of the web console, navigate to Operators → Installed Operators.

    2. Scroll the filter list or type a keyword into the Filter by name box to find the Web Terminal Operator.

    3. Click the Options menu kebab for the Web Terminal Operator, and then select Uninstall Operator.

    4. In the Uninstall Operator confirmation dialog box, click Uninstall to remove the Operator, Operator deployments, and pods from the cluster. The Operator stops running and no longer receives updates.

  2. Remove the CRDs used by the Operator.

    1. $ oc delete devworkspaces.workspace.devfile.io --all-namespaces \
    2. --selector 'console.openshift.io/terminal=true' --wait
    1. $ oc delete devworkspacetemplates.workspace.devfile.io --all-namespaces \
    2. --selector 'console.openshift.io/terminal=true' --wait

Deleting the DevWorkspace Operator dependency

Use the CLI to delete the custom resource definitions (CRDs) and additional resources that are created during installation of the Web Terminal Operator.

The DevWorkspace Operator functions as a standalone Operator and may be required as a dependency for other Operators installed on the cluster (for example, the CodeReady Workspaces Operator may depend on it). Follow the steps below only if you are sure the DevWorkspace Operator is no longer needed.

Procedure

  1. Remove the DevWorkspace custom resources used by the Operator, along with any related Kubernetes objects, such as deployments.

    1. $ oc delete devworkspaces.workspace.devfile.io --all-namespaces --all --wait
    1. $ oc delete devworkspaceroutings.controller.devfile.io --all-namespaces --all --wait

    If this step is not complete, finalizers make it difficult to fully uninstall the Operator easily.

  2. Remove the CRDs used by the Operator:

    The DevWorkspace Operator provides custom resource definitions (CRDs) that use conversion webhooks. Failing to remove these CRDs can cause issues on the cluster.

    1. $ oc delete customresourcedefinitions.apiextensions.k8s.io devworkspaceroutings.controller.devfile.io
    1. $ oc delete customresourcedefinitions.apiextensions.k8s.io devworkspaces.workspace.devfile.io
    1. $ oc delete customresourcedefinitions.apiextensions.k8s.io devworkspacetemplates.workspace.devfile.io
    1. $ oc delete customresourcedefinitions.apiextensions.k8s.io devworkspaceoperatorconfigs.controller.devfile.io
  3. Verify that all involved custom resource definitions are removed. The following command should not display any result.

    1. $ oc get customresourcedefintions | grep "devfile.io"
  4. Remove the devworkspace-webhook-server deployment, mutating, and validating webhooks:

    1. $ oc delete deployment/devworkspace-webhook-server -n openshift-operators
    1. $ oc delete mutatingwebhookconfigurations controller.devfile.io
    1. $ oc delete validatingwebhookconfigurations controller.devfile.io

    If you remove the devworkspace-webhook-server deployment without removing the mutating and validating webhooks, you will not be able to use oc exec commands to run commands in a container on the cluster. After you remove the webhooks you will be able to use the oc exec commands again.

  5. Remove any remaining services, secrets, and config maps. Depending on the installation, some resources included in the following command may not exist on the cluster.

    1. $ oc delete all --selector app.kubernetes.io/part-of=devworkspace-operator,app.kubernetes.io/name=devworkspace-webhook-server -n openshift-operators
    1. $ oc delete serviceaccounts devworkspace-webhook-server -n openshift-operators
    1. $ oc delete configmap devworkspace-controller -n openshift-operators
    1. $ oc delete clusterrole devworkspace-webhook-server
    1. $ oc delete clusterrolebinding devworkspace-webhook-server
  6. Uninstall the Operator using the web console:

    1. In the Administrator perspective of the web console, navigate to Operators → Installed Operators.

    2. Scroll the filter list or type a keyword into the Filter by name box to find the DevWorkspace Operator.

    3. Click the Options menu kebab for the DevWorkspace Operator, and then select Uninstall Operator.

    4. In the Uninstall Operator confirmation dialog box, click Uninstall to remove the Operator, Operator deployments, and pods from the cluster. The Operator stops running and no longer receives updates.