UI Customization

Rancher provides extensive UI customization capabilities through settings and custom resources. You can customize branding, colors, logos, navigation links, and more to match your organization’s requirements.

Branding Customization

Primary Colors

Customize the primary and link colors:

# Settings in management.cattle.io/v3/Setting
ui-primary-color: "#007a33"
ui-link-color: "#0056b3"

These settings control the main color scheme throughout the UI.

Logos and Favicon

Custom Logos:

# Light mode logo
ui-logo-light: "https://example.com/logo-light.svg"

# Dark mode logo  
ui-logo-dark: "https://example.com/logo-dark.svg"

# Custom favicon
ui-favicon: "https://example.com/favicon.ico"

Logos should be:

SVG or PNG format
Maximum height: 40px
Transparent background recommended

Customize the login page background:

# Light theme background
ui-login-background-light: "https://example.com/bg-light.jpg"

# Dark theme background
ui-login-background-dark: "https://example.com/bg-dark.jpg"

Recommended specifications:

Image format: JPEG or PNG
Resolution: 1920x1080 or higher
File size: < 2MB for performance

Home Page Banners

Add custom banners to the home page:

# Light theme banner
ui-banner-light: "https://example.com/banner-light.svg"

# Dark theme banner
ui-banner-dark: "https://example.com/banner-dark.svg"

Page Banners

Header and Footer Banners

Display custom banners in the header or footer:

# Header banner (JSON format)
ui-banner-header: |
  {
    "background": "#ff0000",
    "color": "#ffffff",
    "text": "Production Environment",
    "textAlignment": "center"
  }

# Footer banner
ui-banner-footer: |
  {
    "background": "#0066cc",
    "color": "#ffffff",
    "text": "Confidential - Internal Use Only",
    "textAlignment": "center"
  }

Display a consent banner on the login page:

ui-banner-login-consent: |
  {
    "text": "By logging in, you agree to our Terms of Service",
    "button": "I Agree"
  }

UI Banners Setting

Configure multiple banners using the ui-banners setting:

ui-banners: |
  {
    "banner": {
      "background": "#007a33",
      "color": "#ffffff",
      "text": "Welcome to Rancher"
    },
    "bannerFooter": {
      "background": "#333333",
      "color": "#ffffff",
      "text": "© 2025 Your Organization"
    }
  }

NavLink Custom Resource

Create custom navigation links using the ui.cattle.io/v1/NavLink custom resource:

apiVersion: ui.cattle.io/v1
kind: NavLink
metadata:
  name: documentation
spec:
  label: "Documentation"
  description: "Company documentation portal"
  group: "help"
  iconSrc: "https://example.com/docs-icon.svg"
  target: "_blank"
  toURL: "https://docs.example.com"

Location: pkg/apis/ui.cattle.io/v1/types.go

NavLink Specification

Fields:

label: Display text for the link
description: Tooltip or description text
sideLabel: Additional label shown on the side
iconSrc: URL to icon image
group: Navigation group (e.g., “help”, “tools”)
target: Link target (_blank, _self)
toURL: External URL to navigate to
toService: Internal service reference

Linking to Kubernetes Services

Create a link to an internal Kubernetes service:

apiVersion: ui.cattle.io/v1
kind: NavLink
metadata:
  name: monitoring
spec:
  label: "Monitoring Dashboard"
  description: "Prometheus monitoring"
  group: "tools"
  toService:
    namespace: "cattle-monitoring-system"
    name: "prometheus"
    scheme: "http"
    port: 9090
    path: "/graph"

Service Configuration:

namespace: Kubernetes namespace (required)
name: Service name (required)
scheme: http or https (default: http)
port: Service port (IntOrString)
path: URL path to append

NavLinks are registered in the Steve API server: Location: pkg/api/steve/navlinks/navlinks.go

func Register(ctx context.Context, server *steve.Server) {
    server.SchemaFactory.AddTemplate(schema2.Template{
        Group: "ui.cattle.io",
        Kind:  "NavLink",
        StoreFactory: func(innerStore types.Store) types.Store {
            return &store{
                Store: innerStore,
            }
        },
    })
}

UI Settings Reference

General Settings

Location: pkg/settings/setting.go

# UI Brand (e.g., "suse")
ui-brand: "rancher"

# Vendor/Company name
ui-pl: "rancher"

# Default landing page
ui-default-landing: "vue"

# Preferred UI (vue dashboard vs ember)
ui-preferred: "vue"

Custom Links

# Custom links (JSON format)
ui-custom-links: |
  {
    "Support": "https://support.example.com",
    "Training": "https://training.example.com",
    "Status Page": "https://status.example.com"
  }

Dashboard Configuration

# Dashboard path in container
ui-dashboard-path: "/usr/share/rancher/ui-dashboard"

# Dashboard index (remote)
ui-dashboard-index: "https://releases.rancher.com/dashboard/latest/index.html"

# Offline mode: "true", "false", or "dynamic"
ui-offline-preferred: "dynamic"

Performance Settings

