Skip to content

Navigation Configuration

This guide provides comprehensive documentation for SPOG's navigation configuration system. Navigation controls the menu structure in the Glass UI, enabling you to organize dashboards, tools, and external resources in a way that matches your organizational structure and workflows.

What You'll Learn

  • How navigation provides the menu structure for the Glass UI
  • The three-level hierarchy: menus → sections → items
  • How to configure custom navigation menus via Helm values
  • How the default Tools menu works and when to use it
  • How to add external links that open in new tabs
  • How to control navigation visibility with permission flags
  • How navigation integrates with dashboards and authorization

Prerequisites

This guide assumes you have completed the Quickstart and understand the basics of SPOG. For information on creating dashboards to link to, see Configuring Dashboards and Playlists.

Navigation in SPOG provides the menu structure for the Glass UI sidebar. It enables users to discover and access different views of their infrastructure through a familiar, hierarchical menu system.

Key Concepts

Three-Level Hierarchy

Navigation follows a consistent three-level structure:

  1. Menus: Top-level groupings (e.g., "Regional Views", "Teams", "Tools")
  2. Sections: Subdivisions within menus (e.g., "Americas", "Europe" within "Regional Views")
  3. Items: Individual links to dashboards or external resources (e.g., "US East Production")

Configuration via Helm Values

Navigation is configured in your Glass UI Helm values under globalConfig.navigation. This allows you to define custom menu structures that align with your organizational needs.

Built-in Defaults

SPOG provides a default Tools menu with common operations like DNS Query and Flush Cache. This menu is automatically appended after your custom menus unless you disable defaults.

Permission-Based Visibility

Navigation items can be conditionally displayed based on REGO policy flags. Users only see menu items they have permission to access.

Dashboard Integration

Navigation items typically link to dashboard URLs. When a navigation item points to a dashboard, both the navigation permission and dashboard permission are evaluated.

Configuration Structure

Navigation is configured under globalConfig.navigation in your Glass UI Helm values file. The structure mirrors the three-level hierarchy:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
globalConfig:
  navigation:
    menus:
      - name: "Menu Name"
        sections:
          - name: "Section Name"
            items:
              - name: "Item Label"
                url: "/path/to/dashboard"
                description: "Tooltip text"
                external: false
                requires:
                  - "permission_flag"
Property Type Required Description
name string Yes Display label for the menu (shown in sidebar)
sections array Yes List of sections within this menu

Section Properties

Property Type Required Description
name string Yes Display label for the section (shown as section header)
items array Yes List of navigation items within this section

Item Properties

Property Type Required Default Description
name string Yes - Display label for the item (shown as link text)
url string Yes - Target URL path (internal) or full URL (external)
description string No - Tooltip text shown on hover
external boolean No false Set to true to open link in new tab with external icon
requires array No - List of permission flags required to view this item

Basic Example

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# Documentation Example: Basic Navigation Structure
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Configuration Structure - Basic Example
#
# Demonstrates the three-level hierarchy: menus → sections → items

globalConfig:
  navigation:
    menus:
      # Menu 1: Regional Views
      - name: "Regional Views"
        sections:
          # Section 1: Americas
          - name: "Americas"
            items:
              - name: "US East"
                url: "/regions/us-east"
                description: "US East clusters"
              - name: "US West"
                url: "/regions/us-west"
                description: "US West clusters"

          # Section 2: Europe
          - name: "Europe"
            items:
              - name: "EU West"
                url: "/regions/eu-west"
                description: "EU West clusters"
              - name: "EU Central"
                url: "/regions/eu-central"
                description: "EU Central clusters"

Default Navigation

SPOG provides a default Tools menu automatically, so you can deploy the Glass UI without any navigation configuration. The default menu includes common DNS operations.

Why Use the Default Menu?

The default Tools menu provides a consistent user experience across all SPOG installations. When users move between different SPOG deployments (e.g., from development to production, or between different teams), they can rely on familiar menu locations for common operations like DNS Query and Cache Flush.

Benefits of keeping the default menu:

  • Transferable knowledge: Users trained on one SPOG installation can immediately navigate another
  • Consistent documentation: SPOG documentation and tutorials reference the default menu locations
  • Reduced maintenance: Default menus receive updates automatically with Glass UI upgrades
  • Proven structure: The default organization reflects common operational workflows

