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.4.0 :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

{description}

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

++++

=== Features

• Configuration from kubeconfig files (KUBECONFIG environment variable or $HOME/.kube)
• Switch contexts interactively
• Authentication support (token, username / password, private key / cert, OpenID Connect)
• 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
• ...

Follow image:https://img.shields.io/badge/%40kubebox-00ACEE.svg?&logo=twitter&colorA=555&logoColor=fff[link={uri-kubebox-twitter}] for some updates.

== 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+]

Linux

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

OSX

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

Windows

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

Then run:

$ ./kubebox

=== Server

Kubebox can be served from a service hosted in your 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:

# Make sure to replace the following fields:
# - The ingress host
# - The subject service account namespace
$ 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.

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

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

=== 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

If RBAC is enabled, you'll have to use the --serviceaccount option and reference a service account with sufficient permissions.

=== 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

=== 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 .*

== 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

|===

== FAQ

• Resources usage metrics are unavailable!

** You may face issue https://github.com/kubernetes/kubernetes/issues/56297[#56297] that still affects Kubernetes versions from 1.8.0 to 1.11.x

** The metrics are retrieved from the embedded cAdvisor /stats endpoints, that are accessed by creating a proxy on the node Kubelets, and which requires proper RBAC permission, e.g.: + [source,console]

$ kubectl auth can-i get nodes/proxy yes

== Development

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

== Terminal 🚀

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

++++