diff --git a/README.md b/README.md
index 225798d..9ab6921 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,3 @@
-
# skooner - Kubernetes Dashboard
__(FYI: we are changing our name from "k8dash" to "skooner"! Please bear with us as we transition all of our documentation and codebase to reflect this name change.)__
@@ -19,33 +18,29 @@ skooner is the easiest way to manage your Kubernetes cluster. Why?
-
# Table of Contents
-
-- [Prerequisites](#Prerequisites)
-- [Getting Started](#Getting_started)
-- [Kubectl proxy](#kubectl_proxy)
-- [Logging in](#Logging_in)
- - [Service Account Token](#Service_Account_Token)
- - [Running skooner with OpenId Connect (oidc)](#oidc)
- - [Running skooner with NodePort](#Nodeport)
+- [Prerequisites](#Prerequisites)
+- [Getting Started](#Getting-started)
+- [Kubectl proxy](#kubectl_proxy)
+- [Logging in](#Logging-in)
+ - [Service Account Token](#Service-Account-Token)
+ - [OIDC](#oidc)
+ - [NodePort](#Nodeport)
- [Metrics](#Metrics)
- [Development](#Development)
- [Prerequisites](#Prerequisites)
-- [Parts of skooner](#Parts_of_skooner)
+- [skooner Architecture](#skooner-architecture)
- [Server](#Server)
- [Client](#Client)
- [License](#License)
-
## Prerequisites
+ A running Kubernetes cluster (e.g., [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/))
+ [metrics server](https://github.com/kubernetes-incubator/metrics-server) installed (optional, but strongly recommended)
+ A Kubernetes cluster configured for [OpenId Connect](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens) authentication (optional)
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
## Getting Started
Deploy skooner with something like the following...
@@ -77,21 +72,18 @@ spec:
servicePort: 80
```
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
# kubectl proxy
Unfortunately, `kubectl proxy` can not be used to access k8dash. According to the information at [https://github.com/kubernetes/kubernetes/issues/38775#issuecomment-277915961](https://github.com/kubernetes/kubernetes/issues/38775#issuecomment-277915961), it seems that `kubectl proxy` strips the Authorization header when it proxies requests. From that link:
> this is working as expected. "proxying" through the apiserver will not get you standard proxy behavior (preserving Authorization headers end-to-end), because the API is not being used as a standard proxy
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
# Logging in
There are multiple options logging into the dashboard.
-
## Service Account Token
The first (and easiest) option is to create a dedicated service account. The can be accomplished using the following script.
@@ -112,10 +104,9 @@ kubectl describe secret skooner-sa-token-xxxxx
Retrieve the `token` value from the secret and enter it into the login screen to access the dashboard.
-back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
-## Running skooner with OpenId Connect (oidc)
+## OIDC
skooner makes using OpenId Connect for authentication easy. Assuming your cluster is configured to use OIDC, all you need to do is create a secret containing your credentials and run the [kubernetes-k8dash-oidc.yaml](https://raw.githubusercontent.com/indeedeng/k8dash/master/kubernetes-k8dash-oidc.yaml) config.
To learn more about configuring a cluster for OIDC, check out these great links
@@ -146,10 +137,9 @@ Additionally, there are a few other OIDC options you can provide via environment
The other option is `OIDC_METADATA`. k8dash uses the excellent [node-openid-client](https://github.com/panva/node-openid-client) module. `OIDC_METADATA` will take a json string and pass it to the `Client` constructor. Docs [here](https://github.com/panva/node-openid-client/blob/master/docs/README.md#client). For example, `OIDC_METADATA='{"token_endpoint_auth_method":"client_secret_post"}`
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
-## Running skooner with NodePort
+## NodePort
If you do not have an ingress server setup, you can utilize a NodePort service as configured in the [kubernetes-k8dash-nodeport.yaml](https://raw.githubusercontent.com/indeedeng/k8dash/master/kubernetes-k8dash-nodeport.yaml). This is ideal when creating a single node master, or if you want to get up and running as fast as possible.
This will map the skooner port 4654 to a randomly selected port on the running node. The assigned port can be found using
@@ -160,9 +150,8 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
skooner NodePort 10.107.107.62 4654:32565/TCP 1m
```
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
## Metrics
skooner relies heavily on [metrics-server](https://github.com/kubernetes-incubator/metrics-server) to display real time cluster metrics. It is strongly recommended to have metrics-server installed to get the best experiance from k8dash.
@@ -170,41 +159,35 @@ skooner relies heavily on [metrics-server](https://github.com/kubernetes-incubat
+ [Running metrics-server with kubeadm](https://medium.com/@waleedkhan91/how-to-configure-metrics-server-on-kubeadm-provisioned-kubernetes-cluster-f755a2ac43a2)
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
# Development
-
## Prerequisites:
-+ A running Kubernetes cluster.
-Installing and running [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) is an easy way to get this.
-Once minikube is installed, you can run it with the command `minikube start --driver=docker`
-+ Once the cluster is up and running, create some login credentials as described [above](https://github.com/indeedeng/k8dash#logging-in)
+* A running Kubernetes cluster.
+ * Installing and running [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) is an easy way to get this.
+ * Once minikube is installed, you can run it with the command `minikube start --driver=docker`
+* Once the cluster is up and running, create some login credentials as described [above](https://github.com/indeedeng/k8dash#logging-in)
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
-## Parts of skooner
+## skooner Architecture
-
### Server
To run the server, run `npm i` from the `/server` directory to install dependencies and then `npm start` to run the server.
The server is a simple express.js server that is primarily responsible for proxying requests to the Kubernetes api server.
During development, the server will use whatever is configured in `~/.kube/config` to connect the desired cluster. If you are using minikube, for example, you can run `kubectl config set-context minikube` to get `~/.kube/config` set up correctly.
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
### Client
The client is a React application (using TypeScript) with minimal other dependencies.
To run the client, open a new terminal tab and navigate to the `/client` directory, run `npm i` and then `npm start`. This will open up a browser window to your local k8dash dashboard. If everything compiles correctly, it will load the site and then an error message will pop up `Unhandled Rejection (Error): Api request error: Forbidden...`. The error message has an 'X' in the top righthand corner to close that message. After you close it, you should see the UI where you can enter your token.
-Back to [Table of Contents](#table_of_contents)
+(Back to [Table of Contents](#table-of-contents))
-
# License
[Apache License 2.0](https://raw.githubusercontent.com/indeedeng/k8dash/master/LICENSE)
@@ -212,4 +195,4 @@ Back to [Table of Contents](#table_of_contents)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Findeedeng%2Fk8dash?ref=badge_large)
-Back to [Top](#top)
+(Back to [Table of Contents](#table-of-contents))