Default Tools Menu Structure

The default Tools menu includes two sections: DNS Operations (containing DNS Query) and Cache Management (containing Flush Cache):

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Default Tools menu structure
# Note: Additional properties (description, external, requires) are available
# but not used in the default configuration
menus:
  - name: "Tools"
    sections:
      - name: "DNS Operations"
        items:
          - name: "DNS Query"
            url: "/dns-query"
      - name: "Cache Management"
        items:
          - name: "Flush Cache"
            url: "/clear-cache/all"

How Defaults Work

Automatic Inclusion: The default Tools menu is automatically appended after any custom menus you define.

Merge Behavior: User-defined menus appear first, followed by the default menus:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Your Helm values
globalConfig:
  navigation:
    menus:
      - name: "Regional Views"
        sections: [...]

# Resulting navigation in UI:
# 1. Regional Views (your custom menu)
# 2. Tools (default menu)

Disabling Defaults: To disable the default navigation entirely and provide your own Tools menu:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# Documentation Example: Disabling Default Navigation
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Default Navigation - Disabling Defaults
#
# Demonstrates disabling default navigation to provide custom Tools menu

globalConfig:
  defaults:
    enabled: false
  navigation:
    menus:
      - name: "My Custom Tools"
        sections:
          - name: "Operations"
            items:
              - name: "DNS Query"
                url: "/dns-query"
              - name: "Custom Tool"
                url: "/custom-tool"

Think Twice Before Disabling Defaults

When you set defaults.enabled: false, both the default dashboard and navigation are disabled. You must provide your own configuration for both. Only disable defaults if you have a compelling reason to completely replace the standard navigation structure—for most deployments, adding custom menus alongside the defaults provides the best balance of customization and consistency.

Navigation items can link to external resources like team wikis, runbooks, or monitoring dashboards. External links open in new tabs and display an external-link icon to indicate this behavior.

Set external: true to mark a link as external:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
globalConfig:
  navigation:
    menus:
      - name: "Resources"
        sections:
          - name: "Documentation"
            items:
              - name: "Team Wiki"
                url: "https://wiki.example.com/team"
                description: "Team documentation and runbooks"
                external: true

              - name: "Grafana Dashboard"
                url: "https://grafana.example.com/d/team-metrics"
                description: "Team metrics dashboard"
                external: true

Use external links to integrate with resources outside SPOG:

  • Team documentation and runbooks
  • External monitoring dashboards (Grafana, Prometheus)
  • Incident management and ticketing systems
  • Related infrastructure tools

See the "DevOps Team" example below for practical patterns.

Example: Team Resources Menu

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# Documentation Example: External Links
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: External Links - Example: Team Resources Menu
#
# Demonstrates external links that open in new tabs with permission control

globalConfig:
  navigation:
    menus:
      - name: "DevOps Team"
        sections:
          - name: "Dashboards"
            items:
              - name: "Team Overview"
                url: "/team/devops"
                description: "DevOps team clusters"

          - name: "Resources"
            items:
              - name: "Team Runbook"
                url: "https://docs.example.com/devops/runbook"
                description: "DevOps operational procedures"
                external: true
                requires:
                  - "navigation_devops_resources"

              - name: "Team Wiki"
                url: "https://wiki.example.com/devops"
                description: "DevOps team wiki"
                external: true
                requires:
                  - "navigation_devops_resources"

              - name: "Grafana Metrics"
                url: "https://grafana.example.com/d/devops-metrics"
                description: "Team performance metrics"
                external: true
                requires:
                  - "navigation_devops_resources"

Permission Control with requires

Navigation items can be conditionally displayed based on user permissions. The requires field specifies a list of permission flags that are evaluated by REGO policies. Items are hidden if the user lacks the required permissions.

Basic Permission Control

Add a requires array to any navigation item:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
globalConfig:
  navigation:
    menus:
      - name: "Admin"
        sections:
          - name: "Management"
            items:
              - name: "Global Overview"
                url: "/admin/global"
                requires:
                  - "navigation_admin_global"

              - name: "User Management"
                url: "/admin/users"
                requires:
                  - "navigation_admin_users"

Defining Permission Flags in REGO

