diff --git a/README.md b/README.md index 6217d12..57ae8a8 100644 --- a/README.md +++ b/README.md @@ -13,12 +13,32 @@ k8dash is the easiest way to manage your Kubernetes cluster. Why? ## Click the video below to see k8dash in action [![k8dash - Kubernetes Dashboard](https://raw.githubusercontent.com/herbrandson/k8dash/master/docs/videoThumbnail.png)](http://www.youtube.com/watch?v=u-1jGAhAHAM "k8dash - Kubernetes Dashboard") +# Table of Contents +- [Prerequisites](#Prerequisites) +- [Getting Started](#Getting_started) +- [Kubectl proxy](#kubectl_proxy) +- [Logging in](#Logging_in) + - [Service Account Token](#Service_Account_Token) + - [Running k8dash with OpenId Connect (oidc)](#oidc) + - [Running k8dash with NodePort](#Nodeport) + - [Metrics](#Metrics) +- [Development](#Development) + - [Prerequisites](#Prerequisites) +- [k8dash is made up of 2 parts. The server and the client](#Parts_of_k8dash) + - [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) + ## Getting Started Deploy k8dash with something like the following... @@ -49,17 +69,18 @@ spec: serviceName: k8dash servicePort: 80 ``` - + # 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 - + # 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. @@ -80,6 +101,7 @@ kubectl describe secret k8dash-sa-token-xxxxx Retrieve the `token` value from the secret and enter it into the login screen to access the dashboard. + ## Running k8dash with OpenId Connect (oidc) k8dash 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/herbrandson/k8dash/master/kubernetes-k8dash-oidc.yaml) config. @@ -111,6 +133,7 @@ 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"}` + ## Running k8dash with 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/herbrandson/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. @@ -122,6 +145,7 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE k8dash NodePort 10.107.107.62 4654:32565/TCP 1m ``` + ## Metrics k8dash 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. @@ -129,27 +153,34 @@ k8dash relies heavily on [metrics-server](https://github.com/kubernetes-incubato + [Running metrics-server with kubeadm](https://medium.com/@waleedkhan91/how-to-configure-metrics-server-on-kubeadm-provisioned-kubernetes-cluster-f755a2ac43a2) + # 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) + ## k8dash is made up of 2 parts. The server and the client. + ### 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. + ### 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. -## License + +# License [Apache License 2.0](https://raw.githubusercontent.com/herbrandson/k8dash/master/LICENSE)