feat: add support for raw folder permissions

api/v1beta1/grafanafolder_types.go

@@ -31,6 +31,10 @@ type GrafanaFolderSpec struct {
 	// +optional
 	Title string `json:"title,omitempty"`
 
+	// raw json with folder permissions
+	// +optional
+	Permissions string `json:"permissions,omitempty"`
+
 	// selects Grafanas for import
 	InstanceSelector *metav1.LabelSelector `json:"instanceSelector"`
 
@@ -85,6 +89,7 @@ func (in *GrafanaFolderList) Find(namespace string, name string) *GrafanaFolder
 func (in *GrafanaFolder) Hash() string {
 	hash := sha256.New()
 	hash.Write([]byte(in.Spec.Title))
+	hash.Write([]byte(in.Spec.Permissions))
 	return fmt.Sprintf("%x", hash.Sum(nil))
 }
 

bundle/manifests/grafana.integreatly.org_grafanafolders.yaml

@@ -52,6 +52,8 @@ spec:
                     type: object
                 type: object
                 x-kubernetes-map-type: atomic
+              permissions:
+                type: string
               title:
                 type: string
             required:

config/crd/bases/grafana.integreatly.org_grafanafolders.yaml

@@ -53,6 +53,8 @@ spec:
                     type: object
                 type: object
                 x-kubernetes-map-type: atomic
+              permissions:
+                type: string
               title:
                 type: string
             required:

config/grafana.integreatly.org_grafanafolders.yaml

@@ -84,6 +84,9 @@ spec:
                     type: object
                 type: object
                 x-kubernetes-map-type: atomic
+              permissions:
+                description: raw json with folder permissions
+                type: string
               title:
                 type: string
             required:

controllers/grafanafolder_controller.go

@@ -18,6 +18,7 @@ package controllers
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"strings"
 	"time"
@@ -301,14 +302,12 @@ func (r *GrafanaFolderReconciler) onFolderCreated(ctx context.Context, grafana *
 			}
 		}
 
-		if cr.Unchanged() && uid == remoteUID {
-			return nil
-		}
-
-		// Update title and replace uid if needed
-		err = grafanaClient.UpdateFolder(remoteUID, title, uid)
-		if err != nil {
-			return err
+		if !cr.Unchanged() || uid != remoteUID {
+			// Update title and replace uid if needed
+			err = grafanaClient.UpdateFolder(remoteUID, title, uid)
+			if err != nil {
+				return err
+			}
 		}
 	} else {
 		folderFromClient, err := grafanaClient.NewFolder(title, uid)
@@ -330,6 +329,20 @@ func (r *GrafanaFolderReconciler) onFolderCreated(ctx context.Context, grafana *
 		}
 	}
 
+	// NOTE: it's up to a user to reset permissions with correct json
+	if !cr.Unchanged() && cr.Spec.Permissions != "" {
+		permissions := grapi.PermissionItems{}
+		err = json.Unmarshal([]byte(cr.Spec.Permissions), &permissions)
+		if err != nil {
+			return fmt.Errorf("failed to unmarshal spec.permissions: %w", err)
+		}
+
+		err = grafanaClient.UpdateFolderPermissions(uid, &permissions)
+		if err != nil {
+			return fmt.Errorf("failed to update folder permissions: %w", err)
+		}
+	}
+
 	return r.UpdateStatus(ctx, cr)
 }
 

deploy/helm/grafana-operator/crds/grafana.integreatly.org_grafanafolders.yaml

@@ -53,6 +53,8 @@ spec:
                     type: object
                 type: object
                 x-kubernetes-map-type: atomic
+              permissions:
+                type: string
               title:
                 type: string
             required:

deploy/kustomize/base/crds.yaml

@@ -423,6 +423,9 @@ spec:
                     type: object
                 type: object
                 x-kubernetes-map-type: atomic
+              permissions:
+                description: raw json with folder permissions
+                type: string
               title:
                 type: string
             required:

docs/docs/api.md

@@ -902,6 +902,13 @@ GrafanaFolderSpec defines the desired state of GrafanaFolder
           allow to import this resources from an operator in a different namespace<br/>
         </td>
         <td>false</td>
+      </tr><tr>
+        <td><b>permissions</b></td>
+        <td>string</td>
+        <td>
+          raw json with folder permissions<br/>
+        </td>
+        <td>false</td>
       </tr><tr>
         <td><b>title</b></td>
         <td>string</td>

docs/docs/folder.md

@@ -9,4 +9,51 @@ In a standard scenario, a folder with default settings gets created through a `G
 
 If you need more control over folders (such as RBAC settings), it can be achieved through a `GrafanaFolder` CR.
 
+**NOTE:** When the operator starts managing a folder, it changes the folder's uid to `metadata.uid` of the respective `GrafanaFolder` CR. There's no way to change that.
+
 To view all configuration you can do within folders, look at our [API documentation](../api/#grafanafolderspec).
+
+## Folder with custom title
+
+```yaml
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaFolder
+metadata:
+  name: test-folder
+spec:
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+  # If title is not defined, the value will be taken from metadata.name
+  title: custom title
+```
+
+## 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.
+
+```yaml
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaFolder
+metadata:
+  name: test-folder
+spec:
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+  permissions: |
+    {
+      "items": [
+        {
+          "role": "Admin",
+          "permission": 4
+        },
+        {
+          "role": "Editor",
+          "permission": 2
+        }
+      ]
+    }
+```
+
+**NOTE:** When an empty JSON is passed (`permissions: "{}"`), the access is stripped for everyone except for Admin (default Grafana behaviour).

examples/folder/README.md

@@ -0,0 +1,8 @@
+---
+title: "Folder with permissions"
+linkTitle: "Folder with permissions"
+---
+
+Shows how to create a folder with custom title and [permissions](https://grafana.com/docs/grafana/v8.4/http_api/folder_permissions/#update-permissions-for-a-folder).
+
+{{< readfile file="resources.yaml" code="true" lang="yaml" >}}

examples/folder/resources.yaml

@@ -0,0 +1,44 @@
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: Grafana
+metadata:
+  name: grafana
+  labels:
+    dashboards: "grafana"
+spec:
+  config:
+    log:
+      mode: "console"
+    auth:
+      disable_login_form: "false"
+    security:
+      admin_user: root
+      admin_password: secret
+---
+apiVersion: grafana.integreatly.org/v1beta1
+kind: GrafanaFolder
+metadata:
+  name: test-folder
+spec:
+  instanceSelector:
+    matchLabels:
+      dashboards: "grafana"
+
+  # If title is not defined, the value will be taken from metadata.name
+  title: custom title
+
+  # When permissions value is empty/absent, a folder is created with default permissions
+  # When empty JSON is passed ("{}"), the access is stripped for everyone except for Admin (default Grafana behaviour)
+  permissions: |
+    {
+      "items": [
+        {
+          "role": "Admin",
+          "permission": 4
+        },
+        {
+          "role": "Editor",
+          "permission": 2
+        }
+      ]
+    }