Permission flags are evaluated by REGO policies in pdns_global_flags.rego. The flag names are completely arbitrary—you define them to match your organizational needs.

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
policy:
  policies:
    pdns_global_flags.rego: |
      package pdns_global_flags

      # DevOps team members can access DevOps resources
      navigation_devops_resources if "devops" in input.user.roles
      navigation_devops_resources if "admin" in input.user.roles

      # Platform team members can access Platform resources
      navigation_platform_resources if "platform" in input.user.roles
      navigation_platform_resources if "admin" in input.user.roles

      # Only admins can access admin navigation
      navigation_admin_global if "admin" in input.user.roles
      navigation_admin_users if "admin" in input.user.roles

How Permission Evaluation Works

Flag Naming: Flag names in the requires array must match rule names in your REGO policy. The naming convention navigation_* is strongly recommended to: - Distinguish navigation permissions from dashboard permissions (which use dashboard_*) - Make REGO policies easier to understand and maintain - Prevent naming conflicts between different permission types - Enable grep/search operations to find all navigation-related permissions

One Flag Per Item: Each navigation item should specify exactly one flag in requires. While the system technically supports multiple flags with OR logic, this approach is discouraged because:

  • REGO policies are better suited for expressing complex permission logic
  • Combining conditions in REGO makes the permission model more maintainable
  • Keeps navigation configuration simple and authorization logic centralized

Use REGO for Complex Permissions

Instead of listing multiple flags on a navigation item, create a single flag and define the OR/AND logic in your REGO policy:

YAML
1
2
3
4
5
6
# ✗ Avoid: Multiple flags on navigation item
- name: "Executive Dashboard"
  url: "/executive"
  requires:
    - "navigation_executive"
    - "navigation_admin"
YAML
1
2
3
4
5
# ✓ Preferred: Single flag, logic in REGO
- name: "Executive Dashboard"
  url: "/executive"
  requires:
    - "navigation_executive_access"
Rego
1
2
3
# REGO policy handles the OR logic
navigation_executive_access if "executive" in input.user.roles
navigation_executive_access if "admin" in input.user.roles

This pattern keeps your navigation configuration simple and moves complex authorization logic to where it belongs—your REGO policies.

Visibility: If the user lacks all required permissions, the navigation item is completely hidden from the UI. They won't see it in the menu.

No Flags: If requires is omitted, the navigation item is visible to all authenticated users. However, if the item links to a dashboard with its own requires field, the dashboard's permission requirements still apply when the user navigates there:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Navigation item visible to all
- name: "Global Overview"
  url: "/"
  # No requires field - navigation item shown to all authenticated users

# But dashboard may have restrictions
dashboards:
  global-overview:
    url: "/"
    requires:
      - "dashboard_global_view"  # Dashboard still requires this permission

In this case, all users see the navigation item, but only users with dashboard_global_view can actually load the dashboard.

Example: Role-Based Navigation

This example shows navigation tailored to different user roles:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# Documentation Example: Role-Based Navigation with Permissions
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Permission Control - Example: Role-Based Navigation
#
# Demonstrates navigation with granular permission control using requires

globalConfig:
  navigation:
    menus:
      # DevOps Team Menu
      - name: "DevOps Team"
        sections:
          - name: "Dashboards"
            items:
              - name: "Team Overview"
                url: "/team/devops"
                # No requires - all authenticated users can view

              - name: "Production"
                url: "/team/devops/production"
                requires:
                  - "navigation_devops_production"

          - name: "Resources"
            items:
              - name: "Team Runbook"
                url: "https://docs.example.com/devops/runbook"
                external: true
                requires:
                  - "navigation_devops_resources"

      # Admin Menu - external tools for administrators
      - name: "Administration"
        sections:
          - name: "Infrastructure"
            items:
              - name: "Kubernetes Dashboard"
                url: "https://k8s.example.com/dashboard"
                external: true
                requires:
                  - "navigation_admin"

              - name: "Keycloak Admin"
                url: "https://auth.example.com/admin"
                external: true
                requires:
                  - "navigation_admin"

# Corresponding REGO policies
policy:
  policies:
    pdns_global_flags.rego: |
      package pdns_global_flags

      navigation_devops_production if "devops" in input.user.roles
      navigation_devops_production if "admin" in input.user.roles

      navigation_devops_resources if "devops" in input.user.roles
      navigation_devops_resources if "admin" in input.user.roles

      navigation_admin if "admin" in input.user.roles

Integration with Dashboards

