Merge pull request #766 from aiven/rriski-clickhousegrant-docs

feat(clickhousegrant): improve docs
aiven · Jun 25, 2024 · bac4b9b · bac4b9b
2 parents 0839a6c + eeb6008
commit bac4b9b
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 23 deletions.
diff --git a/api/v1alpha1/clickhousegrant_types.go b/api/v1alpha1/clickhousegrant_types.go
@@ -35,11 +35,11 @@ type PrivilegeGrant struct {
 	Privileges []string `json:"privileges"`
 	// The database that the grant refers to.
 	Database string `json:"database"`
-	// The tables that the grant refers to.
+	// The tables that the grant refers to. To grant a privilege on all tables in a database, omit this field instead of writing `table: "*"`.
 	Table string `json:"table,omitempty"`
 	// The column that the grant refers to.
 	Columns []string `json:"columns,omitempty"`
-	// If true, then the grantee (user or role) get the permission to execute the `GRANT`` query.
+	// If true, then the grantee (user or role) get the permission to execute the `GRANT` query.
 	// Users can grant privileges of the same scope they have and less.
 	// See https://clickhouse.com/docs/en/sql-reference/statements/grant#granting-privilege-syntax
 	WithGrantOption bool `json:"withGrantOption,omitempty"`
@@ -63,9 +63,9 @@ type RoleGrant struct {
 type ClickhouseGrantSpec struct {
 	ServiceDependant `json:",inline,omitempty"`
 
-	// Configuration to grant a privilege.
+	// Configuration to grant a privilege. Privileges not in the manifest are revoked. Existing privileges are retained; new ones are granted.
 	PrivilegeGrants []PrivilegeGrant `json:"privilegeGrants,omitempty"`
-	// Configuration to grant a role.
+	// Configuration to grant a role. Role grants not in the manifest are revoked. Existing role grants are retained; new ones are granted.
 	RoleGrants []RoleGrant `json:"roleGrants,omitempty"`
 }
 

diff --git a/charts/aiven-operator-crds/templates/aiven.io_clickhousegrants.yaml b/charts/aiven-operator-crds/templates/aiven.io_clickhousegrants.yaml
@@ -60,7 +60,10 @@ spec:
                     - name
                   type: object
                 privilegeGrants:
-                  description: Configuration to grant a privilege.
+                  description:
+                    Configuration to grant a privilege. Privileges not in
+                    the manifest are revoked. Existing privileges are retained; new
+                    ones are granted.
                   items:
                     description: |-
                       PrivilegeGrant represents the privileges to be granted to users or roles.
@@ -98,11 +101,14 @@ spec:
                           type: string
                         type: array
                       table:
-                        description: The tables that the grant refers to.
+                        description:
+                          'The tables that the grant refers to. To grant
+                          a privilege on all tables in a database, omit this field instead
+                          of writing `table: "*"`.'
                         type: string
                       withGrantOption:
                         description: |-
-                          If true, then the grantee (user or role) get the permission to execute the `GRANT`` query.
+                          If true, then the grantee (user or role) get the permission to execute the `GRANT` query.
                           Users can grant privileges of the same scope they have and less.
                           See https://clickhouse.com/docs/en/sql-reference/statements/grant#granting-privilege-syntax
                         type: boolean
@@ -124,7 +130,10 @@ spec:
                     - message: Value is immutable
                       rule: self == oldSelf
                 roleGrants:
-                  description: Configuration to grant a role.
+                  description:
+                    Configuration to grant a role. Role grants not in the
+                    manifest are revoked. Existing role grants are retained; new ones
+                    are granted.
                   items:
                     description: |-
                       RoleGrant represents the roles to be assigned to users or roles.

diff --git a/config/crd/bases/aiven.io_clickhousegrants.yaml b/config/crd/bases/aiven.io_clickhousegrants.yaml
@@ -60,7 +60,10 @@ spec:
                     - name
                   type: object
                 privilegeGrants:
-                  description: Configuration to grant a privilege.
+                  description:
+                    Configuration to grant a privilege. Privileges not in
+                    the manifest are revoked. Existing privileges are retained; new
+                    ones are granted.
                   items:
                     description: |-
                       PrivilegeGrant represents the privileges to be granted to users or roles.
@@ -98,11 +101,14 @@ spec:
                           type: string
                         type: array
                       table:
-                        description: The tables that the grant refers to.
+                        description:
+                          'The tables that the grant refers to. To grant
+                          a privilege on all tables in a database, omit this field instead
+                          of writing `table: "*"`.'
                         type: string
                       withGrantOption:
                         description: |-
-                          If true, then the grantee (user or role) get the permission to execute the `GRANT`` query.
+                          If true, then the grantee (user or role) get the permission to execute the `GRANT` query.
                           Users can grant privileges of the same scope they have and less.
                           See https://clickhouse.com/docs/en/sql-reference/statements/grant#granting-privilege-syntax
                         type: boolean
@@ -124,7 +130,10 @@ spec:
                     - message: Value is immutable
                       rule: self == oldSelf
                 roleGrants:
-                  description: Configuration to grant a role.
+                  description:
+                    Configuration to grant a role. Role grants not in the
+                    manifest are revoked. Existing role grants are retained; new ones
+                    are granted.
                   items:
                     description: |-
                       RoleGrant represents the roles to be assigned to users or roles.

diff --git a/docs/docs/api-reference/clickhousedatabase.md b/docs/docs/api-reference/clickhousedatabase.md
@@ -17,7 +17,7 @@ title: "ClickhouseDatabase"
 
       project: my-aiven-project
       serviceName: my-clickhouse
-      databaseName: my-db
+      databaseName: example-db
     ```
 
 ## ClickhouseDatabase {: #ClickhouseDatabase }

diff --git a/docs/docs/api-reference/clickhousegrant.md b/docs/docs/api-reference/clickhousegrant.md
@@ -26,8 +26,8 @@ title: "ClickhouseGrant"
             - SELECT
             - INSERT
           database: my-db
-          # If table is not specified, the privileges are granted on all tables in the database
-          # If columns is not specified, the privileges are granted on all columns in the table
+          # If table is omitted, the privileges are granted on all tables in the database
+          # If columns is omitted, the privileges are granted on all columns in the table
         - grantees:
             - role: my-role
           privileges:
@@ -71,8 +71,8 @@ ClickhouseGrantSpec defines the desired state of ClickhouseGrant.
 **Optional**
 
 - [`authSecretRef`](#spec.authSecretRef-property){: name='spec.authSecretRef-property'} (object). Authentication reference to Aiven token in a secret. See below for [nested schema](#spec.authSecretRef).
-- [`privilegeGrants`](#spec.privilegeGrants-property){: name='spec.privilegeGrants-property'} (array of objects). Configuration to grant a privilege. See below for [nested schema](#spec.privilegeGrants).
-- [`roleGrants`](#spec.roleGrants-property){: name='spec.roleGrants-property'} (array of objects). Configuration to grant a role. See below for [nested schema](#spec.roleGrants).
+- [`privilegeGrants`](#spec.privilegeGrants-property){: name='spec.privilegeGrants-property'} (array of objects). Configuration to grant a privilege. Privileges not in the manifest are revoked. Existing privileges are retained; new ones are granted. See below for [nested schema](#spec.privilegeGrants).
+- [`roleGrants`](#spec.roleGrants-property){: name='spec.roleGrants-property'} (array of objects). Configuration to grant a role. Role grants not in the manifest are revoked. Existing role grants are retained; new ones are granted. See below for [nested schema](#spec.roleGrants).
 
 ## authSecretRef {: #spec.authSecretRef }
 
@@ -89,7 +89,7 @@ Authentication reference to Aiven token in a secret.
 
 _Appears on [`spec`](#spec)._
 
-Configuration to grant a privilege.
+Configuration to grant a privilege. Privileges not in the manifest are revoked. Existing privileges are retained; new ones are granted.
 
 **Required**
 
@@ -101,8 +101,8 @@ See https://clickhouse.com/docs/en/sql-reference/statements/grant#assigning-role
 **Optional**
 
 - [`columns`](#spec.privilegeGrants.columns-property){: name='spec.privilegeGrants.columns-property'} (array of strings). The column that the grant refers to.
-- [`table`](#spec.privilegeGrants.table-property){: name='spec.privilegeGrants.table-property'} (string). The tables that the grant refers to.
-- [`withGrantOption`](#spec.privilegeGrants.withGrantOption-property){: name='spec.privilegeGrants.withGrantOption-property'} (boolean). If true, then the grantee (user or role) get the permission to execute the `GRANT`` query.
+- [`table`](#spec.privilegeGrants.table-property){: name='spec.privilegeGrants.table-property'} (string). The tables that the grant refers to. To grant a privilege on all tables in a database, omit this field instead of writing `table: "*"`.
+- [`withGrantOption`](#spec.privilegeGrants.withGrantOption-property){: name='spec.privilegeGrants.withGrantOption-property'} (boolean). If true, then the grantee (user or role) get the permission to execute the `GRANT` query.
 Users can grant privileges of the same scope they have and less.
 See https://clickhouse.com/docs/en/sql-reference/statements/grant#granting-privilege-syntax.
 
@@ -121,7 +121,7 @@ List of grantees (users or roles) to grant the privilege to.
 
 _Appears on [`spec`](#spec)._
 
-Configuration to grant a role.
+Configuration to grant a role. Role grants not in the manifest are revoked. Existing role grants are retained; new ones are granted.
 
 **Required**
 

diff --git a/docs/docs/api-reference/examples/clickhousegrant.yaml b/docs/docs/api-reference/examples/clickhousegrant.yaml
@@ -19,8 +19,8 @@ spec:
         - SELECT
         - INSERT
       database: my-db
-      # If table is not specified, the privileges are granted on all tables in the database
-      # If columns is not specified, the privileges are granted on all columns in the table
+      # If table is omitted, the privileges are granted on all tables in the database
+      # If columns is omitted, the privileges are granted on all columns in the table
     - grantees:
         - role: my-role
       privileges: