Skip to content

Commit 78d8c19

Browse files
committed
[backups,dashboard] Add dev guide for dashboard
Moved README describing how to add new resources to the Cozystack dashboard to a separate commit to directly reference relevant code changes from the document. Signed-off-by: Timofei Larkin <[email protected]>
1 parent 88da2d1 commit 78d8c19

1 file changed

Lines changed: 355 additions & 0 deletions

File tree

Lines changed: 355 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,355 @@
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

Comments
 (0)