Navigation items typically link to dashboard URLs. When designing your navigation structure, consider how it integrates with your dashboard configuration and authorization model.

Dashboard URL Linking

The url field in the navigation item must exactly match the url field in the dashboard configuration for the routing to work correctly. When a user clicks the navigation item, the router navigates to that URL and matches it against registered dashboard routes.

Navigation items point to dashboards via the url field:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
globalConfig:
  navigation:
    menus:
      - name: "Regional Views"
        sections:
          - name: "Americas"
            items:
              - name: "US East"
                url: "/regions/us-east"  # Links to dashboard URL

  dashboards:
    us-east-dashboard:
      title: "US East Clusters"
      url: /regions/us-east  # Matches navigation item URL
      graphs:
        - widget: "cc-state-tree-table"
          args:
            filter: 'region = "us-east"'

Title Matching

Navigation item names don't have to exactly match dashboard titles, but keeping them similar helps users understand where clicking will take them.

URL Placeholders

Dashboards can use URL placeholders (route parameters) to create reusable configurations. Navigation items link to specific instances of these parameterized dashboards.

How it works:

  1. Dashboard URLs contain placeholders like :team or :region
  2. Navigation items use concrete values like /team/devops or /team/platform
  3. The router extracts the parameter value and substitutes it throughout the dashboard

Placeholder syntax:

Location Syntax Example
URL path :name /team/:team
Titles and filters :name title: ":team Dashboard"
Permission flags {{ name }} requires: ["dashboard_{{ team }}_view"]

Example: A single dashboard definition serves multiple teams:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# Documentation Example: URL Placeholders
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Integration with Dashboards - URL Placeholders
#
# Demonstrates how navigation items fill placeholders in dashboard URLs

globalConfig:
  navigation:
    menus:
      - name: "Teams"
        sections:
          - name: "Team Dashboards"
            items:
              # Each link fills :team with a different value
              - name: "DevOps Team"
                url: "/team/devops"      # :team = "devops"
              - name: "Platform Team"
                url: "/team/platform"    # :team = "platform"
              - name: "Security Team"
                url: "/team/security"    # :team = "security"

  dashboards:
    # ONE dashboard definition serves ALL teams
    team-overview:
      title: ":team Team Dashboard"           # Becomes "devops Team Dashboard"
      url: /team/:team                        # Matches /team/devops, /team/platform, etc.
      requires:
        - "dashboard_team_{{team}}_overview"  # Becomes "dashboard_team_devops_overview"
      graphs:
        - widget: "cc-state-tree-table"
          args:
            filter: 'team = ":team"'          # Becomes 'team = "devops"'

Benefits of using placeholders:

  • Reduced configuration: One dashboard definition instead of one per team/region
  • Easy scaling: Add new teams by adding navigation items and REGO rules—no dashboard changes needed
  • Consistency: All teams get the same dashboard layout automatically
  • Maintainability: Update the dashboard once, all teams benefit

When to Use Placeholders

Use placeholders when you have multiple similar entities (teams, regions, environments) that need identical dashboard layouts. If each entity needs a unique layout, use separate dashboard definitions instead.

URL Path Requirements

Internal URLs: Must match the url field defined in a dashboard configuration exactly:

  • Must start with / (e.g., /regions/us-east, not regions/us-east)
  • Are case-sensitive

External URLs: Must be complete URLs including protocol:

  • Valid: https://wiki.example.com/docs
  • Invalid: wiki.example.com/docs (missing protocol)

Unmatched URLs: If a navigation item URL doesn't match any registered dashboard route, clicking it will navigate to the URL but Vue Router will display a 404 page.

Permission Inheritance from Dashboards

When a navigation item links to a dashboard, the dashboard's requires field controls access. Avoid duplicating permissions on both the navigation item and the dashboard.

Permissions Belong with Dashboards

Keep permission flags on the dashboard, not the navigation item. The navigation system automatically hides items when users can't access the linked dashboard.

Recommended: Dashboard-Only Permissions

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
globalConfig:
  navigation:
    menus:
      - name: "Teams"
        sections:
          - name: "Dashboards"
            items:
              - name: "DevOps Team"
                url: "/team/devops"
                # No requires here - permissions come from the dashboard

  dashboards:
    devops-overview:
      title: "DevOps Team Dashboard"
      url: /team/devops
      requires:
        - "dashboard_devops_overview"  # Single permission check
      graphs:
        - widget: "cc-state-tree-table"
          args:
            filter: 'team = "devops"'