# UI performance settings (JSON format)
ui-performance: |
  {
    "incrementalResourceLoading": true,
    "resourceCountThreshold": 1000,
    "manualRefresh": false
  }

UI Extensions

# Configure UI extensions
ui-extensions: |
  {
    "enabled": true,
    "allowedExtensions": ["extension-1", "extension-2"]
  }

# Max plugin file size (bytes)
max-ui-plugin-file-byte-size: "31457280"  # 30MB

Content Configuration

Dynamic Content

Configure dynamic content for the UI:

# Enable dynamic content: "true", "log", or "debug"
ui-content-enabled: "true"

# Custom content endpoint
ui-content-endpoint: "https://content.example.com/api"

Community and Feedback

# Display community links (deprecated, use ui-custom-links)
ui-community-links: "true"

# Custom issues URL
ui-issues: "https://issues.example.com"

# Feedback form URL (Ember UI)
ui-feedback-form: "https://feedback.example.com"

Theme Configuration

Users can set their preferred theme:

# User-specific setting (stored per user)
ui-theme: "dark"  # "light" or "dark"

Applying Customizations

Using kubectl

Update settings using kubectl:

# Update a single setting
kubectl patch setting ui-primary-color \
  -p '{"value":"#007a33"}' \
  --type=merge

# Create a NavLink
kubectl apply -f navlink.yaml

Using Rancher UI

Navigate to Global Settings
Search for UI settings (filter by “ui-”)
Click Edit on any setting
Enter the new value
Click Save

Using Rancher API

Update settings via the API:

curl -X PUT "https://rancher.example.com/v3/settings/ui-primary-color" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"#007a33"}'

Helm Chart Values

Configure UI settings during Helm installation:

# values.yaml
extraEnv:
  - name: CATTLE_BASE_UI_BRAND
    value: "suse"

Best Practices

Test customizations in a development environment first
Use HTTPS for all custom resource URLs
Optimize images for fast loading (< 2MB)
Provide both light and dark theme assets
Document custom links for your users
Use environment variables for different environments
Backup settings before making changes
Follow brand guidelines for colors and logos
Test accessibility of custom colors (contrast ratios)
Cache external resources for better performance

Examples

Complete Branding Example

# Primary branding
ui-primary-color: "#00B140"
ui-link-color: "#007A33"
ui-brand: "acme"
ui-pl: "ACME Corporation"

# Logos
ui-logo-light: "https://cdn.acme.com/logo-light.svg"
ui-logo-dark: "https://cdn.acme.com/logo-dark.svg"
ui-favicon: "https://cdn.acme.com/favicon.ico"

# Backgrounds
ui-login-background-light: "https://cdn.acme.com/login-bg-light.jpg"
ui-login-background-dark: "https://cdn.acme.com/login-bg-dark.jpg"

# Custom links
ui-custom-links: |
  {
    "Help Desk": "https://support.acme.com",
    "Documentation": "https://docs.acme.com",
    "Status": "https://status.acme.com"
  }

ui-banner-header: |
  {
    "background": "#d32f2f",
    "color": "#ffffff",
    "text": "CLASSIFIED - TOP SECRET",
    "textAlignment": "center"
  }

ui-banner-footer: |
  {
    "background": "#d32f2f",
    "color": "#ffffff",
    "text": "This system is for authorized use only. All activity is monitored.",
    "textAlignment": "center"
  }

Troubleshooting

Custom assets not loading

Verify URLs are accessible from browser
Check CORS headers on asset server
Ensure HTTPS is used for security
Check browser console for errors

Colors not applying

Clear browser cache
Check setting syntax (valid hex colors)
Verify settings are saved correctly
Test in incognito mode

NavLinks not appearing

Verify NavLink resource is created
Check group name is valid
Ensure user has permissions to view
Check Rancher logs for errors

UI Settings: pkg/settings/setting.go (lines 288-374)
NavLink Types: pkg/apis/ui.cattle.io/v1/types.go
NavLink Registration: pkg/api/steve/navlinks/navlinks.go

Fleet & GitOps

Monitoring & Telemetry

Extensions

Development

​UI Customization

​Branding Customization

​Primary Colors

​Logos and Favicon

​Login Backgrounds

​Home Page Banners

​Page Banners

​Header and Footer Banners

​Login Consent Banner

​UI Banners Setting

​Custom Navigation Links

​NavLink Custom Resource

​NavLink Specification

​Linking to Kubernetes Services

​Navigation Registration

​UI Settings Reference

​General Settings

​Custom Links

​Dashboard Configuration

​Performance Settings

​UI Extensions

​Content Configuration

​Dynamic Content

​Community and Feedback

​Theme Configuration

​Applying Customizations

​Using kubectl

​Using Rancher UI

​Using Rancher API

​Helm Chart Values

​Best Practices

​Examples

​Complete Branding Example

​Security Banner Example

​Troubleshooting

​Custom assets not loading

​Colors not applying

​NavLinks not appearing

​Related Resources

Build docs developers (and LLMs) love