From a0d3efa7d5f767f3649c69545cc9badb49a90990 Mon Sep 17 00:00:00 2001
From: Kevin Carter <kevin.carter@rackspace.com>
Date: Mon, 15 Apr 2024 14:05:19 -0500
Subject: [PATCH] feat: add Readonly user documentation

This change will permit readonly access to a given project/domain.

Signed-off-by: Kevin Carter <kevin.carter@rackspace.com>
---
 docs/openstack-keystone-federation.md | 53 +--------------------------
 docs/openstack-keystone-readonly.md   | 49 +++++++++++++++++++++++++
 etc/keystone/mapping.json             | 50 +++++++++++++++++++++++++
 mkdocs.yml                            |  1 +
 4 files changed, 102 insertions(+), 51 deletions(-)
 create mode 100644 docs/openstack-keystone-readonly.md
 create mode 100644 etc/keystone/mapping.json

diff --git a/docs/openstack-keystone-federation.md b/docs/openstack-keystone-federation.md
index 808df160..38c1b09b 100644
--- a/docs/openstack-keystone-federation.md
+++ b/docs/openstack-keystone-federation.md
@@ -17,61 +17,12 @@ openstack --os-cloud default identity provider create --remote-id rackspace --do
 You're also welcome to generate your own mapping to suit your needs; however, if you want to use the example mapping (which is suitable for production) you can.
 
 ``` json
-[
-    {
-        "local": [
-            {
-                "user": {
-                    "name": "{0}",
-                    "email": "{1}"
-                }
-            },
-            {
-                "projects": [
-                    {
-                        "name": "{2}_Flex",
-                        "roles": [
-                            {
-                                "name": "member"
-                            },
-                            {
-                                "name": "load-balancer_member"
-                            },
-                            {
-                                "name": "heat_stack_user"
-                            }
-                        ]
-                    }
-                ]
-            }
-        ],
-        "remote": [
-            {
-                "type": "RXT_UserName"
-            },
-            {
-                "type": "RXT_Email"
-            },
-            {
-                "type": "RXT_TenantName"
-            },
-            {
-                "type": "RXT_orgPersonType",
-                "any_one_of": [
-                    "admin",
-                    "default",
-                    "user-admin",
-                    "tenant-access"
-                ]
-            }
-        ]
-    }
-]
+--8<-- "etc/keystone/mapping.json"
 ```
 
 !!! tip
 
-    Save the mapping to a local file before uploading it to keystone. In the examples, the mapping is stored at `/tmp/mapping.json`.
+    The example mapping **JSON** file can be found within the genestack repository at `etc/keystone/mapping.json`.
 
 Now register the mapping within Keystone.
 
diff --git a/docs/openstack-keystone-readonly.md b/docs/openstack-keystone-readonly.md
new file mode 100644
index 00000000..93d0b115
--- /dev/null
+++ b/docs/openstack-keystone-readonly.md
@@ -0,0 +1,49 @@
+# Create a Readonly User
+
+The following commands will setup a readonly user which is able to read data across domains.
+
+## Create the VMM user and project
+
+After running the following commands, a readonly user (example: `vmm`) will have read only access to everything under the `default` and `rackspace_cloud_domain` domains.
+
+### Create a project
+
+``` shell
+openstack --os-cloud default project create --description 'vmm enablement' vmm --domain default
+```
+
+### Create a new user
+
+!!! tip "Make sure to set the password accordingly"
+
+    ``` shell
+    PASSWORD=SuperSecrete
+    ```
+
+``` shell
+openstack --os-cloud default user create --project vmm --password ${PASSWORD} vmm --domain default
+```
+
+### Add the member role to the new user
+
+``` shell
+openstack --os-cloud default role add --user vmm --project vmm member --inherited
+```
+
+### Add the reader roles for user `vmm` to the `default` domain
+
+``` shell
+openstack --os-cloud default role add --user vmm --domain default reader --inherited
+```
+
+### Add the reader role for user `vmm` to the `rackspace_cloud_domain` domain
+
+``` shell
+openstack --os-cloud default role add --user vmm --domain rackspace_cloud_domain reader --inherited
+```
+
+### Add the reader role for user `vmm` to the system
+
+``` shell
+openstack --os-cloud default role add --user vmm --system all reader
+```
diff --git a/etc/keystone/mapping.json b/etc/keystone/mapping.json
new file mode 100644
index 00000000..8b25a211
--- /dev/null
+++ b/etc/keystone/mapping.json
@@ -0,0 +1,50 @@
+[
+    {
+        "local": [
+            {
+                "user": {
+                    "name": "{0}",
+                    "email": "{1}"
+                }
+            },
+            {
+                "projects": [
+                    {
+                        "name": "{2}_Flex",
+                        "roles": [
+                            {
+                                "name": "member"
+                            },
+                            {
+                                "name": "load-balancer_member"
+                            },
+                            {
+                                "name": "heat_stack_user"
+                            }
+                        ]
+                    }
+                ]
+            }
+        ],
+        "remote": [
+            {
+                "type": "RXT_UserName"
+            },
+            {
+                "type": "RXT_Email"
+            },
+            {
+                "type": "RXT_TenantName"
+            },
+            {
+                "type": "RXT_orgPersonType",
+                "any_one_of": [
+                    "admin",
+                    "default",
+                    "user-admin",
+                    "tenant-access"
+                ]
+            }
+        ]
+    }
+]
diff --git a/mkdocs.yml b/mkdocs.yml
index 723d089e..4b6d7419 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -209,6 +209,7 @@ nav:
       - OpenStack:
           - Generating Clouds YAML: openstack-clouds.md
           - Keystone Federation to Rackspace: openstack-keystone-federation.md
+          - Keystone Readonly Users: openstack-keystone-readonly.md
           - Nova Flavor Creation: openstack-flavors.md
           - Nova CPU Allocation Ratio: openstack-cpu-allocation-ratio.md
           - Creating Networks: openstack-neutron-networks.md