When to Use Navigation-Level Permissions

Use requires on navigation items only for:

  • External links: Links to external URLs that don't have dashboard permission checks
  • Non-dashboard internal links: Links to built-in pages like DNS Query or Cache Clear
  • Hidden from navigation but accessible via direct link: When dashboards should be accessible from external sources (wikis, runbooks, internal portals) but not cluttering the navigation menu
YAML
1
2
3
4
5
6
# External link needs its own permission
- name: "Team Runbook"
  url: "https://docs.example.com/devops/runbook"
  external: true
  requires:
    - "navigation_devops_resources"

Example: Complete Navigation + Dashboard Integration

This example shows a complete configuration with aligned permissions:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# Documentation Example: Navigation + Dashboard Integration
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Integration with Dashboards - Example: Complete Navigation + Dashboard Integration
#
# Demonstrates aligned navigation and dashboard configuration with permissions

globalConfig:
  navigation:
    menus:
      - name: "Teams"
        sections:
          - name: "Dashboards"
            items:
              - name: "DevOps Team"
                url: "/team/devops"
                requires:
                  - "navigation_team_devops"

              - name: "Platform Team"
                url: "/team/platform"
                requires:
                  - "navigation_team_platform"

  dashboards:
    devops-overview:
      title: "DevOps Team Dashboard"
      url: /team/devops
      requires:
        - "dashboard_devops_overview"
      graphs:
        - widget: "cc-state-tree-table"
          args:
            filter: 'team = "devops"'

    platform-overview:
      title: "Platform Team Dashboard"
      url: /team/platform
      requires:
        - "dashboard_platform_overview"
      graphs:
        - widget: "cc-state-tree-table"
          args:
            filter: 'team = "platform"'

# Corresponding REGO policies
policy:
  policies:
    pdns_global_flags.rego: |
      package pdns_global_flags

      # DevOps permissions
      navigation_team_devops if "devops" in input.user.roles
      navigation_team_devops if "admin" in input.user.roles
      dashboard_devops_overview if "devops" in input.user.roles
      dashboard_devops_overview if "admin" in input.user.roles

      # Platform permissions
      navigation_team_platform if "platform" in input.user.roles
      navigation_team_platform if "admin" in input.user.roles
      dashboard_platform_overview if "platform" in input.user.roles
      dashboard_platform_overview if "admin" in input.user.roles

Permission Flow:

  • DevOps users see "DevOps Team" navigation item and can access the DevOps dashboard
  • Platform users see "Platform Team" navigation item and can access the Platform dashboard
  • Admin users see both navigation items and can access both dashboards
  • Users without these roles see neither navigation item

Examples

Example 1: Basic Regional Navigation

A simple navigation structure organized by geographic region:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# Documentation Example: Basic Regional Navigation
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Examples - Example 1: Basic Regional Navigation
#
# A simple navigation structure organized by geographic region

globalConfig:
  navigation:
    menus:
      - name: "Regional Views"
        sections:
          - name: "Americas"
            items:
              - name: "US East"
                url: "/regions/us-east"
                description: "US East clusters"

              - name: "US West"
                url: "/regions/us-west"
                description: "US West clusters"

          - name: "Europe"
            items:
              - name: "EU West"
                url: "/regions/eu-west"
                description: "EU West clusters"

              - name: "EU Central"
                url: "/regions/eu-central"
                description: "EU Central clusters"

          - name: "Asia Pacific"
            items:
              - name: "AP North"
                url: "/regions/ap-north"
                description: "Asia Pacific North clusters"

              - name: "AP South"
                url: "/regions/ap-south"
                description: "Asia Pacific South clusters"

Result: Single menu with three sections (Americas, Europe, Asia Pacific), each containing regional dashboard links.

Navigation organized by team, including both internal dashboards and external resources:

YAML
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
# Example: Team-Based Navigation Configuration
# This example shows how to create a custom navigation menu for a specific team.
#
# The DevOps team gets a tailored menu structure focused on their workflows.

