feat: permissions (#60)

* feat: parser permissions

* chore: add tests for permissions

* feat: add permissions class

* update permissions once the dashboard has been created

* feat: add permissions schema and docs

* chore: update render.py to support permissions

* chore: add tests for permissions

Author: nyambati

README.md

@@ -8,12 +8,11 @@
 - Template panels and use them in multiple dashboards
 - Mass update many dashboards quickly and easily
 
-
 ## Install and quick start
 
 Install `grafyaml`:
 
-```
+```console
 pip3 install https://github.com/deliveryhero/grafyaml/archive/master.zip
 ```
 
@@ -33,11 +32,41 @@ dashboard:
 
 Sync it to Grafana:
 
-```
+```console
 export GRAFANA_API_KEY="API_KEY_HERE"
 grafyaml --grafana-url https://my-grafana-host.domain.com update my-example-dashboard.yaml
 ```
 
+## Permissions
+
+Grafyaml supports permissions for dashboards. The permissions are defined in the same file as dashboard under `permissions` root key. The permissions are applied to the dashboard as a whole, not to individual panels.
+
+```yaml
+
+permissions:
+  strategy: replace # merge or overwrite
+  grants:
+    # subject:identifier:permission
+    - team:admins:admin
+dashboard:
+  title: My Dashboard
+  panels:
+  - title: Container metrics
+    panels:
+    - title: Container CPU usage
+      targets:
+      - expr: rate(container_cpu_user_seconds_total[30s]) * 100
+      type: timeseries
+```
+
+Grants are structured as a triplet: `subject:identifier:permission`.
+
+- Subject: Specifies the entity to which the permission applies. Valid subjects include team, user, role, or serviceAccount. (serviceAccount is not yet supported)
+- Identifier: The specific name or unique identifier of the subject.
+- Permission: Defines the level of access granted. Permissible values are view, edit, admin, or none.
+
+Example: To grant edit permission for the developers team on a resource named my-dashboard, the grant would be defined as team:developers:edit.
+
 ## More examples
 
 - [examples/basic](examples/basic): A very basic example with a single dashboard

examples/advanced/apps.yaml

@@ -1,4 +1,8 @@
 app1:
+  permissions:
+    strategy: merge
+    grants:
+      - team:admins:admin
   templating:
     - name: dynamodb_name
       query: dynamodb_name

examples/advanced/render.py

@@ -274,7 +274,7 @@ def write_dashboard_file(
     try:
         with open(output_file_path, "w") as f:
             # Use default_flow_style=False for a more human-readable output
-            yaml.dump({"dashboard": dashboard_data}, f, default_flow_style=False)
+            yaml.dump(dashboard_data, f, default_flow_style=False)
         logging.info(f"Successfully generated '{output_file_path}'")
     except (IOError, yaml.YAMLError) as e:
         logging.error(f"Error writing output file '{output_file_path}': {e}")
@@ -364,21 +364,25 @@ def main():
 
         # --- Override Tags if specified ---
         app_tags = app_config.get("tags")
-        if app_tags is not None:  # Allows setting tags to None/empty list in input
-            if (
-                isinstance(app_tags, list) or app_tags is None
-            ):  # Ensure it's a list or None
-                dashboard_data["tags"] = app_tags
-                logging.debug(f"Overrode tags for '{app_name}': {app_tags}")
-            else:
-                logging.warning(
-                    f"App '{app_name}' has invalid 'tags' structure: {app_tags}. "
-                    f"Expected list or null. Skipping tag override."
-                )
+        if app_tags and isinstance(app_tags, list):
+            dashboard_data["tags"] = app_tags
+            logging.debug(f"Overrode tags for '{app_name}': {app_tags}")
+        else:
+            logging.warning(
+                f"App '{app_name}' has invalid 'tags' structure: {app_tags}. "
+                f"Expected list or null. Skipping tag override."
+            )
+
+        if "permissions" in app_config:
+            dashboard_full_structure["permissions"] = app_config.get("permissions", [])
 
         # --- Write Output File ---
         # Pass the dictionary that represents the content *under* the top-level 'dashboard' key
-        write_dashboard_file(app_name, output_dir, dashboard_data)
+        write_dashboard_file(
+            app_name=app_name,
+            output_dir=output_dir,
+            dashboard_data=dashboard_full_structure,
+        )
 
     logging.info("Dashboard generation process completed.")
 

examples/advanced/rendered_dashboards/.gitkeep

@@ -0,0 +1,56 @@
+permissions:
+  strategy: replace # merge or overwrite
+  grants:
+  # subject:identifier:permission
+  - team:admins:admin
+  - user:admin@localhost:edit
+  - role:viewer:view
+  - serviceAccount:grafana:admin
+
+dashboard:
+  editable: false
+  tags:
+  - grafyaml
+  - example
+  - basic
+  time:
+    from: now-30m
+    to: now
+  timezone: browser
+  title: Host metrics
+  rows:
+  - showTitle: true
+    title: CPU and memory usage
+    collapse: false
+    height: 500px
+    panels:
+    - fill: 8
+      legend:
+        alignAsTable: true
+        current: true
+        show: true
+        sort: current
+        sortDesc: true
+        values: true
+      span: 4
+      stack: true
+      targets:
+      - expr: 100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) * on (instance) group_left (nodename) node_uname_info
+        legendFormat: '{{ nodename }}'
+      title: CPU usage
+      type: graph
+    - fill: 8
+      legend:
+        alignAsTable: true
+        current: true
+        show: true
+        sort: current
+        sortDesc: true
+        values: true
+      span: 4
+      stack: true
+      targets:
+      - expr: 100 * (avg by (instance) (1 - ((avg_over_time(node_memory_MemFree_bytes{}[5m]) + avg_over_time(node_memory_Cached_bytes{}[5m]) + avg_over_time(node_memory_Buffers_bytes{}[5m])) / avg_over_time(node_memory_MemTotal_bytes{}[5m])))) * on (instance) group_left (nodename) node_uname_info
+        legendFormat: '{{ nodename }}'
+      title: Memory usage
+      type: graph

examples/basic/dashboard_with_permissions.yaml

@@ -96,9 +96,15 @@ def _update_dashboard(self, data):
         for name in data:
             data, md5 = self.parser.get_dashboard(name)
             if self.cache.has_changed(name, md5):
-                self.grafana.dashboard.create(
+                permissions = self.parser.get_permissions(name)
+                uid = self.grafana.dashboard.create(
                     data=data, overwrite=self.overwrite, folder_id=self.folder_id
                 )
+                if uid and permissions:
+                    LOG.debug("Updating permissions for dashboard UID %s", uid)
+                    self.grafana.permissions.update(
+                        dashboard_uid=uid, permissions=permissions
+                    )
                 self.cache.set(name, md5)
             else:
                 LOG.debug("'%s' has not changed" % name)

grafana_dashboards/builder.py

@@ -147,7 +147,7 @@ def update(self):
         builder = Builder(self.config)
         try:
             builder.update(self.args.path)
-        except ValueError as e:
+        except Exception as e:
             LOG.info(f"Error: {e}")
             sys.exit(1)
 

grafana_dashboards/cmd.py

@@ -16,6 +16,7 @@
 
 from grafana_dashboards.grafana.dashboard import Dashboard
 from grafana_dashboards.grafana.datasource import Datasource
+from grafana_dashboards.grafana.permissions import Permissions
 
 
 class Grafana(object):
@@ -45,3 +46,4 @@ def __init__(self, url, key=None):
 
         self.dashboard = Dashboard(self.server, session)
         self.datasource = Datasource(self.server, session)
+        self.permissions = Permissions(self.server, session)

grafana_dashboards/grafana/__init__.py

@@ -24,7 +24,7 @@ def __init__(self, base_url: str, session):
         self.search_url = utils.urljoin(base_url, "api/search?type=dash-db")
         self.session = session
 
-    def create(self, data: Dict, overwrite: bool = False, folder_id: int = 0) -> None:
+    def create(self, data: Dict, overwrite: bool = False, folder_id: int = 0) -> str:
         """Create a new dashboard
 
         :param data: Dashboard model
@@ -63,6 +63,8 @@ def create(self, data: Dict, overwrite: bool = False, folder_id: int = 0) -> Non
         res = self.session.post(self.db_url, data=json.dumps(dashboard))
         res.raise_for_status()
 
+        return res.json().get("uid")
+
     def delete(self, name):
         """Delete a dashboard
 
@@ -128,6 +130,10 @@ def find_dashboards_by_title(self, title: str, folder_id: int = 0) -> List[Dict]
         """
         dashboards = self.search_dashboards(title)
 
+        # If folder_id is 0, return all dashboards
+        if folder_id == 0:
+            return dashboards
+
         dashboards = list(
             filter(
                 lambda x: x.get("title") == title and x.get("folderId") == folder_id,