kubebox

= Kubebox [small]#^⎈❏^# Antonin Stefanutti https://github.com/astefanutti[@astefanutti] // Meta :description: Terminal and Web console for Kubernetes // Settings :idprefix: :idseparator: - :experimental: // Aliases ifdef::env-github[] :note-caption: :information_source: :icon-edit: :pencil2: endif::[] ifndef::env-github[] :icons: font :icon-edit: icon:pencil[fw] endif::[] // URIs :uri-kubebox-download: https://github.com/astefanutti/kubebox/releases/download/v0.3.2 :uri-kubebox-twitter: https://twitter.com/kubebox :uri-kube-apiserver: https://kubernetes.io/docs/admin/kube-apiserver/ :uri-ingress-controllers: https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-controllers :uri-service-account: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ :uri-terminal-forever: http://www.commitstrip.com/en/2016/12/22/terminal-forever/ :uri-xterm-js: https://github.com/xtermjs/xterm.js

image::https://img.shields.io/badge/%40kubebox-00ACEE.svg?style=flat-square&logo=twitter&colorA=555&logoColor=fff[link={uri-kubebox-twitter}] {description}

//image::https://astefanutti.github.io/kubebox/kubebox.svg[align="center"] ++++

++++

=== Features

• Configuration sourcing from kubeconfig files (KUBECONFIG environment variable or $HOME/.kube)
• Switch contexts interactively
• Login and OAuth authentication support
• Namespace selection and pods list watching
• Container log scrolling / watching
• Container resources usage (memory, CPU, network charts) footnote:[Currently requires priviledged access / role.]
• Container remote exec terminal
• Object configuration editor and CRUD operations
• Cluster and nodes views / monitoring
• Port proxying and interactive HTTP client
• ...

== Run

The following alternatives are available for you to use Kubebox, depending on your preferences and constraints.

=== Executable

Download the Kubebox standalone executable for your OS:

-- [source,shell,subs=attributes+]

OSX

$ curl -Lo kubebox {uri-kubebox-download}/kubebox-macos && chmod +x kubebox

Linux

$ curl -Lo kubebox {uri-kubebox-download}/kubebox-linux && chmod +x kubebox

Windows

$ curl -Lo kubebox.exe {uri-kubebox-download}/kubebox-windows

=== Kubectl

You can run Kubebox as an in-cluster client with kubectl, e.g.:

$ kubectl run kubebox -it --rm --env="TERM=xterm" --image=astefanutti/kubebox --restart=Never

See the <<RBAC, RBAC>> section for more information about RBAC authorization.

=== Docker

You can run Kubebox using Docker, e.g.:

$ docker run -it --rm astefanutti/kubebox

You may want to mount your home directory so that Kubebox can rely on the ~/.kube/config file, e.g.:

$ docker run -it --rm -v ~/.kube/:/home/node/.kube/:ro astefanutti/kubebox

=== Server

Kubebox can be served from a service deployed in the target Kubernetes cluster. Terminal emulation is provided by {uri-xterm-js}[Xterm.js] and the communication with the Kubernetes master API is proxied by the server.

To deploy the server in your Kubernetes cluster, run:

# Replace the ROUTE_HOSTNAME variable
$ kubectl create -f https://raw.github.com/astefanutti/kubebox/master/kubernetes.yaml

For the Ingress resource to work, the cluster must have an Ingress controller running. See {uri-ingress-controllers}[Ingress controllers] for more information. Besides, see the <<RBAC, RBAC>> section for more information about RBAC authorization.

Alternatively, to deploy the server in your OpenShift cluster, run:

$ oc new-app -f https://raw.github.com/astefanutti/kubebox/master/openshift.yaml

=== Online

Kubebox is available online at https://astefanutti.github.com/kubebox. Note that this requires this address to match the allowed origins for CORS by the API server. This can be achived with the {uri-kube-apiserver}[Kubernetes API server CLI], e.g.:

$ kube-apiserver --cors-allowed-origins .*

== RBAC

If RBAC is enabled, Kubebox needs RBAC permissions to access the cluster resources. By default, while running as in-cluster client or server, Kubebox uses the default service account credentials to access the API server.

The following command can be run to bind the cluster-admin role to the default service account:

$ kubectl create clusterrolebinding default-cluster-admin --clusterrole=cluster-admin --serviceaccount=default:default

You can find more information in {uri-service-account}[Configure Service Accounts for Pods].

== Commands

[cols="1v,2v"] |=== |Keybinding |Description

2+^.e|General

|kbd:[l], kbd:[Ctrl+l] |Login

|[kbd:[⇧]+]kbd:[←], kbd:[→] + [kbd:[Alt]+]kbd:[1], ..., kbd:[9] |Navigate screens + (use kbd:[⇧] or kbd:[Alt] inside exec terminal)

|kbd:[↑], kbd:[↓] |Navigate list / form / log

|kbd:[Enter] |Select item / submit form

|kbd:[Esc] |Close modal window / cancel form / rewind focus

|kbd:[q], kbd:[Ctrl+q] |Exit footnoteref:[online keys, Not available in Web version.]

2+^.e|Login

|kbd:[←], kbd:[→] |Navigate Kube configurations

2+^.e|Namespace

|kbd:[n] |Change current namespace

|kbd:[r] |Remote shell into container

|kbd:[m] |Memory usage

|kbd:[c] |CPU usage

|kbd:[t] |Network usage

2+^.e|Log

|kbd:[g], kbd:[⇧+g] |Move to top / bottom

|kbd:[Ctrl+u], kbd:[Ctrl+d] |Move one page up / down

|===

== Usage

{icon-edit}

== Development

$ git clone https://github.com/astefanutti/kubebox.git
$ cd kubebox
$ npm install
$ node index.js

== Terminal forever

//image::https://astefanutti.github.io/kubebox/terminal-forever.jpg[align="center", link={uri-terminal-forever}] ++++

++++