Document unrestricted application credential requirement for Magnum clusters

docs/SUMMARY.md

@@ -2,6 +2,8 @@
     - [Getting Started](user/getting-started.md)
     - user/*.md
 - Administrator Guide
-    - admin/*.md
+    - [Introduction](admin/intro.md)
+    - [Authentication](admin/authentication.md)
+    - [Troubleshooting](admin/troubleshooting.md)
 - Developer Guide
     - developer/*.md

docs/admin/authentication.md

@@ -0,0 +1,77 @@
+# Authentication
+
+## Application Credentials
+
+When using the Cluster API driver for Magnum, OpenStack application credentials
+are used for authentication between the cluster and the OpenStack API. It is
+important to understand the requirements for creating these application
+credentials to avoid common issues.
+
+### Unrestricted Application Credentials
+
+**Important**: Application credentials used with Magnum clusters **must** be
+created with the `--unrestricted` flag to function properly.
+
+When creating application credentials without the `--unrestricted` option, you
+may encounter errors such as:
+
+```
+Failed to create trustee or trust for Cluster
+```
+
+This occurs because non-unrestricted application credentials have limited
+permissions that prevent them from creating the necessary trust relationships
+that Magnum requires for cluster management operations.
+
+### Creating Application Credentials
+
+To create an application credential that will work with Magnum clusters, use
+the following command:
+
+```bash
+openstack application credential create --unrestricted <credential-name>
+```
+
+For example:
+
+```bash
+openstack application credential create --unrestricted magnum-cluster-api
+```
+
+This will output the application credential ID and secret that you can then
+use to configure authentication for your Magnum clusters.
+
+### Why Unrestricted is Required
+
+The `--unrestricted` flag allows the application credential to:
+
+- Create and manage trust relationships with Keystone
+- Create trustee users for cluster operations
+- Perform all necessary OpenStack API operations required for cluster
+  lifecycle management
+
+Without these permissions, the Cluster API driver for Magnum cannot properly
+manage the cluster's integration with OpenStack services.
+
+### Security Considerations
+
+While using unrestricted application credentials provides the necessary
+permissions for Magnum operations, consider the following security best
+practices:
+
+- Limit the scope of the application credential to the specific project
+  where clusters will be created
+- Regularly rotate application credentials
+- Monitor the usage of application credentials
+- Remove unused application credentials promptly
+
+### Troubleshooting
+
+If you encounter trust or trustee creation errors with existing clusters that
+were created with restricted application credentials, you will need to:
+
+1. Create a new unrestricted application credential
+2. Update the cluster's cloud configuration to use the new credentials
+
+For detailed steps on updating cluster credentials, see the
+[Troubleshooting](troubleshooting.md) section.

docs/admin/troubleshooting.md

@@ -143,11 +143,17 @@ go into the database and update the `id` of the new project to match the
 7.  Create a new set of application credentials and update the existing
     `cloud-config` secret for the cluster
 
+    !!! warning
+
+        Make sure to use the `--unrestricted` flag when creating the application
+        credential. For more information about application credential requirements,
+        see the [Authentication](authentication.md) documentation.
+
     ```
     $ export CAPI_CLUSTER_NAME=$(openstack coe cluster show tst1-useg-k8s-1 -f value -c stack_id)
     $ export EXISTING_APPCRED_ID=$(kubectl -n magnum-system get secret/$CAPI_CLUSTER_NAME-cloud-config -ojson | jq -r '.data."clouds.yaml"' | base64 --decode | grep application_credential_id | awk '{print $2}')
     $ export EXISTING_APPCRED_SECRET=$(kubectl -n magnum-system get secret/$CAPI_CLUSTER_NAME-cloud-config -ojson | jq -r '.data."clouds.yaml"' | base64 --decode | grep application_credential_secret | awk '{print $2}')
-    $ export NEW_APPCRED_ID=$(openstack application credential create --secret $EXISTING_APPCRED_SECRET $CAPI_CLUSTER_NAME-cleanup -f value -c id)
+    $ export NEW_APPCRED_ID=$(openstack application credential create --unrestricted --secret $EXISTING_APPCRED_SECRET $CAPI_CLUSTER_NAME-cleanup -f value -c id)
     $  > /tmp/clouds.yaml
     $ kubectl -n magnum-system patch secret/$CAPI_CLUSTER_NAME-cloud-config -p '{"data":{"clouds.yaml":"'$(kubectl -n magnum-system get secret/$CAPI_CLUSTER_NAME-cloud-config -ojson | jq -r '.data."clouds.yaml"' | base64 --decode | sed "s/$EXISTING_APPCRED_ID/$NEW_APPCRED_ID/" | base64 --wrap=0)'"}}'
     ```
@@ -165,3 +171,35 @@ Once the cluster is gone, you can clean up the project:
 $ unset OS_PROJECT_ID
 $ openstack project delete $CURRENT_PROJECT_ID
 ```
+
+## Failed to create trustee or trust for Cluster
+
+If you encounter an error message similar to "Failed to create trustee or trust
+for Cluster" when creating or managing clusters, this is typically caused by
+using application credentials that were not created with the `--unrestricted`
+flag.
+
+### Root Cause
+
+Non-unrestricted application credentials have limited permissions that prevent
+them from creating the necessary trust relationships that Magnum requires for
+cluster management operations.
+
+### Solution
+
+Create a new application credential with the `--unrestricted` flag:
+
+```bash
+openstack application credential create --unrestricted <credential-name>
+```
+
+Then update your cluster configuration to use the new credentials. For detailed
+information about application credential requirements, see the
+[Authentication](authentication.md) documentation.
+
+### Prevention
+
+Always use the `--unrestricted` flag when creating application credentials for
+use with Magnum clusters. This ensures that the credentials have the necessary
+permissions to create trust relationships and manage cluster operations
+properly.