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 and authcode-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%).

Indices and tables

• Index
• Module Index
• Search Page