Add docs on resource mutation and validation

README.md

@@ -27,7 +27,7 @@ It handles TLS certificates and the management of associated Secrets for secure
 Documentation on each of the resources that are validated or mutated can be found in `docs.md`. It is recommended to review the [kubernetes docs on CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) as well.
 
 Docs are added by creating a resource-specific readme in the directory of your mutator/validator (e.x. `pkg/resources/$GROUP/$GROUP_VERSION/$RESOURCE/$READABLE_RESOURCE.MD`). 
-These files should be named with a human-readable version of the resource's name.
+These files should be named with a human-readable version of the resource's name. For example, `GlobalRole.md`.
 Running `go generate` will then aggregate these into the user-facing docs in the `docs.md` file.
 
 ## Webhooks

docs.md

@@ -4,13 +4,44 @@
 
 ### Validation Checks
 
-Note: The kube-system namespace, unlike other namespaces, has a "failPolicy" of "ignore" on update calls.
+Note: The `kube-system` namespace, unlike other namespaces, has a `failPolicy` of `ignore` on update calls.
+
+#### Project annotation
+Verifies that the annotation `field.cattle.io/projectId` value can only be updated by users with the `manage-namespaces` 
+verb on the project specified in the annotation.
 
 #### PSA Label Validation
 
-Validates that users who create or edit a PSA enforcement label on a namespace have the `updatepsa` verb on `projects` in `management.cattle.io/v3`. See the [upstream docs](https://kubernetes.io/docs/concepts/security/pod-security-admission/) for more information on the effect of these labels.
+Validates that users who create or edit a PSA enforcement label on a namespace have the `updatepsa` verb on `projects` 
+in `management.cattle.io/v3`. See the [upstream docs](https://kubernetes.io/docs/concepts/security/pod-security-admission/) 
+for more information on the effect of these labels.
+
+The following labels are considered relevant for PSA enforcement: 
+- pod-security.kubernetes.io/enforce
+- pod-security.kubernetes.io/enforce-version 
+- pod-security.kubernetes.io/audit 
+- pod-security.kubernetes.io/audit-version 
+- pod-security.kubernetes.io/warn
+- pod-security.kubernetes.io/warn-version
+
+## Secret 
+
+### Validation Checks
+
+A secret cannot be deleted if its deletion request has an orphan policy,
+and the secret has roles or role bindings dependent on it.
+
+### Mutation Checks
+
+#### On create
+
+For all secrets of type `provisioning.cattle.io/cloud-credential`, 
+places a `field.cattle.io/creatorId` annotation with the name of the user as the value.
 
-The following labels are considered relevant labels for PSA enforcement: `"pod-security.kubernetes.io/enforce", "pod-security.kubernetes.io/enforce-version", "pod-security.kubernetes.io/audit", "pod-security.kubernetes.io/audit-version", "pod-security.kubernetes.io/warn", "pod-security.kubernetes.io/warn-version"`.
+#### On delete
+
+Checks if there are any RoleBindings owned by this secret which provide access to a role granting access to this secret.
+If yes, the webhook redacts the role, so that it only grants a deletion permission.
 
 # management.cattle.io/v3 
 
@@ -25,10 +56,10 @@ Users can only create/update ClusterRoleTemplateBindings which grant permissions
 #### Invalid Fields - Create
 
 Users cannot create ClusterRoleTemplateBindings which violate the following constraints:
-- Either a user subject (through "UserName" or "UserPrincipalName") or a group subject (through "GroupName" or "GroupPrincipalName") must be specified; both a user subject and group subject cannot be specified
-- A "ClusterName" must be specified
-- The roleTemplate indicated in "RoleTemplateName" must be:
-  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` apiGroup)
+- Either a user subject (through `UserName` or `UserPrincipalName`) or a group subject (through `GroupName` or `GroupPrincipalName`) must be specified; both a user subject and a group subject cannot be specified
+- `ClusterName` must be specified
+- The roleTemplate indicated in `RoleTemplateName` must be:
+  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` API group)
   - Not locked (i.e. `roleTemplate.Locked` must be `false`)
 
 #### Invalid Fields - Update
@@ -45,11 +76,22 @@ Users can update the following fields if they have not been set, but after they
 
 In addition, as in the create validation, both a user subject and a group subject cannot be specified.
 
+## Feature 
+
+### Validation Checks
+
+#### On update
+
+The desired value must not change on new spec unless it's equal to the `lockedValue` or `lockedValue` is nil.
+
 ## GlobalRole 
 
 ### Validation Checks
 
-Note: all checks are bypassed if the GlobalRole is being deleted
+Note: all checks are bypassed if the GlobalRole is being deleted.
+
+#### Invalid Fields - Create and Update
+When a GlobalRole is created or updated, the webhook checks that each rule has at least one verb.
 
 #### Escalation Prevention
 
@@ -59,7 +101,7 @@ Users can only change GlobalRoles with rights less than or equal to those they c
 
 ### Validation Checks
 
-Note: all checks are bypassed if the GlobalRoleBinding is being deleted
+Note: all checks are bypassed if the GlobalRoleBinding is being deleted.
 
 #### Escalation Prevention
 
@@ -90,10 +132,10 @@ Users can only create/update ProjectRoleTemplateBindings with rights less than o
 #### Invalid Fields - Create
 
 Users cannot create ProjectRoleTemplateBindings which violate the following constraints:
-- Either a user subject (through "UserName" or "UserPrincipalName") or a group subject (through "GroupName" or "GroupPrincipalName") must be specified; both a user subject and group subject cannot be specified
-- A "ProjectName" must be specified
-- The roleTemplate indicated in "RoleTemplateName" must be:
-  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` apiGroup)
+- Either a user subject (through `UserName` or `UserPrincipalName`) or a group subject (through `GroupName` or `GroupPrincipalName`) must be specified; both a user subject and a group subject cannot be specified
+- `ProjectName` must be specified
+- The roleTemplate indicated in `RoleTemplateName` must be:
+  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` API group)
   - Not locked (i.e. `roleTemplate.Locked` must be `false`)
 
 #### Invalid Fields - Update
@@ -102,7 +144,7 @@ Users cannot update the following fields after creation:
 - RoleTemplateName
 - ProjectName
 
-Users can update the following fields if they have not been set, but after they have been set they cannot be changed:
+Users can update the following fields if they have not been set, but after they have been set, they cannot be changed:
 - UserName
 - UserPrincipalName
 - GroupName

pkg/resources/core/v1/namespace/Namespace.md

@@ -1,10 +1,22 @@
 ## Validation Checks
 
-Note: The kube-system namespace, unlike other namespaces, has a "failPolicy" of "ignore" on update calls.
+Note: The `kube-system` namespace, unlike other namespaces, has a `failPolicy` of `ignore` on update calls.
+
+### Project annotation
+Verifies that the annotation `field.cattle.io/projectId` value can only be updated by users with the `manage-namespaces` 
+verb on the project specified in the annotation.
 
 ### PSA Label Validation
 
-Validates that users who create or edit a PSA enforcement label on a namespace have the `updatepsa` verb on `projects` in `management.cattle.io/v3`. See the [upstream docs](https://kubernetes.io/docs/concepts/security/pod-security-admission/) for more information on the effect of these labels.
+Validates that users who create or edit a PSA enforcement label on a namespace have the `updatepsa` verb on `projects` 
+in `management.cattle.io/v3`. See the [upstream docs](https://kubernetes.io/docs/concepts/security/pod-security-admission/) 
+for more information on the effect of these labels.
 
-The following labels are considered relevant labels for PSA enforcement: `"pod-security.kubernetes.io/enforce", "pod-security.kubernetes.io/enforce-version", "pod-security.kubernetes.io/audit", "pod-security.kubernetes.io/audit-version", "pod-security.kubernetes.io/warn", "pod-security.kubernetes.io/warn-version"`.
+The following labels are considered relevant for PSA enforcement: 
+- pod-security.kubernetes.io/enforce
+- pod-security.kubernetes.io/enforce-version 
+- pod-security.kubernetes.io/audit 
+- pod-security.kubernetes.io/audit-version 
+- pod-security.kubernetes.io/warn
+- pod-security.kubernetes.io/warn-version
 

pkg/resources/core/v1/secret/Secret.md

@@ -0,0 +1,16 @@
+## Validation Checks
+
+A secret cannot be deleted if its deletion request has an orphan policy,
+and the secret has roles or role bindings dependent on it.
+
+## Mutation Checks
+
+### On create
+
+For all secrets of type `provisioning.cattle.io/cloud-credential`, 
+places a `field.cattle.io/creatorId` annotation with the name of the user as the value.
+
+### On delete
+
+Checks if there are any RoleBindings owned by this secret which provide access to a role granting access to this secret.
+If yes, the webhook redacts the role, so that it only grants a deletion permission.

pkg/resources/management.cattle.io/v3/clusterroletemplatebinding/ClusterRoleTemplateBinding.md

@@ -7,10 +7,10 @@ Users can only create/update ClusterRoleTemplateBindings which grant permissions
 ### Invalid Fields - Create
 
 Users cannot create ClusterRoleTemplateBindings which violate the following constraints:
-- Either a user subject (through "UserName" or "UserPrincipalName") or a group subject (through "GroupName" or "GroupPrincipalName") must be specified; both a user subject and group subject cannot be specified
-- A "ClusterName" must be specified
-- The roleTemplate indicated in "RoleTemplateName" must be:
-  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` apiGroup)
+- Either a user subject (through `UserName` or `UserPrincipalName`) or a group subject (through `GroupName` or `GroupPrincipalName`) must be specified; both a user subject and a group subject cannot be specified
+- `ClusterName` must be specified
+- The roleTemplate indicated in `RoleTemplateName` must be:
+  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` API group)
   - Not locked (i.e. `roleTemplate.Locked` must be `false`)
 
 ### Invalid Fields - Update

pkg/resources/management.cattle.io/v3/feature/Feature.md

@@ -0,0 +1,5 @@
+## Validation Checks
+
+### On update
+
+The desired value must not change on new spec unless it's equal to the `lockedValue` or `lockedValue` is nil.

pkg/resources/management.cattle.io/v3/globalrole/GlobalRole.md

@@ -1,6 +1,9 @@
 ## Validation Checks
 
-Note: all checks are bypassed if the GlobalRole is being deleted
+Note: all checks are bypassed if the GlobalRole is being deleted.
+
+### Invalid Fields - Create and Update
+When a GlobalRole is created or updated, the webhook checks that each rule has at least one verb.
 
 ### Escalation Prevention
 

pkg/resources/management.cattle.io/v3/globalrolebinding/GlobalRoleBinding.md

@@ -1,6 +1,6 @@
 ## Validation Checks
 
-Note: all checks are bypassed if the GlobalRoleBinding is being deleted
+Note: all checks are bypassed if the GlobalRoleBinding is being deleted.
 
 ### Escalation Prevention
 

pkg/resources/management.cattle.io/v3/projectroletemplatebinding/ProjectRoleTemplateBinding.md

@@ -7,10 +7,10 @@ Users can only create/update ProjectRoleTemplateBindings with rights less than o
 ### Invalid Fields - Create
 
 Users cannot create ProjectRoleTemplateBindings which violate the following constraints:
-- Either a user subject (through "UserName" or "UserPrincipalName") or a group subject (through "GroupName" or "GroupPrincipalName") must be specified; both a user subject and group subject cannot be specified
-- A "ProjectName" must be specified
-- The roleTemplate indicated in "RoleTemplateName" must be:
-  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` apiGroup)
+- Either a user subject (through `UserName` or `UserPrincipalName`) or a group subject (through `GroupName` or `GroupPrincipalName`) must be specified; both a user subject and a group subject cannot be specified
+- `ProjectName` must be specified
+- The roleTemplate indicated in `RoleTemplateName` must be:
+  - Valid (i.e. is an existing `roleTemplate` object in the `management.cattle.io/v3` API group)
   - Not locked (i.e. `roleTemplate.Locked` must be `false`)
 
 ### Invalid Fields - Update
@@ -19,7 +19,7 @@ Users cannot update the following fields after creation:
 - RoleTemplateName
 - ProjectName
 
-Users can update the following fields if they have not been set, but after they have been set they cannot be changed:
+Users can update the following fields if they have not been set, but after they have been set, they cannot be changed:
 - UserName
 - UserPrincipalName
 - GroupName