globalConfig:
  navigation:
    menus:
      # Menu 1: DevOps Team Menu
      - name: "DevOps Team"
        sections:
          # Section 1: Dashboard Links
          - name: "Dashboards"
            items:
              # Link to main team dashboard
              - name: "Team Overview"
                url: "/team/devops"
                description: "All DevOps clusters"

              # Link to production-only view
              - name: "Production"
                url: "/team/devops/production"
                description: "Production clusters only"

              # Link to environment breakdown
              - name: "By Environment"
                url: "/team/devops/environments"
                description: "Dev, Staging, Prod views"

          # Section 2: External Links (EXAMPLE ONLY - these URLs are fictional)
          - name: "Resources"
            items:
              # Example: Link to team runbook
              - name: "Team Runbook"
                url: "https://docs.example.com/devops/runbook"
                description: "DevOps operational procedures"
                external: true
                requires:
                  - "navigation_devops_resources"

              # Example: Link to team documentation
              - name: "Team Wiki"
                url: "https://wiki.example.com/devops"
                description: "DevOps team wiki"
                external: true
                requires:
                  - "navigation_devops_resources"

      # Menu 2: Platform Team Menu
      - name: "Platform Team"
        sections:
          # Section 1: Dashboard Links
          - name: "Dashboards"
            items:
              # Link to main team dashboard
              - name: "Team Overview"
                url: "/team/platform"
                description: "All Platform clusters"

              # Link to production-only view
              - name: "Production"
                url: "/team/platform/production"
                description: "Production clusters only"

              # Link to environment breakdown
              - name: "By Environment"
                url: "/team/platform/environments"
                description: "Dev, Staging, Prod views"

          # Section 2: External Links (EXAMPLE ONLY - these URLs are fictional)
          - name: "Resources"
            items:
              # Example: Link to team runbook
              - name: "Team Runbook"
                url: "https://docs.example.com/platform/runbook"
                description: "Platform operational procedures"
                external: true
                requires:
                  - "navigation_platform_resources"

              # Example: Link to team documentation
              - name: "Team Wiki"
                url: "https://wiki.example.com/platform"
                description: "Platform team wiki"
                external: true
                requires:
                  - "navigation_platform_resources"

      # Menu 3: Global Admin Menu
      - name: "Global Admin"
        sections:
          # Section 1: Global Dashboard Links
          - name: "Dashboards"
            items:
              # Link to global overview dashboard
              - name: "Global Overview"
                url: "/global/all-clusters"
                description: "All clusters across all teams"

              # Link to by-team view
              - name: "View by Team"
                url: "/global/by-team"
                description: "Clusters organized by team"

          # Section 2: All Teams Quick Access
          - name: "Team Dashboards"
            items:
              - name: "DevOps Team"
                url: "/team/devops"
                description: "DevOps team dashboard"

              - name: "Platform Team"
                url: "/team/platform"
                description: "Platform team dashboard"

# Note: The default "Tools" menu (DNS Query, Cache Management) is automatically
# appended after these custom menus.

# Navigation Visibility:
# - Navigation menus can be conditionally displayed based on user permissions
# - REGO policies control which menus and items a user sees
# - Users only see navigation items they have permission to access
#
# Integration with Dashboards:
# - Menu items link to dashboard URLs defined in team-based-dashboard.yaml
# - Example: "/team/devops" links to devops-overview dashboard

Result: Two team menus, each with dashboard links and external resources. External links are protected by permission flags.

Example 3: Multi-Dimensional Navigation

Navigation organized by multiple dimensions: region, service type, and tier:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# Documentation Example: Multi-Dimensional Navigation
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Examples - Example 3: Multi-Dimensional Navigation
#
# Navigation organized by multiple dimensions: region, service type, and tier

