-
Notifications
You must be signed in to change notification settings - Fork 206
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Add documentation for extending the map
Signed-off-by: Oleksandr Dubenko <[email protected]>
- Loading branch information
Showing
7 changed files
with
151 additions
and
10 deletions.
There are no files selected for viewing
141 changes: 141 additions & 0 deletions
141
docs/development/plugins/functionality/extending-the-map.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,141 @@ | ||
| --- | ||
| title: Extending the Map | ||
| sidebar_label: Extending the Map | ||
| --- | ||
|
|
||
| Map view displays cluster resource on a graph. Plugins can extend this graph by adding nodes and edges. | ||
|
|
||
| ## Nodes, edges and sources | ||
|
|
||
| **Node** represents a Kubernetes resource. **Edges** connect different **nodes**, for example ReplicaSet connects to Pods it owns. | ||
|
|
||
| <figure> | ||
|
|
||
|  | ||
|
|
||
| <figcaption>1 ReplicaSet and 3 Pods it owns</figcaption> | ||
| </figure> | ||
|
|
||
| To add your own nodes and edges you need to define a **Source** | ||
|
|
||
| A graph **Source** represents a collection of Nodes and Edges along with name and icon. Source may contain other Sources. | ||
|
|
||
| <figure style="text-align: center"> | ||
|
|
||
|  | ||
|
|
||
| <figcaption>Example: "Pods" is a source that contains Nodes for all the Pods in the cluster, "Workloads" is also a source containing other Sources.</figcaption> | ||
| </figure> | ||
|
|
||
| ## Creating and registering a Source | ||
|
|
||
| To define a Source create an object with the following structure: | ||
|
|
||
| ```tsx | ||
| const mySource = { | ||
| id: "my-source", // ID of the source should be unique | ||
| label: "My Source", // label will be displayed in source picker | ||
| // you can provide an icon | ||
| icon: ( | ||
| <img | ||
| src="https://headlamp.dev/img/favicon.png" | ||
| alt="My Source logo" | ||
| style={{ width: "100%", height: "100%" }} | ||
| /> | ||
| ), | ||
| /** | ||
| * useData is a hook that will be called to load nodes and edges for your source | ||
| * You can use hooks here that Headlamp provides to load Kubernetes resources | ||
| * this hook should return an object with nodes and edges or `null` if it's loading | ||
| * it's important that return object is not recreated every time, so useMemo is required | ||
| */ | ||
| useData() { | ||
| return useMemo(() => { | ||
| // This would come from kubernetes API but it's hardcoded here as an example | ||
| const myResource = { | ||
| kind: "MyResourceKind", | ||
| metadata: { | ||
| uid: "1234", | ||
| name: "my-test-resource", | ||
| namespace: "test-namespace", | ||
| creationTimestamp: "1234", | ||
| }, | ||
| }; | ||
|
|
||
| const edges = []; // no edges in this source | ||
| const nodes = [ | ||
| { | ||
| id: "1234", // ID should be unique | ||
| type: "kubeObject", // 'kubeObject' type represnets a kubernetes resource | ||
| data: { | ||
| // resource field is required and should contain KubeObject | ||
| resource: new KubeObject(myResource), | ||
| }, | ||
| }, | ||
| ]; | ||
|
|
||
| return { edges, nodes }; | ||
| }, []); | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| Then to register it call `registerMapSource` | ||
|
|
||
| ```tsx | ||
| registerMapSource(mySource); | ||
| ``` | ||
|
|
||
| You'll now see it in the Source picker and the Node on the Map: | ||
|
|
||
| <figure style="text-align: center"> | ||
|
|
||
|  | ||
|
|
||
| <figcaption>"My Source" is listed on the bottom. Enabled by default.</figcaption> | ||
| </figure> | ||
|
|
||
| <figure style="text-align: center"> | ||
|
|
||
|  | ||
|
|
||
| <figcaption>MyCustomResource Node displayed with default Icon</figcaption> | ||
| </figure> | ||
|
|
||
| ## Node Icons | ||
|
|
||
| To add an icon to the Node you need to call `registerKindIcon`. | ||
|
|
||
| Note: This is different from the Source icon. One Source may contain multiple different kinds of objects. | ||
|
|
||
| ```tsx | ||
| registerKindIcon("MyCustomResource", { | ||
| // icon is a JSX element | ||
| icon: <img src="https://headlamp.dev/img/favicon.png" />, | ||
| }); | ||
| ``` | ||
|
|
||
| <figure style="text-align: center"> | ||
|
|
||
|  | ||
|
|
||
| <figcaption>Node with a custom Icon</figcaption> | ||
| </figure> | ||
|
|
||
| ## Details panel | ||
|
|
||
| When selecting a Node Map will display a details panel for the selected object. | ||
| To add a details Panel for your Nodes call function `registerKindDetailsPage` | ||
|
|
||
| ```tsx | ||
| // You need to provide 'kind' of the resource and a React Component that will render details | ||
| // The props will contain name and a namespace of the Kubernetes Resource | ||
| // Details page usually loads the resource by name and namespace | ||
| registerKindDetailsPage("MyCustomResource", { | ||
| component: (props) => ( | ||
| <div style={{ padding: "60px" }}> | ||
| Details {props.name} {props.namespace} | ||
| </div> | ||
| ), | ||
| }); | ||
| ``` |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+30.7 KB
docs/development/plugins/functionality/images/node-without-an-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+37.1 KB
docs/development/plugins/functionality/images/source-picker-workloads.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters