docs: principal ID and rules in readme (#222)

## Issue
There wasn't much guidance on how to specify the correct `principalId`
in the spec for RBAC rule. Azure is complex when it comes to this. There
are four GUIDs users see in the Azure Portal, where three of them are
unique to each Entra ID identify they create. We need to guide them.

## Description
Clarifies how principalID works in the docs. This includes the docstring
generated by kubebuilder and some additions to the readme that go into
detail about it, including screenshots.

Because there is now a readme section on each rule in detail, there is a
part where it describes the community gallery image rule too. But there
isn't much to say about that rule right now.

Also removes some unneeded `MaxLength` annotations (because they aren't
used in other kubebuilder validations where long strings are
problematic).

Note that unlike in the PR
#219, the
`ActionStr` type and its `MaxLength` annotation must remain. This is
because the RBAC rule forbids wildcards in specified permissions and
kubebuilder validation here validates this, which is a type of
kubebuilder validation where long strings are problematic. We need
`ActionStr` because we need to place the `MaxLength` annotation on the
list of actions in a way where it is applied to each string in a slice
of strings, and this is the recommended way to do that right now.

---------

Signed-off-by: Matt Welke <matt.welke@spectrocloud.com>

Author: mattwelke

README.md

@@ -20,6 +20,34 @@ Each `AzureValidator` CR is (re)-processed every two minutes to continuously ens
 
 See the [samples](https://github.com/validator-labs/validator-plugin-azure/tree/main/config/samples) directory for example `AzureValidator` configurations. Some samples require you to add data to the rules configured in them such as the Azure subscription to use.
 
+### Rules
+
+#### RBAC rule
+
+This rule compares the Azure RBAC permissions associated with a [security principal](https://learn.microsoft.com/en-us/azure/role-based-access-control/overview#security-principal) against an expected permission set.
+
+It checks if an Azure security principal (e.g., users, service principals) has the required Azure RBAC permissions. In Azure RBAC, permissions are applied to principals by a role assignment being created that links a role (which can be a BuiltInRole or a CustomRole) to the principal at a particular scope. API operations at that scope or lower (e.g. operations against a subscription or against a resource group within the subscription) are permitted but operations outside of that scope are not.
+
+Validation is successful if the principal has the necessary permissions, either from one role assignment or a combination of role assignments.
+
+The list of permissions defined in the spec cannot have an action or data action with a wildcard. However, the roles that provide the permissions (via role assignments) may have wildcards in their actions and data actions.
+
+Note that you must use the correct ID when configuring the `principalId` in the spec for the principal. For a service principal, this is the "application object ID" found in the Azure portal under Entra ID > application registration > managed application page > "object ID". Note that this is different from the tenant ID, client ID, and object ID of the application registration.
+
+Service principal example:
+
+![3](https://github.com/user-attachments/assets/59b54214-10f6-4c7c-9ec5-eeeadfada35e)
+
+![4](https://github.com/user-attachments/assets/560acda5-2515-4c87-a1e3-1f400492f4ad)
+
+See [azurevalidator-rbac-one-permission-set-all-actions-permitted-by-one-role.yaml](config/samples/azurevalidator-rbac-one-permission-set-all-actions-permitted-by-one-role.yaml`) for an example rule spec.
+
+#### Community image gallery rule
+
+This rule verifies that images in [community image galleries](https://learn.microsoft.com/en-us/azure/virtual-machines/share-gallery-community) exist.
+
+See [azurevalidator-communitygalleryimages-one-image.yaml](config/samples/azurevalidator-communitygalleryimages-one-image.yaml) for an example rule spec.
+
 ## Authn & Authz
 
 Authentication details for the Azure validator controller are provided within each `AzureValidator` custom resource. Azure authentication can be configured either implicitly or explicitly:

api/v1alpha1/azurevalidator_types.go

@@ -53,7 +53,11 @@ type RBACRule struct {
 	//+kubebuilder:validation:XValidation:message="Each permission set must have Actions, DataActions, or both defined",rule="self.all(item, size(item.actions) > 0 || size(item.dataActions) > 0)"
 	Permissions []PermissionSet `json:"permissionSets" yaml:"permissionSets"`
 	// The principal being validated. This can be any type of principal - Device, ForeignGroup,
-	// Group, ServicePrincipal, or User.
+	// Group, ServicePrincipal, or User. If using a service principal, this is the "application
+	// object ID". In the Azure portal, this can be found by navigating to Entra ID, selecting the
+	// application registration of the service principal, navigating from that page to the managed
+	// application page, and copying the "object ID". This ID is different from the tenant ID,
+	// client ID, and object ID of the application registration.
 	PrincipalID string `json:"principalId" yaml:"principalId"`
 }
 
@@ -77,10 +81,8 @@ type CommunityGalleryImageRule struct {
 // CommunityGallery is a community gallery in a particular location.
 type CommunityGallery struct {
 	// Location is the location of the community gallery (e.g. "westus").
-	// +kubebuilder:validation:MaxLength=50
 	Location string `json:"location" yaml:"location"`
 	// Name is the name of the community gallery.
-	// +kubebuilder:validation:MaxLength=200
 	Name string `json:"name" yaml:"name"`
 }
 

chart/validator-plugin-azure/crds/validation.spectrocloud.labs_azurevalidators.yaml

@@ -72,11 +72,9 @@ spec:
                         location:
                           description: Location is the location of the community gallery
                             (e.g. "westus").
-                          maxLength: 50
                           type: string
                         name:
                           description: Name is the name of the community gallery.
-                          maxLength: 200
                           type: string
                       required:
                       - location
@@ -183,7 +181,11 @@ spec:
                     principalId:
                       description: |-
                         The principal being validated. This can be any type of principal - Device, ForeignGroup,
-                        Group, ServicePrincipal, or User.
+                        Group, ServicePrincipal, or User. If using a service principal, this is the "application
+                        object ID". In the Azure portal, this can be found by navigating to Entra ID, selecting the
+                        application registration of the service principal, navigating from that page to the managed
+                        application page, and copying the "object ID". This ID is different from the tenant ID,
+                        client ID, and object ID of the application registration.
                       type: string
                   required:
                   - name

config/crd/bases/validation.spectrocloud.labs_azurevalidators.yaml

@@ -72,11 +72,9 @@ spec:
                         location:
                           description: Location is the location of the community gallery
                             (e.g. "westus").
-                          maxLength: 50
                           type: string
                         name:
                           description: Name is the name of the community gallery.
-                          maxLength: 200
                           type: string
                       required:
                       - location
@@ -183,7 +181,11 @@ spec:
                     principalId:
                       description: |-
                         The principal being validated. This can be any type of principal - Device, ForeignGroup,
-                        Group, ServicePrincipal, or User.
+                        Group, ServicePrincipal, or User. If using a service principal, this is the "application
+                        object ID". In the Azure portal, this can be found by navigating to Entra ID, selecting the
+                        application registration of the service principal, navigating from that page to the managed
+                        application page, and copying the "object ID". This ID is different from the tenant ID,
+                        client ID, and object ID of the application registration.
                       type: string
                   required:
                   - name