This project contains an Xterm.js frontend that connets to a Go backend to provide a shell to the host system. Basically, access your shell from a browser.
Some use cases I had:
- Deploy to a compute instance in your networks and expose it when needed to gain shell access to your network over the browser
- Deploy to a Kubernetes cluster with appropriate (Cluster)Role and (Cluster)RoleBinding resources to allow some level of access to developers
- Exposing a CLI tool (see
./examples/k9s
for an example) over the browser. Think CLI-as-a-frontend - Doing a demo for a CLI tool over the browser
Table of Contents
Run make init
to install both Node.js and Golang dependencies.
Run make start
to start the Go backend which will also serve the static files for the website.
Open your browser at http://localhost:8376 to view your shell in the browser.
To build this project, run make build
to build the binary
Run make package
to create the Docker image. To customise the package process:
- Create a file named
Makefile.properties
(this will be-include
d by the Makefile) - Set
image_namespace
to your desired namespace (defaults tozephinzer
) - Set
image_name
to your desired image name (defaults tocloudshell
) - Set
image_tag
to your desired tag (defaults to the first 8 characters of the Git commit hash)
Run make publish
to publish the Docker image. Same customisations as above apply.
Run make publish-example id=${id}
to publish the example Docker images where ${id}
is the directory name of the directory in the ./examples
directory.
Configurations can be set via flags or environment variables. To view available configurations in your binary instance, run cloudshell --help
. Otherwise, flags and environment variables follow a rule of kebab-lower-case
for flags and SNAKE_UPPER_CASE
for environment variables.
Configuration | Flag | Environment Variable | Default Value | Description |
---|---|---|---|---|
Allowed hostnames | --allowed-hostnames |
ALLOWED_HOSTNAMES |
"localhost" |
Comma delimited list of hostnames that are allowed to connect to the websocket |
Arguments | --arguments |
ARGUMENTS |
"-l" |
Comma delimited list of arguments that should be passed to the target binary |
Command | --command |
COMMAND |
"/bin/bash" |
Absolute path to the binary to run |
Connection error limit | --connection-error-limit |
CONNECTION_ERROR_LIMIT |
10 |
Number of times a connection should be re-attempted by the server to the XTerm.js frontend before the connection is considered dead and shut down |
Keepalive ping timeout | --keepalive-ping-timeout |
KEEPALIVE_PING_TIMEOUT |
20 |
Maximum duration in seconds between a ping and pong message to tolerate |
Maximum buffer size in bytes | --max-buffer-size-bytes |
MAX_BUFFER_SIZE_BYTES |
512 |
Maximum length of input from the browser terminal |
Log format | --log-format |
LOG_FORMAT |
"text" |
Format with which to output logs, one of "json" or "text" |
Log level | --log-level |
LOG_LEVEL |
"debug" |
Minimum level of logs to output, one of "trace" , "debug" , "info" , "warn" , "error" |
Liveness probe path | --path-liveness |
PATH_LIVENESS |
"/healthz" |
Path to liveness probe handler endpoint |
Metrics probe path | --path-metrics |
PATH_METRICS |
"/metrics" |
Path to metrics endpoint |
Readiness probe path | --path-readiness |
PATH_READINESS |
"/readiness" |
Path to readiness probe handler endpoint |
Xterm.js path | --path-xtermjs |
PATH_XTERMJS |
"/xterm.js" |
Path to xterm.js websocket endpoint |
Server address | --server-address |
SERVER_ADDRESS |
"0.0.0.0" |
IP interface the server should listen on |
Server port | --server-port |
SERVER_PORT |
8376 |
Port the server should listen on |
Working directory | --workdir |
WORKDIR |
"." |
Path to the working directory that Cloudshell should use |
Run make run
to run the Docker image locally
Go to ./deploy/cloudshell
and run helm install --values ./values.yaml --set-url url=cloudshell.yourdomainname.com cloudshell .
. Replace cloudshell.yourdomainname.com
with your own domain name. You could also set the url
property inside the ./values.yaml
file.
The following environment variables should be set in the CI pipeline:
Key | Example | Description |
---|---|---|
DOCKER_REGISTRY_URL |
"docker.io" |
URL of the Docker registry to push the image to |
DOCKER_REGISTRY_USER |
"zephinzer" |
User to identify with for the registry at DOCKER_REGISTRY_URL |
DOCKER_REGISTRY_PASSWORD |
"p@ssw0rd" |
Password for the user identified in DOCKER_REGISTRY_USER for the registry at DOCKER_REGISTRY_URL |
This project is licensed under the MIT license.