From db2cf603466f394c9ddaf1e85cf181f8a3858f15 Mon Sep 17 00:00:00 2001 From: yuqiuw <72527514+yuqiuw@users.noreply.github.com> Date: Thu, 10 Jun 2021 11:36:31 -0500 Subject: [PATCH] Revert "reworking table of contents" This reverts commit c9be5dcdf7ccf730c5184ad82fbd00862d5bfb77. --- README.md | 69 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 9ab6921..225798d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # 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.)__ @@ -18,29 +19,33 @@ 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) - - [OIDC](#oidc) - - [NodePort](#Nodeport) + +- [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) - [Metrics](#Metrics) - [Development](#Development) - [Prerequisites](#Prerequisites) -- [skooner Architecture](#skooner-architecture) +- [Parts of skooner](#Parts_of_skooner) - [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... @@ -72,18 +77,21 @@ 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. @@ -104,9 +112,10 @@ 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) -## OIDC + +## Running skooner with OpenId Connect (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 @@ -137,9 +146,10 @@ 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) -## NodePort + +## Running skooner 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/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 @@ -150,8 +160,9 @@ 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. @@ -159,35 +170,41 @@ 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) -## skooner Architecture + +## Parts of skooner + ### 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) @@ -195,4 +212,4 @@ To run the client, open a new terminal tab and navigate to the `/client` directo [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Findeedeng%2Fk8dash.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Findeedeng%2Fk8dash?ref=badge_large) -(Back to [Table of Contents](#table-of-contents)) +Back to [Top](#top)