KubeBoard

Welcome to Kubeboard, a simple web GUI for visualizing the applications that are available in a Kubernetes cluster!

Written in Python using the Flask framework, it allows you to automatically populate a custom homepage/dashboard based on all the ingresses you've created. Basic customization is also implemented, such as the icon and/or title of each deployed application, and even the theme of the dashboard. Automatic and periodic updating of applications is implemented to make presentations more dynamic.

back to top

Customize ingresses

By default, KubeBoard displays all Ingress using their .metadata.name attribute and a default icon. If you want to customize the name and/or the icon of a specific Ingress or even remove it from the homepage, you can use the following annotations:

Annotation	Default value	Description
kubeboard.xyz/show	true	Whether or not to display the Ingress within KubeBoard homepage
kubeboard.xyz/name	<.metadata.name>	The name of the application
kubeboard.xyz/icon	mdi-link-variant	The icon of the application

We are currently using the Pictogrammers Material Design Icons library. You can find all available icons in its documentation.

back to top

Customize the dashboard

To facilitate the integration of KubeBoard into any project, some theming elements can be customized. This is done by editing the YAML configuration file kubeboard.yaml. It's default location can be changed by setting the FLASK_CONFIGURATION_FILE environment variable.

You'll find the main configuration keys below:

Configuration key	Default value	Description
.hideByDefault	false	Whether or not to hide all ingresses by default (requires explicit addition of the kubeboard.xyz/show annotation)
.fetchFavicon	false	Whether or not to replace the entry icons with the service favicon
.theme.subtitle	A simple web GUI to visualise the applications that are available in a Kubernetes cluster.	App subtitle
.theme.defaultIcons.ingress	mdi-link-variant	Default icon to use for ingresses that don't explicitly specify one
.theme.defaultIcons.bookmark	mdi-bookmark-outline	Default icon to use for ingresses that don't explicitly specify one
.theme.color.primary	#0075ff	The primary color (CSS rgb(), rgba(), #hex)
.theme.color.secondary	#AABBC3	The secondary color (CSS rgb(), rgba(), #hex)
.theme.logo	img/logo.webp	The logo image to use (external links work)
.theme.background.url	../img/earth-background.jpg	The background image to use (CSS relative path or URL)
.theme.background.effects	blur(10px) brightness(55%)	The background effect to add to background (CSS properties)
.bookmarks	[]	The static bookmarks to display below the ingresses
.bookmarks[0].categoryName	""	The name of the bookmark category
.bookmarks[0].items[0].name	""	The bookmark name
.bookmarks[0].items[0].icon	""	The bookmark icon (optional, if no icon is defined, the default icon is used)
.bookmarks[0].items[0].link	""	The bookmark URL

The structure of the configuration file is validated at each start. The JSON schema used by the application is provided here: .schemas/configuration.schema.json.

Favicon fetch limitation

The favicon retrieval relies on the Python favicon pip library. Some issues have been found when fetching favicons in a Single-Page Application that could result in the wrong icon being fetched.

back to top

Getting started (Helm)

KubeBoard is designed to run inside a Kubernetes cluster. To make it easier to deploy, we maintain a special Helm chart, which you can find in the chart folder.

Like any other Helm chart, the available configuration options can be found in the chart/values.yaml configuration file. We recommend you to override any values in a dedicated kubeboard.values.yaml file before deploying the chart:

cp chart/values.yaml kubeboard.values.yaml
vim kubeboard.values.yaml

You can set any of the previously referenced configuration keys mentioned above by setting them in the .config attribute of the kubeboard.values.yaml before deploying the chart:

# kubeboard.values.yaml
config:
  hideByDefault: false
  fetchFavicon: false
  theme:
    subtitle: "A simple web GUI to visualize the services that are available in a Kubernetes cluster."
    defaultIcons:
      ingress: mdi-link-variant
      bookmark: mdi-bookmark-outline
    color:
      primary: "#0075ff"
      secondary: "#AABBC3"
    background:
      url: "../img/earth-background.jpg"
      effects: "blur(10px) brightness(55%)"
  bookmarks: []

Finally, use the following command to deploy the chart:

helm upgrade --install -n <namespace> -f kubeboard.values.yaml kubeboard ./chart

back to top

Getting started (Docker)

To run KubeBoard locally, we recommend using Docker or Podman. Note that you'll also need a valid and accessible Kubernetes cluster, as you'll need to mount your local kubeconfig file in the appropriate container directory:

docker run -v $HOME/.kube:/app/.kube -v $PWD/kubeboard.yaml:/app/kubeboard.yaml:ro -p 5000:5000 ghcr.io/bythehugo/kubeboard:1.3.4

A docker-compose file is also provided in the project. You'll find it at the root of the directory. You can use it to run or rebuild the application:

docker compose up          # Run the application
docker compose up --build  # Build the application

back to top

Getting started (local)

In order to get a local copy up and running, you'll need to follow these simple steps.

Prerequisites

• At least Python v3.12 and its pip module:

  # Install the required packages on Debian-based systems
  sudo apt install python3 python3-pip
  
  # Validate installation
  python3 -V

Installation

1. Clone the repo:

   git clone https://github.com/ByTheHugo/kubeboard.git

2. Create a new Python virtual environment and source it:

   # Create a new virtual environment
   python3 -m venv venv
   
   # Activate the virtual environment
   source venv/bin/activate

3. Install the Python packages using pip:

   python3 -m pip install -r requirements.txt

4. Customize environment variables by editing the .flaskenv file (if needed)

5. Run the application:

   python3 -m flask run

back to top

How to run tests

In order to run the pytest tests you'll need to follow these simple steps.

Prerequisites

If you don't have a Python virtual environment yet, create one. Otherwise, source it

python3 -m venv venv
source venv/bin/activate

Then install the required Python dependencies from both the application and tests using the following command:

python3 -m pip install -r requirements.txt -r tests/requirements.txt

Run the tests

You can run the pytest tests using with following command:

python3 -m pytest

Generate the code coverage

You can use the following options to generate the coverage report:

python3 -m pytest --cov --cov-report html

Generate the code profile

You must install the Graphviz package to generate the Python profile in SVG:

# Package for Debian-based systems
sudo apt install graphviz

You can use the following options to generate the Python profile:

python3 -m pytest --profile --profile-svg

back to top

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

back to top

Contact

Hugo CHUPIN - @hugo.chupin.xyz - hugo@chupin.xyz

Project link: https://github.com/ByTheHugo/kubeboard

back to top