docs: Add subfolder for GrafanaDashboard and GrafanaFolder in documentation

docs/docs/dashboards.md

@@ -7,7 +7,7 @@ weight: 13
 
 To view the entire configuration that you can do within dashboards, look at our [API documentation](../api/#grafanadashboardspec).
 
-## Dashboard managment
+## Dashboard management
 
 You can configure dashboards as code in many different ways.
 
@@ -257,8 +257,167 @@ Whenever a dashboard is imported into a Grafana, it gets assigned a random `uid`
 
 To mitigate the scenario, if `uid` is not hardcoded, the operator will insert the value taken from CR's `metadata.uid` (this value is automatically generated by Kubernetes itself for all resources).
 
+## Select the folder where the dashboard will be deployed
+
+By default, a dashboard will appear in a Folder with the name of the namespace
+
+```yaml
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaDashboard
+metadata:
+  name: grafana-folder-default
+  labels:
+    dashboards: "grafana"
+spec:
+  # the folder will be "default" by default
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+  json: |
+    {
+      "id": null,
+      "title": "Folder Without Folder Defined",
+      "tags": [],
+      "style": "dark",
+      "timezone": "browser",
+      "editable": true,
+      "hideControls": false,
+      "graphTooltip": 1,
+      "panels": [],
+      "time": {
+        "from": "now-6h",
+        "to": "now"
+      },
+      "timepicker": {
+        "time_options": [],
+        "refresh_intervals": []
+      },
+      "templating": {
+        "list": []
+      },
+      "annotations": {
+        "list": []
+      },
+      "refresh": "5s",
+      "schemaVersion": 17,
+      "version": 0,
+      "links": []
+    }
+```
+
+If you want to put the dashboard in a specific folder, you have two choices:
+
+* Use an `GrafanaFolder` resouce as a reference:
+
+```yaml
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaFolder
+metadata:
+  name: folder-ref
+spec:
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+  title: "Folder"
+
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaDashboard
+metadata:
+  name: grafana-folderref
+  labels:
+    dashboards: "grafana"
+spec:
+  folderRef: folder-ref
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+  json: |
+    {
+      "id": null,
+      "title": "Folder Ref With Folder",
+      "tags": [],
+      "style": "dark",
+      "timezone": "browser",
+      "editable": true,
+      "hideControls": false,
+      "graphTooltip": 1,
+      "panels": [],
+      "time": {
+        "from": "now-6h",
+        "to": "now"
+      },
+      "timepicker": {
+        "time_options": [],
+        "refresh_intervals": []
+      },
+      "templating": {
+        "list": []
+      },
+      "annotations": {
+        "list": []
+      },
+      "refresh": "5s",
+      "schemaVersion": 17,
+      "version": 0,
+      "links": []
+    }
+```
+
+* Use a static UID as a folder reference
+
+
+```yaml
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaDashboard
+metadata:
+  name: grafana-folderuid
+  labels:
+    dashboards: "grafana"
+spec:
+  folderUID: ec94e912-02f4-463b-9968-1f5f7db3531f
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+  json: |
+    {
+      "id": null,
+      "title": "Folder UID With Folder",
+      "tags": [],
+      "style": "dark",
+      "timezone": "browser",
+      "editable": true,
+      "hideControls": false,
+      "graphTooltip": 1,
+      "panels": [],
+      "time": {
+        "from": "now-6h",
+        "to": "now"
+      },
+      "timepicker": {
+        "time_options": [],
+        "refresh_intervals": []
+      },
+      "templating": {
+        "list": []
+      },
+      "annotations": {
+        "list": []
+      },
+      "refresh": "5s",
+      "schemaVersion": 17,
+      "version": 0,
+      "links": []
+    }
+```
+
 ## Custom folders
 
+> Note: This method is not recommended. Prefer to use the GrafanaFolder CR and `folderRef` field to declare a folder instead.
+
 In a standard scenario, the operator would use the namespace a CR is deployed to as a folder name in grafana. `folder` field can be used to set a custom folder name:
 
 ```yaml
@@ -274,6 +433,8 @@ spec:
   url: "https://raw.githubusercontent.com/grafana-operator/grafana-operator/master/examples/dashboard_from_url/dashboard.json"
 ```
 
+> Note: the field folder is ignored when `folderUID` or `folderRef` is already present in the GrafanaDashboard declaration.
+
 ## Dashboard customization by providing environment variables
 
 Will be pleasant for scenarios when you would like to extend the behaviour of jsonnet generation by parametrizing it with runtime Env vars:

docs/docs/folder.md

@@ -28,6 +28,54 @@ spec:
   title: custom title
 ```
 
+## Subfolder into an already existing Folder
+
+With the arrival of Grafana 10, you can create a complete `Folder` hierarchie in Grafana. To do this, you have two choices:
+
+* Use an existing GrafanaFolder CR as reference with the `parentFolderRef` field:
+
+```yaml
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaFolder
+metadata:
+  name: folder-with-parent
+spec:
+  title: parent folder
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaFolder
+metadata:
+  name: subfolder-in-parent
+spec:
+  title: subfolder
+  # GrafanaFolder parent folder reference
+  parentFolderRef: folder-with-parent
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+```
+
+* Select an existing Folder in Grafana using its UID:
+
+```yaml
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaFolder
+metadata:
+  name: existing-folder-uid
+spec:
+  # parent Folder uid to retrieve in your Grafana
+  parentFolderUID: "3e7b4fe1-ca90-4125-a8ab-06567c1971b5"
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+```
+
+
 ## Folder with custom permissions
 
 When `permissions` value is empty/absent, a folder is created with default permissions. In all other scenarios, a raw JSON is passed to Grafana API, and it's up to Grafana to interpret it.