web-terminal-exec

Web Terminal Exec

Web Terminal Exec is a component of Web Terminal Operator that enables OpenShift clusters to inject a user's kubeconfig into a running container, allowing for automatic login when using pods/exec. It is intended to run as a container within the context of a Web Terminal Operator installation in an OpenShift cluster.

API

The Web Terminal Exec serves three endpoints

The /exec/init endpoint accepts the following JSON:

{
  // Optional container name to inject kubeconfig into; by default search for a suitable container
  "containerName": "<CONTAINER_NAME>",
  "kubeconfig": {
    // Namespace for current context in kubeconfig; optional and unset in kubeconfig if not specified
    "namespace": "<NAMESPACE>",
    // Username for the current user; set to 'Developer' if not specified
    "username": "<USERNAME>"
  }
}

The /exec/init endpoint responds with JSON containing the information necessary to open a terminal session in the container it injected the kubeconfig into:

{
  // Name of pod in specified namespace
  "pod": "<POD_NAME>",
  // Name of detected container in specified namespace
  "container": "<CONTAINER_NAME>",
  // Detected default shell command (e.g. ["/bin/bash"])
  "cmd": ["<COMMAND>..."]
}

This can be consumed in a kubectl command as follows:

kubectl exec -it <POD_NAME> <CONTAINER_NAME> -- <COMMAND>...

Authentication

Endpoints that require authentication expect a user's OpenShift token to be passed in a X-Access-Token or X-Forwarded-Access-Token header on the request. This token is used to

1. Verify that the user making the request is the authorized user for the current terminal
2. Execute the pods/exec API call that interacts with the container into which kubeconfig is being injected (if applicable)

If a token is not provided or does not match what is expected, the server returns HTTP 401

Commandline options

  --authenticated-user-id string
      OpenShift user's ID that should has access to API. Must be set.
  --idle-timeout duration
      IdleTimeout is a inactivity period after which workspace should be stopped. Use '-1' to disable idle timeout.
      Examples: -1, 30s, 15m, 1h (default 5m0s)
  --pod-selector string
      Selector that is used to find workspace pod. (default controller.devfile.io/devworkspace_id=${DEVWORKSPACE_ID})
  --stop-retry-period duration
      StopRetryPeriod is a period after which workspace should be tried to stop if the previous try failed.
      Examples: 30s (default 10s)
  --url string
      Host:Port address for the Web Terminal Exec server. (default ":4444")

Development

The Web Terminal Exec component is intended to only run within an OpenShift cluster in the context of a Web Terminal Operator installation. To test builds of Web Terminal Exec in an OpenShift cluster, edit the web-terminal-exec DevWorkspaceTemplate created by the Web Terminal Operator to use the in-development image. Alternatively, individual Web Terminal instances can be edited to use a custom image for testing. Running locally or in isolation (i.e. without the Web Terminal Operator installed) is not currently supported.

This repository contains a Makefile to simplify development of Web Terminal Exec. The following environment variables can be set to configure behavior:

• DOCKER: configure container build tool to use for building container images. Default is podman.
• WEB_TERMINAL_EXEC_IMG: Configure image name and tag for container builds. Default is quay.io/wto/web-terminal-exec:next.