docs: add org level permissions example

aiven · Dec 9, 2024 · 848d2e3 · 848d2e3
1 parent 6086287
commit 848d2e3
Show file tree

Hide file tree

Showing 4 changed files with 103 additions and 16 deletions.
diff --git a/docs/resources/organization_permission.md b/docs/resources/organization_permission.md
@@ -1,19 +1,23 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "aiven_organization_permission Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  Grants roles and permissions https://aiven.io/docs/platform/concepts/permissions to a principal for a resource.
+  Grants roles and permissions https://aiven.io/docs/platform/concepts/permissions to a principal for a resource. Permissions can be granted at the organization, organizational unit, and project level.
 ---
-
 # aiven_organization_permission (Resource)
 
-Grants [roles and permissions](https://aiven.io/docs/platform/concepts/permissions) to a principal for a resource.
+Grants [roles and permissions](https://aiven.io/docs/platform/concepts/permissions) to a principal for a resource. Permissions can be granted at the organization, organizational unit, and project level.
 
-## Example Usage
+Permissions can be granted at the organization, organizational unit, and project level.
+
+~> **Important**
+    Organization and unit permissions are not yet fully supported.
 
+## Example Usage
 ```terraform
-resource "aiven_organization_permission" "example_permissions" {
+# Project-level permissions
+# Grant access to a specific project
+resource "aiven_organization_permission" "example_project_permissions" {
   organization_id = data.aiven_organization.main.id
   resource_id     = data.aiven_project.example_project.id
   resource_type   = "project"
@@ -26,19 +30,48 @@ resource "aiven_organization_permission" "example_permissions" {
     principal_id   = "u123a456b7890c"
     principal_type = "user"
   }
-  # Grant write project integrations and read project networking permissions, and the developer role to a group
+  # Grant write project integrations, and the developer role to a group
   permissions {
     permissions = [
       "project:integrations:write",
-      "project:networking:read",
       "developer"
     ]
     principal_id   = data.aiven_organization_user_group.example_group.group_id
     principal_type = "user_group"
   }
 }
-```
 
+# Organization-level permissions
+resource "aiven_organization_permission" "example_org_permissions" {
+  organization_id = data.aiven_organization.main.id
+  resource_id     = data.aiven_organization.main.id
+  resource_type   = "organization"
+
+  # Grant access to manage application users and 
+  # view all project audit logs to a user
+  permissions {
+    permissions = [
+      "organization:app_users:write",
+      "project:audit_logs:read"
+    ]
+    principal_id   = "u123a456b7890c" 
+    principal_type = "user"
+  }
+
+  # Grant access to users, groups, domains, and
+  # identity providers to a group
+  permissions {
+    permissions = [
+      "organization:users:write",
+      "organization:groups:write",
+      "organization:domains:write",
+      "organization:idps:write"
+    ]
+    principal_id   = aiven_organization_user_group.example_group.group_id
+    principal_type = "user_group"
+  }
+}
+```
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
@@ -82,11 +115,8 @@ Optional:
 - `delete` (String)
 - `read` (String)
 - `update` (String)
-
 ## Import
-
 Import is supported using the following syntax:
-
 ```shell
 terraform import aiven_organization_permission.operator ORGANIZATION_ID/ID
 ```
diff --git a/examples/resources/aiven_organization_permission/resource.tf b/examples/resources/aiven_organization_permission/resource.tf
@@ -1,4 +1,6 @@
-resource "aiven_organization_permission" "example_permissions" {
+# Project-level permissions
+# Grant access to a specific project
+resource "aiven_organization_permission" "example_project_permissions" {
   organization_id = data.aiven_organization.main.id
   resource_id     = data.aiven_project.example_project.id
   resource_type   = "project"
@@ -11,14 +13,44 @@ resource "aiven_organization_permission" "example_permissions" {
     principal_id   = "u123a456b7890c"
     principal_type = "user"
   }
-  # Grant write project integrations and read project networking permissions, and the developer role to a group
+  # Grant write project integrations, and the developer role to a group
   permissions {
     permissions = [
       "project:integrations:write",
-      "project:networking:read",
       "developer"
     ]
     principal_id   = data.aiven_organization_user_group.example_group.group_id
     principal_type = "user_group"
   }
 }
+
+# Organization-level permissions
+resource "aiven_organization_permission" "example_org_permissions" {
+  organization_id = data.aiven_organization.main.id
+  resource_id     = data.aiven_organization.main.id
+  resource_type   = "organization"
+
+  # Grant access to manage application users and 
+  # view all project audit logs to a user
+  permissions {
+    permissions = [
+      "organization:app_users:write",
+      "project:audit_logs:read"
+    ]
+    principal_id   = "u123a456b7890c" 
+    principal_type = "user"
+  }
+
+  # Grant access to users, groups, domains, and
+  # identity providers to a group
+  permissions {
+    permissions = [
+      "organization:users:write",
+      "organization:groups:write",
+      "organization:domains:write",
+      "organization:idps:write"
+    ]
+    principal_id   = aiven_organization_user_group.example_group.group_id
+    principal_type = "user_group"
+  }
+}
diff --git a/internal/sdkprovider/service/organization/organization_permission.go b/internal/sdkprovider/service/organization/organization_permission.go
@@ -72,7 +72,7 @@ var permissionFields = map[string]*schema.Schema{
 
 func ResourceOrganizationalPermission() *schema.Resource {
 	return &schema.Resource{
-		Description:   "Grants [roles and permissions](https://aiven.io/docs/platform/concepts/permissions) to a principal for a resource.",
+		Description:   "Grants [roles and permissions](https://aiven.io/docs/platform/concepts/permissions) to a principal for a resource. Permissions can be granted at the organization, organizational unit, and project level.",
 		CreateContext: common.WithGenClient(resourceOrganizationalPermissionUpsert),
 		ReadContext:   common.WithGenClient(resourceOrganizationalPermissionRead),
 		UpdateContext: common.WithGenClient(resourceOrganizationalPermissionUpsert),

diff --git a/templates/resources/organization_permission.md.tmpl b/templates/resources/organization_permission.md.tmpl
@@ -0,0 +1,25 @@
+---
+page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+# {{.Name}} ({{.Type}})
+
+{{ .Description | trimspace }}
+
+Permissions can be granted at the organization, organizational unit, and project level.
+
+~> **Important**
+    Organization and unit permissions are not yet fully supported.
+
+{{ if .HasExample -}}
+## Example Usage
+{{ tffile .ExampleFile }}
+{{- end }}
+{{ .SchemaMarkdown | trimspace }}
+{{ if .HasImport -}}
+## Import
+Import is supported using the following syntax:
+{{ codefile "shell" .ImportFile }}
+{{- end }}