📝 added documentation for JOBS_API version usage to ensure ACLs are working as expected (#776)

Author: renardeinside

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 [Please read through the Keep a Changelog (~5min)](https://keepachangelog.com/en/1.0.0/).
 
+## [UNRELEASED] - YYYY-MM-DD
+
+### Fixed
+
+- Added documentation for JOBS_API version usage to ensure ACLs are working as expected
+
 ## [0.8.14] - 2023-05-11
 
 ### Added

docs/features/permissions_management.md

@@ -9,6 +9,22 @@
 
 ## :material-file-check: Providing the permissions
 
+!!! warning "Enforcing Jobs API 2.1 usage to work with ACLs"
+
+    Provisioning of ACLs is only supported with Jobs API 2.1. To enforce Jobs API 2.1 usage, please use the following settings:
+
+    For local setup via `~/.databrickscfg` use the following command:
+
+    ```bash
+    databricks jobs configure --version=2.1 # add --profile=<profile-name> to enforce configuration for different profiles
+    ```
+
+    In CI pipelines, provide the following environment variable:
+
+    ```bash
+    DATABRICKS_JOBS_API_VERSION=2.1
+    ```
+
 To manage permissions provide the following payload at the workflow level:
 
 ```yaml
@@ -31,8 +47,10 @@ environments:
         tasks:
           ...
         access_control_list:
-          - user_name: "some_user@example.com"
+          - service_principal_name: "service-principal://some-sp-name" # alternatively, you can directly provide the Id string itself
             permission_level: "IS_OWNER"
+          - user_name: "some_user@example.com"
+            permission_level: "CAN_MANAGE"
           - group_name: "some-user-group"
             permission_level: "CAN_VIEW"
 ```

docs/reference/deployment.md

@@ -247,7 +247,7 @@ environments:
     workflows:
       - name: "example-workflow"
         access_control_list:
-         - user_name: "service-principal://some-service-principal-name"
+         - service_principal_name: "service-principal://some-service-principal-name"
            permission_level: "IS_OWNER"
          - user_name: "some-real-user@email.com"
            permission_level: "CAN_MANAGE"