|
| 1 | +# Dashboard Resource Integration Guide |
| 2 | + |
| 3 | +This guide explains how to add a new Kubernetes resource to the Cozystack dashboard. The dashboard provides a unified interface for viewing and managing Kubernetes resources through custom table views, detail pages, and sidebar navigation. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Adding a new resource to the dashboard requires three main components: |
| 8 | + |
| 9 | +1. **CustomColumnsOverride**: Defines how the resource appears in list/table views |
| 10 | +2. **Factory**: Defines the detail page layout for individual resource instances |
| 11 | +3. **Sidebar Entry**: Adds navigation to the resource in the sidebar menu |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +- The resource must have a Kubernetes CustomResourceDefinition (CRD) or be a built-in Kubernetes resource |
| 16 | +- Know the resource's API group, version, kind, and plural name |
| 17 | +- Understand the resource's spec structure to display relevant fields |
| 18 | + |
| 19 | +## Step-by-Step Guide |
| 20 | + |
| 21 | +### Step 1: Add CustomColumnsOverride |
| 22 | + |
| 23 | +The CustomColumnsOverride defines the columns shown in the resource list table and how clicking on a row navigates to the detail page. |
| 24 | + |
| 25 | +**Location**: `internal/controller/dashboard/static_refactored.go` in `CreateAllCustomColumnsOverrides()` |
| 26 | + |
| 27 | +**Example**: |
| 28 | +```go |
| 29 | +// Stock namespace backups cozystack io v1alpha1 plans |
| 30 | +createCustomColumnsOverride("stock-namespace-/backups.cozystack.io/v1alpha1/plans", []any{ |
| 31 | + createCustomColumnWithJsonPath("Name", ".metadata.name", "Plan", "", "/openapi-ui/{2}/{reqsJsonPath[0]['.metadata.namespace']['-']}/factory/plan-details/{reqsJsonPath[0]['.metadata.name']['-']}"), |
| 32 | + createApplicationRefColumn("Application"), |
| 33 | + createTimestampColumn("Created", ".metadata.creationTimestamp"), |
| 34 | +}), |
| 35 | +``` |
| 36 | + |
| 37 | +**Key Components**: |
| 38 | +- **ID Format**: `stock-namespace-/{group}/{version}/{plural}` |
| 39 | +- **Name Column**: Use `createCustomColumnWithJsonPath()` with: |
| 40 | + - Badge value: Resource kind in PascalCase (e.g., "Plan", "Service") |
| 41 | + - Link href: `/openapi-ui/{2}/{namespace}/factory/{resource-details}/{name}` |
| 42 | +- **Additional Columns**: Use helper functions like: |
| 43 | + - `createStringColumn()`: Simple string values |
| 44 | + - `createTimestampColumn()`: Timestamp fields |
| 45 | + - `createReadyColumn()`: Ready status from conditions |
| 46 | + - Custom helpers for complex fields |
| 47 | + |
| 48 | +**Helper Functions Available**: |
| 49 | +- `createCustomColumnWithJsonPath(name, jsonPath, badgeValue, badgeColor, linkHref)`: Column with badge and link |
| 50 | +- `createStringColumn(name, jsonPath)`: Simple string column |
| 51 | +- `createTimestampColumn(name, jsonPath)`: Timestamp with formatting |
| 52 | +- `createReadyColumn()`: Ready status column |
| 53 | +- `createBoolColumn(name, jsonPath)`: Boolean column |
| 54 | +- `createArrayColumn(name, jsonPath)`: Array column |
| 55 | + |
| 56 | +### Step 2: Add Factory (Detail Page) |
| 57 | + |
| 58 | +The Factory defines the detail page layout when viewing an individual resource instance. |
| 59 | + |
| 60 | +**Location**: `internal/controller/dashboard/static_refactored.go` in `CreateAllFactories()` |
| 61 | + |
| 62 | +**Using Unified Factory Approach** (Recommended): |
| 63 | +```go |
| 64 | +// Resource details factory using unified approach |
| 65 | +resourceConfig := UnifiedResourceConfig{ |
| 66 | + Name: "resource-details", // Must match the href in CustomColumnsOverride |
| 67 | + ResourceType: "factory", |
| 68 | + Kind: "ResourceKind", // PascalCase |
| 69 | + Plural: "resources", // lowercase plural |
| 70 | + Title: "resource", // lowercase singular |
| 71 | +} |
| 72 | +resourceTabs := []any{ |
| 73 | + map[string]any{ |
| 74 | + "key": "details", |
| 75 | + "label": "Details", |
| 76 | + "children": []any{ |
| 77 | + contentCard("details-card", map[string]any{ |
| 78 | + "marginBottom": "24px", |
| 79 | + }, []any{ |
| 80 | + antdText("details-title", true, "Resource details", map[string]any{ |
| 81 | + "fontSize": 20, |
| 82 | + "marginBottom": "12px", |
| 83 | + }), |
| 84 | + spacer("details-spacer", 16), |
| 85 | + antdRow("details-grid", []any{48, 12}, []any{ |
| 86 | + antdCol("col-left", 12, []any{ |
| 87 | + antdFlexVertical("col-left-stack", 24, []any{ |
| 88 | + // Metadata fields: Name, Namespace, Created, etc. |
| 89 | + }), |
| 90 | + }), |
| 91 | + antdCol("col-right", 12, []any{ |
| 92 | + antdFlexVertical("col-right-stack", 24, []any{ |
| 93 | + // Spec fields |
| 94 | + }), |
| 95 | + }), |
| 96 | + }), |
| 97 | + }), |
| 98 | + }, |
| 99 | + }, |
| 100 | +} |
| 101 | +resourceSpec := createUnifiedFactory(resourceConfig, resourceTabs, []any{"/api/clusters/{2}/k8s/apis/{group}/{version}/namespaces/{3}/{plural}/{6}"}) |
| 102 | + |
| 103 | +// Add to return list |
| 104 | +return []*dashboardv1alpha1.Factory{ |
| 105 | + // ... other factories |
| 106 | + createFactory("resource-details", resourceSpec), |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +**Key Components**: |
| 111 | +- **Factory Key**: Must match the href path segment (e.g., `plan-details` matches `/factory/plan-details/...`) |
| 112 | +- **API Endpoint**: `/api/clusters/{2}/k8s/apis/{group}/{version}/namespaces/{3}/{plural}/{6}` |
| 113 | + - `{2}`: Cluster name |
| 114 | + - `{3}`: Namespace |
| 115 | + - `{6}`: Resource name |
| 116 | +- **Sidebar Tags**: Automatically set to `["{lowercase-kind}-sidebar"]` by `createUnifiedFactory()` |
| 117 | +- **Tabs**: Define the detail page content (Details, YAML, etc.) |
| 118 | + |
| 119 | +**UI Helper Functions**: |
| 120 | +- `contentCard(id, style, children)`: Container card |
| 121 | +- `antdText(id, strong, text, style)`: Text element |
| 122 | +- `antdFlexVertical(id, gap, children)`: Vertical flex container |
| 123 | +- `antdRow(id, gutter, children)`: Row layout |
| 124 | +- `antdCol(id, span, children)`: Column layout |
| 125 | +- `parsedText(id, text, style)`: Text with JSON path parsing |
| 126 | +- `parsedTextWithFormatter(id, text, formatter)`: Formatted text (e.g., timestamp) |
| 127 | +- `spacer(id, space)`: Spacing element |
| 128 | + |
| 129 | +**Displaying Fields**: |
| 130 | +```go |
| 131 | +antdFlexVertical("field-block", 4, []any{ |
| 132 | + antdText("field-label", true, "Field Label", nil), |
| 133 | + parsedText("field-value", "{reqsJsonPath[0]['.spec.fieldName']['-']}", nil), |
| 134 | +}), |
| 135 | +``` |
| 136 | + |
| 137 | +### Step 3: Add Sidebar Entry |
| 138 | + |
| 139 | +The sidebar entry adds navigation to the resource in the sidebar menu. |
| 140 | + |
| 141 | +**Location**: `internal/controller/dashboard/sidebar.go` in `ensureSidebar()` |
| 142 | + |
| 143 | +**3a. Add to keysAndTags** (around line 110-116): |
| 144 | +```go |
| 145 | +// Add sidebar for {group} {kind} resource |
| 146 | +keysAndTags["{plural}"] = []any{"{lowercase-kind}-sidebar"} |
| 147 | +``` |
| 148 | + |
| 149 | +**3b. Add Sidebar Section** (if creating a new section, around line 169): |
| 150 | +```go |
| 151 | +// Add hardcoded {SectionName} section |
| 152 | +menuItems = append(menuItems, map[string]any{ |
| 153 | + "key": "{section-key}", |
| 154 | + "label": "{SectionName}", |
| 155 | + "children": []any{ |
| 156 | + map[string]any{ |
| 157 | + "key": "{plural}", |
| 158 | + "label": "{ResourceLabel}", |
| 159 | + "link": "/openapi-ui/{clusterName}/{namespace}/api-table/{group}/{version}/{plural}", |
| 160 | + }, |
| 161 | + }, |
| 162 | +}), |
| 163 | +``` |
| 164 | + |
| 165 | +**3c. Add Sidebar ID to targetIDs** (around line 220): |
| 166 | +```go |
| 167 | +"stock-project-factory-{lowercase-kind}-details", |
| 168 | +``` |
| 169 | + |
| 170 | +**3d. Update Category Ordering** (if adding a new section): |
| 171 | +- Update the comment around line 29 to include the new section |
| 172 | +- Update `orderCategoryLabels()` function if needed |
| 173 | +- Add skip condition in the category loop (around line 149) |
| 174 | + |
| 175 | +**Important Notes**: |
| 176 | +- The sidebar tag (`{lowercase-kind}-sidebar`) must match what the Factory uses |
| 177 | +- The link format: `/openapi-ui/{clusterName}/{namespace}/api-table/{group}/{version}/{plural}` |
| 178 | +- All sidebars share the same `keysAndTags` and `menuItems`, so changes affect all sidebar instances |
| 179 | + |
| 180 | +### Step 4: Verify Integration |
| 181 | + |
| 182 | +1. **Check Factory-Sidebar Connection**: |
| 183 | + - Factory uses `sidebarTags: ["{lowercase-kind}-sidebar"]` |
| 184 | + - Sidebar has `keysAndTags["{plural}"] = []any{"{lowercase-kind}-sidebar"}` |
| 185 | + - Sidebar ID `stock-project-factory-{lowercase-kind}-details` exists in `targetIDs` |
| 186 | + |
| 187 | +2. **Check Navigation Flow**: |
| 188 | + - Sidebar link → List table (CustomColumnsOverride) |
| 189 | + - List table Name column → Detail page (Factory) |
| 190 | + - All paths use consistent naming |
| 191 | + |
| 192 | +3. **Test**: |
| 193 | + - Verify the resource appears in the sidebar |
| 194 | + - Verify the list table displays correctly |
| 195 | + - Verify clicking a resource navigates to the detail page |
| 196 | + - Verify the detail page displays all relevant fields |
| 197 | + |
| 198 | +## Common Patterns |
| 199 | + |
| 200 | +### Displaying Object References |
| 201 | + |
| 202 | +For fields that reference other resources (e.g., `applicationRef`, `storageRef`): |
| 203 | + |
| 204 | +```go |
| 205 | +// In CustomColumnsOverride |
| 206 | +createApplicationRefColumn("Application"), // Uses helper function |
| 207 | + |
| 208 | +// In Factory details tab |
| 209 | +parsedText("application-ref-value", |
| 210 | + "{reqsJsonPath[0]['.spec.applicationRef.kind']['-']}.{reqsJsonPath[0]['.spec.applicationRef.apiGroup']['-']}/{reqsJsonPath[0]['.spec.applicationRef.name']['-']}", |
| 211 | + nil), |
| 212 | +``` |
| 213 | + |
| 214 | +### Displaying Timestamps |
| 215 | + |
| 216 | +```go |
| 217 | +antdFlexVertical("created-block", 4, []any{ |
| 218 | + antdText("time-label", true, "Created", nil), |
| 219 | + antdFlex("time-block", 6, []any{ |
| 220 | + map[string]any{ |
| 221 | + "type": "antdText", |
| 222 | + "data": map[string]any{ |
| 223 | + "id": "time-icon", |
| 224 | + "text": "🌐", |
| 225 | + }, |
| 226 | + }, |
| 227 | + map[string]any{ |
| 228 | + "type": "parsedText", |
| 229 | + "data": map[string]any{ |
| 230 | + "formatter": "timestamp", |
| 231 | + "id": "time-value", |
| 232 | + "text": "{reqsJsonPath[0]['.metadata.creationTimestamp']['-']}", |
| 233 | + }, |
| 234 | + }, |
| 235 | + }), |
| 236 | +}), |
| 237 | +``` |
| 238 | + |
| 239 | +### Displaying Namespace with Link |
| 240 | + |
| 241 | +```go |
| 242 | +antdFlexVertical("meta-namespace-block", 8, []any{ |
| 243 | + antdText("meta-namespace-label", true, "Namespace", nil), |
| 244 | + antdFlex("header-row", 6, []any{ |
| 245 | + // Badge component |
| 246 | + map[string]any{ |
| 247 | + "type": "antdText", |
| 248 | + "data": map[string]any{ |
| 249 | + "id": "header-badge", |
| 250 | + "text": "NS", |
| 251 | + "title": "namespace", |
| 252 | + "style": map[string]any{ |
| 253 | + "backgroundColor": "#a25792ff", |
| 254 | + // ... badge styles |
| 255 | + }, |
| 256 | + }, |
| 257 | + }, |
| 258 | + // Link component |
| 259 | + map[string]any{ |
| 260 | + "type": "antdLink", |
| 261 | + "data": map[string]any{ |
| 262 | + "id": "namespace-link", |
| 263 | + "text": "{reqsJsonPath[0]['.metadata.namespace']['-']}", |
| 264 | + "href": "/openapi-ui/{2}/{reqsJsonPath[0]['.metadata.namespace']['-']}/factory/marketplace", |
| 265 | + }, |
| 266 | + }, |
| 267 | + }), |
| 268 | +}), |
| 269 | +``` |
| 270 | + |
| 271 | +## File Reference |
| 272 | + |
| 273 | +- **CustomColumnsOverride**: `internal/controller/dashboard/static_refactored.go` → `CreateAllCustomColumnsOverrides()` |
| 274 | +- **Factory**: `internal/controller/dashboard/static_refactored.go` → `CreateAllFactories()` |
| 275 | +- **Sidebar**: `internal/controller/dashboard/sidebar.go` → `ensureSidebar()` |
| 276 | +- **Helper Functions**: `internal/controller/dashboard/static_helpers.go` |
| 277 | +- **UI Helpers**: `internal/controller/dashboard/ui_helpers.go` |
| 278 | +- **Unified Helpers**: `internal/controller/dashboard/unified_helpers.go` |
| 279 | + |
| 280 | +## AI Agent Prompt Template |
| 281 | + |
| 282 | +Use this template when asking an AI agent to add a new resource to the dashboard: |
| 283 | + |
| 284 | +``` |
| 285 | +Please add support for the {ResourceKind} resource ({group}/{version}/{plural}) to the Cozystack dashboard. |
| 286 | +
|
| 287 | +Resource Details: |
| 288 | +- API Group: {group} |
| 289 | +- Version: {version} |
| 290 | +- Kind: {ResourceKind} |
| 291 | +- Plural: {plural} |
| 292 | +- Namespaced: {true/false} |
| 293 | +
|
| 294 | +Requirements: |
| 295 | +1. Add a CustomColumnsOverride in CreateAllCustomColumnsOverrides() with: |
| 296 | + - ID: stock-namespace-/{group}/{version}/{plural} |
| 297 | + - Name column with {ResourceKind} badge linking to /factory/{lowercase-kind}-details/{name} |
| 298 | + - Additional columns: {list relevant columns} |
| 299 | + |
| 300 | +2. Add a Factory in CreateAllFactories() with: |
| 301 | + - Key: {lowercase-kind}-details |
| 302 | + - API endpoint: /api/clusters/{2}/k8s/apis/{group}/{version}/namespaces/{3}/{plural}/{6} |
| 303 | + - Details tab showing all spec fields: |
| 304 | + {list spec fields to display} |
| 305 | + - Use createUnifiedFactory() approach |
| 306 | + |
| 307 | +3. Add sidebar entry in ensureSidebar(): |
| 308 | + - Add keysAndTags entry: keysAndTags["{plural}"] = []any{"{lowercase-kind}-sidebar"} |
| 309 | + - Add sidebar section: {specify section name or "add to existing section"} |
| 310 | + - Add to targetIDs: "stock-project-factory-{lowercase-kind}-details" |
| 311 | + |
| 312 | +4. Ensure Factory sidebarTags matches the keysAndTags entry |
| 313 | +
|
| 314 | +Please follow the existing patterns in the codebase, particularly the Plan resource implementation as a reference. |
| 315 | +``` |
| 316 | + |
| 317 | +## Example: Plan Resource |
| 318 | + |
| 319 | +The Plan resource (`backups.cozystack.io/v1alpha1/plans`) serves as a complete reference implementation: |
| 320 | + |
| 321 | +- **CustomColumnsOverride**: [Diff](https://github.com/cozystack/cozystack/compare/1f0b5ff9ac0d9d8896af46f8a19501c8b728671d..88da2d1f642b6cf03873d368dfdc675de23f1513#diff-8309b1db3362715b3d94a8b0beae7e95d3ccaf248d4f8702aaa12fba398da895R374-R380) in `static_refactored.go` |
| 322 | +- **Factory**: [Diff](https://github.com/cozystack/cozystack/compare/1f0b5ff9ac0d9d8896af46f8a19501c8b728671d..88da2d1f642b6cf03873d368dfdc675de23f1513#diff-8309b1db3362715b3d94a8b0beae7e95d3ccaf248d4f8702aaa12fba398da895R1443-R1558) in `static_refactored.go` |
| 323 | +- **Sidebar**: [Diff](https://github.com/cozystack/cozystack/compare/1f0b5ff9ac0d9d8896af46f8a19501c8b728671d..88da2d1f642b6cf03873d368dfdc675de23f1513#diff-be79027f7179e457a8f10e225bb921a197ffa390eb8f916d8d21379fadd54a56) in `sidebar.go` |
| 324 | +- **Helper Function**: `createApplicationRefColumn()` in `static_helpers.go` ([diff](https://github.com/cozystack/cozystack/compare/1f0b5ff9ac0d9d8896af46f8a19501c8b728671d..88da2d1f642b6cf03873d368dfdc675de23f1513#diff-f17bcccc089cac3a8e965b13b9ab26e678d45bfc9a58d842399f218703e06a08R1026-R1046)) |
| 325 | + |
| 326 | +Review [this implementation](https://github.com/cozystack/cozystack/compare/1f0b5ff9ac0d9d8896af46f8a19501c8b728671d..88da2d1f642b6cf03873d368dfdc675de23f1513) for a complete working example. |
| 327 | + |
| 328 | +## Troubleshooting |
| 329 | + |
| 330 | +### Resource doesn't appear in sidebar |
| 331 | +- Check that `keysAndTags["{plural}"]` is set correctly |
| 332 | +- Verify the sidebar section is added to `menuItems` |
| 333 | +- Ensure the sidebar ID is in `targetIDs` |
| 334 | + |
| 335 | +### Clicking resource doesn't navigate to detail page |
| 336 | +- Verify the CustomColumnsOverride href matches the Factory key |
| 337 | +- Check that the Factory key is exactly `{lowercase-kind}-details` |
| 338 | +- Ensure the Factory is added to the return list in `CreateAllFactories()` |
| 339 | + |
| 340 | +### Detail page shows wrong sidebar |
| 341 | +- Verify Factory `sidebarTags` matches `keysAndTags["{plural}"]` |
| 342 | +- Check that the sidebar ID `stock-project-factory-{lowercase-kind}-details` exists |
| 343 | +- Ensure all sidebars are updated (they share the same `keysAndTags`) |
| 344 | + |
| 345 | +### Fields not displaying correctly |
| 346 | +- Verify JSON paths are correct (use `.spec.fieldName` format) |
| 347 | +- Check that `reqsJsonPath[0]` index is used for single resource views |
| 348 | +- Ensure field names match the actual resource spec structure |
| 349 | + |
| 350 | +## Additional Resources |
| 351 | + |
| 352 | +- Kubernetes API Conventions: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md |
| 353 | +- Dashboard API Types: `api/dashboard/v1alpha1/` |
| 354 | +- Resource Types: `api/backups/v1alpha1/` (example) |
| 355 | + |
0 commit comments