globalConfig:
  navigation:
    menus:
      # Regional Views Menu
      - name: "Regional Views"
        sections:
          - name: "Americas"
            items:
              - name: "Americas Overview"
                url: "/regions/americas"
              - name: "US East"
                url: "/regions/us-east"
              - name: "US West"
                url: "/regions/us-west"

          - name: "Europe"
            items:
              - name: "Europe Overview"
                url: "/regions/europe"
              - name: "EU West"
                url: "/regions/eu-west"
              - name: "EU Central"
                url: "/regions/eu-central"

          - name: "Asia Pacific"
            items:
              - name: "APAC Overview"
                url: "/regions/apac"
              - name: "AP North"
                url: "/regions/ap-north"
              - name: "AP South"
                url: "/regions/ap-south"

      # Service Type Menu
      - name: "Service Types"
        sections:
          - name: "DNS Services"
            items:
              - name: "Authoritative Servers"
                url: "/services/authoritative"
                description: "All authoritative DNS servers"

              - name: "Recursor Servers"
                url: "/services/recursor"
                description: "All recursor DNS servers"

          - name: "By Region"
            items:
              - name: "Americas Auth"
                url: "/services/americas/authoritative"

              - name: "Europe Auth"
                url: "/services/europe/authoritative"

      # Tier-Based Menu
      - name: "By Tier"
        sections:
          - name: "Production Tiers"
            items:
              - name: "Critical Systems"
                url: "/tier/critical"
                description: "Critical tier clusters"

              - name: "Standard Systems"
                url: "/tier/standard"
                description: "Standard tier clusters"

          - name: "Non-Production"
            items:
              - name: "Development"
                url: "/tier/development"

              - name: "Testing"
                url: "/tier/testing"

Result: Three menus providing different organizational views. Users can navigate by region, service type, or tier depending on their workflow.

Example 4: Conditional Navigation with Permissions

Navigation with granular permission control for different user roles:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
# Documentation Example: Conditional Navigation with Permissions
#
# Referenced in: docs/docs/concepts/navigation.md
# Section: Examples - Example 4: Conditional Navigation with Permissions
#
# Navigation with granular permission control for different user roles

globalConfig:
  navigation:
    menus:
      # Public Menu (no permissions required)
      - name: "Overview"
        sections:
          - name: "Global"
            items:
              - name: "Infrastructure Overview"
                url: "/"
                description: "Global DNS infrastructure view"

              - name: "Service Health"
                url: "/health"
                description: "Overall service health status"

      # DevOps Team Menu (requires devops role)
      - name: "DevOps"
        sections:
          - name: "Dashboards"
            items:
              - name: "Team Clusters"
                url: "/team/devops"
                requires:
                  - "navigation_team_devops"

              - name: "Production"
                url: "/team/devops/production"
                requires:
                  - "navigation_devops_production"

          - name: "Operations"
            items:
              - name: "Deploy Pipeline"
                url: "https://jenkins.example.com/devops"
                external: true
                requires:
                  - "navigation_devops_operations"

              - name: "Grafana Metrics"
                url: "https://grafana.example.com/d/devops"
                external: true
                requires:
                  - "navigation_devops_operations"

      # Admin Menu (requires admin role) - external infrastructure tools
      - name: "Administration"
        sections:
          - name: "Infrastructure"
            items:
              - name: "Kubernetes Dashboard"
                url: "https://k8s.example.com/dashboard"
                external: true
                requires:
                  - "navigation_admin"

              - name: "Keycloak Admin"
                url: "https://auth.example.com/admin"
                external: true
                requires:
                  - "navigation_admin"

              - name: "Grafana Admin"
                url: "https://grafana.example.com/admin"
                external: true
                requires:
                  - "navigation_admin"

# Corresponding REGO policies
policy:
  policies:
    pdns_global_flags.rego: |
      package pdns_global_flags

      # DevOps permissions
      navigation_team_devops if "devops" in input.user.roles
      navigation_team_devops if "admin" in input.user.roles

      navigation_devops_production if "devops" in input.user.roles
      navigation_devops_production if "admin" in input.user.roles

      navigation_devops_operations if "devops" in input.user.roles
      navigation_devops_operations if "admin" in input.user.roles

      # Admin permissions
      navigation_admin if "admin" in input.user.roles

Permission Flow:

  • All users see the "Overview" menu (no permissions required)
  • DevOps users see "Overview" + "DevOps" menus
  • Admin users see all three menus: "Overview" + "DevOps" + "Administration"
  • External links in "DevOps" menu require specific operation permissions

Summary

Navigation configuration uses a three-level hierarchy (menus → sections → items) under globalConfig.navigation. Key points:

  • Default Tools menu is automatically appended; disable with globalConfig.defaults.enabled: false
  • External links use external: true to open in new tabs with security attributes
  • Permission control via requires flags evaluated by REGO policies—keep permissions on dashboards, not navigation items
  • URL placeholders (:name syntax) enable single dashboard definitions serving multiple navigation links

For complete deployments, see the Team-Based Deployment and Multi-Region Operations examples.