đ¶ Kubernetes CLI To Manage Your Clusters In Style!
K9s provides a terminal UI to interact with your Kubernetes clusters. The aim of this project is to make it easier to navigate, observe and manage your applications in the wild. K9s continually watches Kubernetes for changes and offers subsequent commands to interact with your observed resources.
Please refer to our K9s documentation site for installation, usage, customization and tips.
Wanna discuss K9s features with your fellow
K9sersor simply show your support for this tool?
K9s is available on Linux, macOS and Windows platforms.
Binaries for Linux, Windows and Mac are available as tarballs in the release page.
Via Homebrew for macOS or LinuxBrew for Linux
brew install k9s
sudo port install k9s
pacman -S k9s
zypper install k9s
scoop install k9s
choco install k9s
# NOTE: The dev version will be in effect! go get -u github.com/derailed/k9s
K9s is currently using go v1.14 or above. In order to build K9 from source you must:
Build and run the executable
make build && ./execs/k9s
You can run k9s as a Docker container by mounting your
KUBECONFIG:
docker run --rm -it -v $KUBECONFIG:/root/.kube/config quay.io/derailed/k9s
For default path it would be:
docker run --rm -it -v ~/.kube/config:/root/.kube/config quay.io/derailed/k9s
You can build your own Docker image of k9s from the Dockerfile with the following:
docker build -t k9s-docker:0.1 .
You can get the latest stable
kubectlversion and pass it to the
docker buildcommand with the
--build-argoption. You can use the
--build-argoption to pass any valid
kubectlversion (like
v1.18.0or
v1.19.1).
KUBECTL_VERSION=$(make kubectl-stable-version 2>/dev/null) docker build --build-arg KUBECTL_VERSION=${KUBECTL_VERSION} -t k9s-docker:0.1 .
Run your container:
docker run --rm -it -v ~/.kube/config:/root/.kube/config k9s-docker:0.1
K9s uses 256 colors terminal mode. On `Nix system make sure TERM is set accordingly.
export TERM=xterm-256color
In order to issue manifest edit commands make sure your EDITOR env is set.
# Kubectl edit command will use this env var. export EDITOR=my_fav_editor # Should your editor deals with streamed vs on disk files differently, also set... export K9S_EDITOR=my_fav_editor
K9s prefers recent kubernetes versions ie 1.16+
# List all available CLI options k9s help # To get info about K9s runtime (logs, configs, etc..) k9s info # To run K9s in a given namespace k9s -n mycoolns # Start K9s in an existing KubeConfig context k9s --context coolCtx # Start K9s in readonly mode - with all cluster modification commands disabled k9s --readonly
Given the nature of the ui k9s does produce logs to a specific location. To view the logs and turn on debug mode, use the following commands:
k9s info # Will produces something like this # ____ __.________ # | |/ _/ __ \______ # | < \____ / ___/ # | | \ / /\___ \ # |____|__ \ /____//____ > # \/ \/ # # Configuration: /Users/fernand/.k9s/config.yml # Logs: /var/folders/8c/hh6rqbgs5nx_c_8k9_17ghfh0000gn/T/k9s-fernand.log # Screen Dumps: /var/folders/8c/hh6rqbgs5nx_c_8k9_17ghfh0000gn/T/k9s-screens-fernandTo view k9s logs
tail -f /var/folders/8c/hh6rqbgs5nx_c_8k9_17ghfh0000gn/T/k9s-fernand.log
Start K9s in debug mode
k9s -l debug
K9s uses aliases to navigate most K8s resources.
| Action | Command | Comment | |----------------------------------------------------------------|-------------------------------|------------------------------------------------------------------------| | Show active keyboard mnemonics and help |
?| | | Show all available resource alias |
ctrl-a| | | To bail out of K9s |
:q,
ctrl-c| | | View a Kubernetes resource using singular/plural or short-name |
:poâ | accepts singular, plural, short-name or alias ie pod or pods | | View a Kubernetes resource in a given namespace |
:alias namespaceâ | | | Filter out a resource view given a filter |
/filterâ | Regex2 supported ie
fred|bleeto filter resources named fred or blee | | Inverse regex filer |
/! filterâ | Keep everything that doesn't match. | | Filter resource view by labels |
/-l label-selectorâ | | | Fuzzy find a resource given a filter |
/-f filterâ | | | Bails out of view/command/filter mode | | | | Key mapping to describe, view, edit, view logs,... |
d,
v,
e,
l,... | | | To view and switch to another Kubernetes context |
:ctxâ | | | To view and switch to another Kubernetes context |
:ctx context-nameâ | | | To view and switch to another Kubernetes namespace |
:nsâ | | | To view all saved resources |
:screendump or sdâ | | | To delete a resource (TAB and ENTER to confirm) |
ctrl-d| | | To kill a resource (no confirmation dialog!) |
ctrl-k| | | Launch pulses view |
:pulses or puâ | | | Launch XRay view |
:xray RESOURCE [NAMESPACE]â | RESOURCE can be one of po, svc, dp, rs, sts, ds, NAMESPACE is optional | | Launch Popeye view |
:popeye or popâ | See https://popeyecli.io |
K9s keeps its configurations in a .k9s directory in your home directory
$HOME/.k9s/config.yml.
NOTE: This is still in flux and will change while in pre-release stage!
# $HOME/.k9s/config.yml k9s: # Represents ui poll intervals. Default 2secs refreshRate: 2 # Number of retries once the connection to the api-server is lost. Default 15. maxConnRetry: 5 # Enable mouse support. Default false enableMouse: true # Set to true to hide K9s header. Default false headless: false # Set to true to hide K9s crumbs. Default false crumbsless: false # Indicates whether modification commands like delete/kill/edit are disabled. Default is false readOnly: false # Toggles icons display as not all terminal support these chars. noIcons: false # Logs configuration logger: # Defines the number of lines to return. Default 100 tail: 200 # Defines the total number of log lines to allow in the view. Default 1000 buffer: 500 # Represents how far to go back in the log timeline in seconds. Setting to -1 will show all available logs. Default is 5min. sinceSeconds: 300 # Go full screen while displaying logs. Default false fullScreenLogs: false # Toggles log line wrap. Default false textWrap: false # Toggles log line timestamp info. Default false showTime: false # Indicates the current kube context. Defaults to current context currentContext: minikube # Indicates the current kube cluster. Defaults to current context cluster currentCluster: minikube # Persists per cluster preferences for favorite namespaces and view. clusters: coolio: namespace: active: coolio favorites: - cassandra - default view: active: po featureGates: # Toggles NodeShell support. Allow K9s to shell into nodes if needed. Default false. nodeShell: false # Provide shell pod customization of feature gate is enabled shellPod: # The shell pod image to use. image: killerAdmin # The namespace to launch to shell pod into. namespace: fred # The resource limit to set on the shell pod. limits: cpu: 100m memory: 100Mi # The IP Address to use when launching a port-forward. portForwardAddress: 1.2.3.4 kind: namespace: active: all favorites: - all - kube-system - default view: active: dp
By enabling the nodeShell feature gate on a given cluster, K9s allows you to shell into your cluster nodes. Once enabled, you will have a new
sfor
shellmenu option while in node view. K9s will launch a pod on the selected node using a special k9s_shell pod. Furthermore, you can refine your shell pod by using a custom docker image preloaded with the shell tools you love. By default k9s uses a BusyBox image, but you can configure it as follows:
# $HOME/.k9s/config.yml k9s: clusters: # Configures node shell on cluster blee blee: featureGates: # You must enable the nodeShell feature gate to enable shelling into nodes nodeShell: true # You can also further tune the shell pod specification shellPod: image: cool_kid_admin:42 namespace: blee limits: cpu: 100m memory: 100Mi
In K9s, you can define your very own command aliases (shortnames) to access your resources. In your
$HOME/.k9sdefine a file called
alias.yml. A K9s alias defines pairs of alias:gvr. A gvr (Group/Version/Resource) represents a fully qualified Kubernetes resource identifier. Here is an example of an alias file:
# $HOME/.k9s/alias.yml alias: pp: v1/pods crb: rbac.authorization.k8s.io/v1/clusterrolebindings
Using this alias file, you can now type pp/crb to list pods or ClusterRoleBindings respectively.
Entering the command mode and typing a resource name or alias, could be cumbersome for navigating thru often used resources. We're introducing hotkeys that allows a user to define their own hotkeys to activate their favorite resource views. In order to enable hotkeys please follow these steps:
$HOME/.k9s/hotkey.yml
Add the following to your
hotkey.yml. You can use resource name/short name to specify a command ie same as typing it while in command mode.
# $HOME/.k9s/hotkey.yml hotKey: # Hitting Shift-0 navigates to your pod view shift-0: shortCut: Shift-0 description: Viewing pods command: pods # Hitting Shift-1 navigates to your deployments shift-1: shortCut: Shift-1 description: View deployments command: dp # Hitting Shift-2 navigates to your xray deployments shift-2: shortCut: Shift-2 description: Xray Deployments command: xray deploy
Not feeling so hot? Your custom hotkeys will be listed in the help view
?. Also your hotkey file will be automatically reloaded so you can readily use your hotkeys as you define them.
You can choose any keyboard shortcuts that make sense to you, provided they are not part of the standard K9s shortcuts list.
NOTE: This feature/configuration might change in future releases!
SneakCast v0.17.0 on The Beach! - Yup! sound is sucking but what a setting!
You can change which columns shows up for a given resource via custom views. To surface this feature, you will need to create a new configuration file, namely
$HOME/.k9s/views.yml. This file leverages GVR (Group/Version/Resource) to configure the associated table view columns. If no GVR is found for a view the default rendering will take over (ie what we have now). Going wide will add all the remaining columns that are available on the given resource after your custom columns. To boot, you can edit your views config file and tune your resources views live!
NOTE: This is experimental and will most likely change as we iron this out!
Here is a sample views configuration that customize a pods and services views.
# $HOME/.k9s/views.yml k9s: views: v1/pods: columns: - AGE - NAMESPACE - NAME - IP - NODE - STATUS - READY v1/services: columns: - AGE - NAMESPACE - NAME - TYPE - CLUSTER-IP
K9s allows you to extend your command line and tooling by defining your very own cluster commands via plugins. K9s will look at
$HOME/.k9s/plugin.ymlto locate all available plugins. A plugin is defined as follows:
allto provide this shortcut for all views.
K9s does provide additional environment variables for you to customize your plugins arguments. Currently, the available environment variables are as follows:
$NAMESPACE-- the selected resource namespace
$NAME-- the selected resource name
$CONTAINER-- the current container if applicable
$FILTER-- the current filter if any
$KUBECONFIG-- the KubeConfig location.
$CLUSTERthe active cluster name
$CONTEXTthe active context name
$USERthe active user
$GROUPSthe active groups
$PODwhile in a container view
$COL-use a given column name for a viewed resource. Must be prefixed by
COL-!
This defines a plugin for viewing logs on a selected pod using
ctrl-lfor shortcut.
# $HOME/.k9s/plugin.yml plugin: # Defines a plugin to provide a `ctrl-l` shortcut to tail the logs while in pod view. fred: shortCut: Ctrl-L confirm: false description: Pod logs scopes: - pods command: kubectl background: false args: - logs - -f - $NAME - -n - $NAMESPACE - --context - $CONTEXT
NOTE: This is an experimental feature! Options and layout may change in future K9s releases as this feature solidifies.
K9s integrates Hey from the brilliant and super talented Jaana Dogan.
Heyis a CLI tool to benchmark HTTP endpoints similar to AB bench. This preliminary feature currently supports benchmarking port-forwards and services (Read the paint on this is way fresh!).
To setup a port-forward, you will need to navigate to the PodView, select a pod and a container that exposes a given port. Using
SHIFT-Fa dialog comes up to allow you to specify a local port to forward. Once acknowledged, you can navigate to the PortForward view (alias
pf) listing out your active port-forwards. Selecting a port-forward and using
CTRL-Bwill run a benchmark on that HTTP endpoint. To view the results of your benchmark runs, go to the Benchmarks view (alias
be). You should now be able to select a benchmark and view the run stats details by pressing . NOTE: Port-forwards only last for the duration of the K9s session and will be terminated upon exit.
Initially, the benchmarks will run with the following defaults:
The PortForward view is backed by a new K9s config file namely:
$HOME/.k9s/bench-.yml(note: extension is
ymland not
yaml). Each cluster you connect to will have its own bench config file, containing the name of the K8s context for the cluster. Changes to this file should automatically update the PortForward view to indicate how you want to run your benchmarks.
Here is a sample benchmarks.yml configuration. Please keep in mind this file will likely change in subsequent releases!
# This file resides in $HOME/.k9s/bench-mycontext.yml benchmarks: # Indicates the default concurrency and number of requests setting if a container or service rule does not match. defaults: # One concurrent connection concurrency: 1 # Number of requests that will be sent to an endpoint requests: 500 containers: # Containers section allows you to configure your http container's endpoints and benchmarking settings. # NOTE: the container ID syntax uses namespace/pod-name:container-name default/nginx:nginx: # Benchmark a container named nginx using POST HTTP verb using http://localhost:port/bozo URL and headers. concurrency: 1 requests: 10000 http: path: /bozo method: POST body: {"fred":"blee"} header: Accept: - text/html Content-Type: - application/json services: # Similarly you can Benchmark an HTTP service exposed either via NodePort, LoadBalancer types. # Service ID is ns/svc-name default/nginx: # Set the concurrency level concurrency: 5 # Number of requests to be sent requests: 500 http: method: GET # This setting will depend on whether service is NodePort or LoadBalancer. NodePort may require vendor port tunneling setting. # Set this to a node if NodePort or LB if applicable. IP or dns name. host: A.B.C.D path: /bumblebeetuna auth: user: jean-baptiste-emmanuel password: Zorg!
On RBAC enabled clusters, you would need to give your users/groups capabilities so that they can use K9s to explore their Kubernetes cluster. K9s needs minimally read privileges at both the cluster and namespace level to display resources and metrics.
These rules below are just suggestions. You will need to customize them based on your environment policies. If you need to edit/delete resources extra Fu will be necessary.
NOTE! Cluster/Namespace access may change in the future as K9s evolves. NOTE! We expect K9s to keep running even in atrophied clusters/namespaces. Please file issues if this is not the case!
--- # K9s Reader ClusterRole kind: ClusterRole apiVersion: rbac.authorization.k8s.io/v1 metadata: name: k9s rules: # Grants RO access to cluster resources node and namespace - apiGroups: [""] resources: ["nodes", "namespaces"] verbs: ["get", "list", "watch"] # Grants RO access to RBAC resources - apiGroups: ["rbac.authorization.k8s.io"] resources: ["clusterroles", "roles", "clusterrolebindings", "rolebindings"] verbs: ["get", "list", "watch"] # Grants RO access to CRD resources - apiGroups: ["apiextensions.k8s.io"] resources: ["customresourcedefinitions"] verbs: ["get", "list", "watch"] # Grants RO access to metric server (if present) - apiGroups: ["metrics.k8s.io"] resources: ["nodes", "pods"] verbs: ["get", "list", "watch"]
Sample K9s user ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: k9s subjects:
If your users are constrained to certain namespaces, K9s will need to following role to enable read access to namespaced resources.
--- # K9s Reader Role (default namespace) kind: Role apiVersion: rbac.authorization.k8s.io/v1 metadata: name: k9s namespace: default rules: # Grants RO access to most namespaced resources - apiGroups: ["", "apps", "autoscaling", "batch", "extensions"] resources: ["*"] verbs: ["get", "list", "watch"] # Grants RO access to metric server - apiGroups: ["metrics.k8s.io"] resources: ["pods", "nodes"] verbs: - get - list - watch
Sample K9s user RoleBinding
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: k9s namespace: default subjects:
Example: Dracula Skin ;)
You can style K9s based on your own sense of look and style. Skins are YAML files, that enable a user to change the K9s presentation layer. K9s skins are loaded from
$HOME/.k9s/skin.yml. If a skin file is detected then the skin would be loaded if not the current stock skin remains in effect.
You can also change K9s skins based on the cluster you are connecting too. In this case, you can specify the skin file name as
$HOME/.k9s/mycontext_skin.ymlBelow is a sample skin file, more skins are available in the skins directory in this repo, just simply copy any of these in your user's home dir as
skin.yml.
Colors can be defined by name or uing an hex representation. Of recent, we've added a color named
defaultto indicate a transparent background color to preserve your terminal background color settings if so desired.
NOTE: This is very much an experimental feature at this time, more will be added/modified if this feature has legs so thread accordingly!
NOTE: Please see K9s Skins for a list of available colors.
# Skin InTheNavy... k9s: # General K9s styles body: fgColor: dodgerblue bgColor: '#ffffff' logoColor: '#0000ff' # ClusterInfoView styles. info: fgColor: lightskyblue sectionColor: steelblue frame: # Borders styles. border: fgColor: dodgerblue focusColor: aliceblue # MenuView attributes and styles. menu: fgColor: darkblue keyColor: cornflowerblue # Used for favorite namespaces numKeyColor: cadetblue # CrumbView attributes for history navigation. crumbs: fgColor: white bgColor: steelblue activeColor: skyblue # Resource status and update styles status: newColor: '#00ff00' modifyColor: powderblue addColor: lightskyblue errorColor: indianred highlightcolor: royalblue killColor: slategray completedColor: gray # Border title styles. title: fgColor: aqua bgColor: white highlightColor: skyblue counterColor: slateblue filterColor: slategray views: # TableView attributes. table: fgColor: blue bgColor: darkblue cursorColor: aqua # Header row styles. header: fgColor: white bgColor: darkblue sorterColor: orange # YAML info styles. yaml: keyColor: steelblue colonColor: blue valueColor: royalblue # Logs styles. logs: fgColor: white bgColor: black
This is still work in progress! If something is broken or there's a feature that you want, please file an issue and if so inclined submit a PR!
K9s will most likely blow up if...
K9s sits on top of many open source projects and libraries. Our sincere appreciations to all the OSS contributors that work nights and weekends to make this project a reality!
We always enjoy hearing from folks who benefit from our work!
© 2020 Imhotep Software LLC. All materials licensed under Apache v2.0