Welcome to Kubernetes Operational View’s documentation!¶
The goal of Kubernetes Operational View is to provide a common operational picture for multiple Kubernetes clusters.
GitHub repository: https://github.com/hjacobs/kube-ops-view
Getting Started¶
You can find example Kubernetes manifests for deployment in the deploy folder. It should be as simple as:
$ git clone git@github.com:hjacobs/kube-ops-view.git
$ kubectl apply -f kube-ops-view/deploy
Afterwards you can open “kube-ops-view” via the kubectl proxy:
$ kubectl proxy
Now direct your browser to http://localhost:8001/api/v1/proxy/namespaces/default/services/kube-ops-view/
User’s Guide¶
Pod Status¶
Each pod indicates its status by color and animation:
- Running and all containers ready: constant green
- Running and not all containers ready: flashing green
- Pending or ContainerCreating: flashing yellow
- ImagePullBackoff or CrashLoopBackoff: flashing red
- Succeeded (for jobs): blue
Tooltips¶
Various UI elements provide additional tooltip information when hovering over them with the mouse:
- Hovering over the title bar of a node box reveals the node’s labels.
- Hovering over the vertical resource bars will show the node’s capacity, sum of all resource requests and current resource usage.
- Hovering over a pod will show the pod’s labels, container status and resources.
Filtering Pods¶
Kubernetes Operational View allows you to quickly find your running application pods.
Typing characters will run the filter, i.e. non-matching pods will be greyed out.
You can filter by:
- name
- labels - when query includes
=
, e.g.env=prod
The pod filter is persisted in the location bar (#q=..
query parameter) which allows to conveniently send the filtered view to other users (e.g. for troubleshooting).
Sorting Pods¶
Pods can be sorted by different properties:
- pod name (this is the default)
- age (start time)
- memory usage (metric collected from Heapster)
- CPU usage (metric collected from Heapster)
Sorting by memory or CPU allows finding the most resource hungry pod (per node).
Filtering Clusters¶
Clicking on a cluster handle (the top bar of the cluster box) will toggle between showing the single cluster alone and all clusters.
Themes¶
The top menu bar allows selecting an UI color theme matching your taste. The theme selection will be saved in the browser’s Local Storage.
Multiple Clusters¶
Multiple clusters are supported by either passing a static list of API server URLs, using an existing kubeconfig file or pointing to a Cluster Registry HTTP endpoint.
Static List of API Server URLs¶
Set the CLUSTERS
environment variable to a comma separated list of Kubernetes API server URLs.
These can either be unprotected localhost
URLs or OAuth 2 protected API endpoints.
The needed OAuth credentials (Bearer
access token) must be provided via a file ${CREDENTIALS_DIR}/read-only-token-secret
.
Kubeconfig File¶
The kubeconfig file allows defining multiple cluster contexts with potential different authentication mechanisms.
Kubernetes Operational View will try to reach all defined contexts when given the --kubeconfig-path
command line option (or KUBECONFIG_PATH
environment variable).
Example:
Assuming ~/.kube/config
as the following contents with two defined contexts:
apiVersion: v1
kind: Config
clusters:
- cluster: {server: 'https://kube.foo.example.org'}
name: kube_foo_example_org
- cluster: {server: 'https://kube.bar.example.org'}
name: kube_bar_example_org
contexts:
- context: {cluster: kube_foo_example_org, user: kube_foo_example_org}
name: foo
- context: {cluster: kube_bar_example_org, user: kube_bar_example_org}
name: bar
current-context: kube_foo_example_org
users:
- name: kube_foo_example_org
user: {token: myfootoken123}
- name: kube_bar_example_org
user: {token: mybartoken456}
Kubernetes Operational View would try to reach both endpoints with the respective token for authentication:
$ # note that we need to mount the local ~/.kube/config file into the Docker container
$ docker run -it --net=host -v ~/.kube:/kube hjacobs/kube-ops-view --kubeconfig-path=/kube/config
Note
You need to make sure that the Docker container has access to any required SSL certificate files.
Minikube by default will use certificates in ~/.minikube
. You can copy them to ~/.kube
and make the paths in ~/.kube/config
relative.
The following command should work out of the box with Minikube:
$ docker run -it --net=host -v ~/.kube:/kube -v ~/.minikube:$HOME/.minikube hjacobs/kube-ops-view --kubeconfig-path=/kube/config
You can select which clusters should be queried by specifying a list of kubeconfig contexts with the --kubeconfig-contexts
option:
$ docker run -it --net=host -v ~/.kube:/kube hjacobs/kube-ops-view --kubeconfig-path=/kube/config --kubeconfig-contexts=bar
This would only query the Kubernetes cluster defined by the bar
context.
Cluster Registry¶
Clusters can be dynamically discovered by providing one HTTP endpoint as the cluster registry.
Set either the CLUSTER_REGISTRY_URL
environment variable or the --cluster-registry-url
option to an URL conforming to:
$ curl -H 'Authorization: Bearer mytoken' $CLUSTER_REGISTRY_URL/kubernetes-clusters
{
"items": [
{
"id": "my-cluster-id",
"api_server_url": "https://my-cluster.example.org"
}
]
}
The cluster registry will be queried with an OAuth Bearer token, the token can be statically set via the OAUTH2_ACCESS_TOKENS
environment variable.
Example:
$ token=mysecrettoken
$ docker run -it -p 8080:8080 -e OAUTH2_ACCESS_TOKENS=read-only=$token hjacobs/kube-ops-view --cluster-registry-url=https://cluster-registry.example.org
Otherwise the needed OAuth credentials (Bearer
access token) must be provided via a file ${CREDENTIALS_DIR}/read-only-token-secret
.
You can pass this file by mounting a secret like:
apiVersion: v1
kind: Secret
metadata:
name: kube-ops-view-credentials
type: Opaque
data:
read-only-token-type: Bearer
read-only-token-secret: dXNlcjpwYXNzCg== # base64 encoded token
The deployment manifest to mount the above secret:
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: kube-ops-view
spec:
replicas: 1
template:
metadata:
labels:
app: kube-ops-view
spec:
containers:
- name: kube-ops-view
image: hjacobs/kube-ops-view:latest
env:
- name: CLUSTER_REGISTRY_URL
value: "https://cluster-registry.example.org"
- name: CREDENTIALS_DIR
value: "/meta/credentials"
ports:
- containerPort: 8080
protocol: TCP
volumeMounts:
- name: credentials
mountPath: /meta/credentials
readOnly: true
volumes:
- name: credentials
secret:
secretName: kube-ops-view-credentials
Access Control¶
Kube Ops View supports protecting the UI via the OAuth Authorization Code Grant flow.
Relevant configuration settings (environment variables) for OAuth are:
APP_URL
- The app’s own URL, e.g. https://kube-ops-view.example.org. This is used to construct the OAuth 2 redirect URI (callback URL).
AUTHORIZE_URL
- OAuth 2 authorization endpoint URL, e.g. https://oauth2.example.org/authorize
ACCESS_TOKEN_URL
- Token endpoint URL for the OAuth 2 Authorization Code Grant flow, e.g. https://oauth2.example.org/token
CREDENTIALS_DIR
- Folder path to load client credentials from. The folder needs to contain two files:
authcode-client-id
andauthcode-client-secret
.
TODO: how to configure
Screen Tokens¶
Screen tokens allow non-human access to the UI to support permanent dashboards on TV screens.
On your local machine: authenticate via OAuth redirect flow and go to /screen-tokens to create a new token. Write down the screen token on a piece of paper.
Go to the TV screen and enter /screen/$TOKEN in the location bar.
TODO: how do screen tokens work?
UI Options¶
Kubernetes Operational View has a few options to change the UI behavior.
All these options are passed in the URL’s fragment identifier (starting with #
) in the format of key/value pairs separated by semicolons.
Example URL: https://kube-ops-view.example.org/#dashboard=true;reload=600
clusters
- Comma separated list of cluster IDs to show.
dashboard
- Enable dashboard mode which hides the menu bar.
reload
- Reload the whole page after X seconds. This is useful for unattended TV screens running 24x7 to mitigate JavaScript memory leaks and browser crashes.
renderer
- Forces the fallback canvas renderer (instead of WebGL) when set to “canvas”.
scale
- Set the initial view scale (
1.0
is 100%).