Customizing the Dashboard

The KKP Dashboard supports white-labeling through a branding configuration block and custom CSS themes. Branding configuration covers most customization needs (logo, colors, fonts, page title, etc.) without building from source. For deeper visual changes, custom SCSS/CSS themes are available.

• Branding Configuration
• Custom Themes
  • Modifying Available Themes
  • Creating a Theme With Source Access
  • Creating a Theme Without Source Access

Branding Configuration

Branding is configured via the KubermaticConfiguration CRD under spec.ui.config. Add a branding object to config.json:

apiVersion: kubermatic.k8c.io/v1
kind: KubermaticConfiguration
metadata:
  name: kubermatic
  namespace: kubermatic
spec:
  ui:
    config: |
      {
        "branding": {
          "product_name": "Chelsea Cloud",
          "product_url": "https://chelsea.cloud/",
          "postfix_page_title": "Chelsea Cloud",
          "tagline": "Your Cloud, Your Rules",
          "logo_url": "https://cdn.jsdelivr.net/gh/simple-icons/simple-icons/icons/kubernetes.svg",
          "logo_dark_url": "https://cdn.jsdelivr.net/gh/simple-icons/simple-icons/icons/kubernetes.svg",
          "favicon_url": "https://cdn.jsdelivr.net/gh/simple-icons/simple-icons/icons/kubernetes.svg",
          "background_url": "https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=1920&q=80",
          "custom_css_url": "",
          "font_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
          "font_family": "'Inter', helvetica, arial, sans-serif",
          "hide_version": true,
          "hide_documentation_links": true,
          "colors": {
            "primary": "#0052cc",
            "secondary": "#00b8d9",
            "header_bg": "#1a1a2e",
            "header_text": "#ffffff"
          }
        }
      }

All fields are optional. Unset fields fall back to KKP defaults. Changes take effect after saving the CRD (no pod restart required).

Branding Field Reference

Color Fields (branding.colors)

Custom Themes

The dashboard ships with light and dark themes. Users select a theme in User Settings > Account:

Modifying Available Themes

Light, dark, and system (OS-based) themes are available by default. To force a single theme for all users, set enforced_theme in config.json to the desired theme name (e.g. light):

spec:
  ui:
    config: |
      {
        "enforced_theme": "light"
      }

Creating a Theme With Source Access

This approach uses SCSS and lets you test themes locally before deploying.

1. Create src/assets/themes/custom.scss using light.scss or dark.scss as a base.

2. Register the theme in src/assets/config/config.json:

   {
     "themes": [
       {
         "name": "custom",
         "displayName": "Custom",
         "isDark": false
       }
     ]
   }
   

   • name — matches the SCSS filename (without extension) in assets/themes.
   • displayName — label shown in the theme picker.
   • isDark — controls the picker icon (sun/moon).

3. Run npm start, switch to the new theme under User Settings, and iterate on custom.scss. Any CSS rule can be overridden:

   .mat-form-field {
     background-color: red;
   }
   

   Switch back to a default theme before deploying, since the selected theme is stored in user settings.

4. Run npm run build:themes — this creates compiled CSS files in dist-themes/. Rename custom.css to your final name (e.g. solar.css).

1. Update config.json in the KubermaticConfiguration to register the new theme (use the filename without .css as name).
2. Mount the CSS file into dist/assets/themes using extraVolumes and extraVolumeMounts in the KubermaticConfiguration. Do not replace the entire directory — default themes are required.
3. Restart the dashboard pod. The new theme appears in the theme picker.

Creating a Theme Without Source Access

Download an existing compiled theme (light or dark) and modify the CSS directly.

Download via Browser

Open the KKP UI, go to Developer Tools > Sources, and download the active theme CSS from assets/themes.

Download from Container

Kubernetes

kubectl -n kubermatic cp kubermatic-dashboard-5b96d7f5df-mkmgh:/dist/assets/themes ~/themes

Docker

docker cp kubermatic-dashboard:/dist/assets/themes/. ~/themes

Using the Compiled Theme

1. Rename the downloaded file (e.g. light.css to solar.css).

2. Edit solar.css as needed. Any CSS rule can be changed or added; if modifying colors, update all occurrences.

3. Mount solar.css into dist/assets/themes in the dashboard container. Do not replace the entire directory.

4. Register the theme in config.json:

   {
     "themes": [
       {
         "name": "solar",
         "displayName": "Solar",
         "isDark": true
       }
     ]
   }
   

5. Restart the dashboard. The new theme appears in the theme picker under User Settings > Account.