Document the "immutable" resource option

Roles, projects, and domains can accept "immutable" as a resource
option. This change explains the option in the admin guide and updates
the API reference to mention it.

Change-Id: I95926927472f6418f97a08fea0ebd56da04ce7a5
Related-bug: #1823258

16 files changed, 80 insertions, 11 deletions

diff --git a/api-ref/source/v3/domains.inc b/api-ref/source/v3/domains.inc
index 9611df0fb..0da7f40d0 100644
--- a/api-ref/source/v3/domains.inc
+++ b/api-ref/source/v3/domains.inc
@@ -102,6 +102,7 @@ Parameters
    - enabled: domain_enabled_request_body
    - description: domain_description_request_body
    - name: domain_name_request_body
+   - options: request_domain_options_body_not_required
 
 Example
 ~~~~~~~
@@ -123,6 +124,7 @@ Parameters
    - id: domain_id_response_body
    - links: domain_link_response_body
    - name: domain_name_response_body
+   - options: response_role_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
@@ -177,6 +179,7 @@ Parameters
    - id: domain_id_response_body
    - links: domain_link_response_body
    - name: domain_name_response_body
+   - options: response_role_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
@@ -224,6 +227,7 @@ Parameters
    - enabled: domain_enabled_update_request_body
    - description: domain_description_update_request_body
    - name: domain_name_update_request_body
+   - options: request_domain_options_body_not_required
 
 Example
 ~~~~~~~
@@ -245,6 +249,7 @@ Parameters
    - id: domain_id_response_body
    - links: domain_link_response_body
    - name: domain_name_response_body
+   - options: response_role_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 724ab3582..c86d6628d 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -1664,6 +1664,13 @@ request_default_limit_body_not_required:
   in: body
   required: false
   type: integer
+request_domain_options_body_not_required:
+  description: |
+    The resource options for the domain. Available resource options are
+    ``immutable``.
+  in: body
+  required: false
+  type: object
 request_limit_domain_id_not_required:
   description: |
     The name of the domain.
@@ -1676,6 +1683,13 @@ request_limit_project_id_not_required:
   in: body
   required: false
   type: string
+request_project_options_body_not_required:
+  description: |
+    The resource options for the project. Available resource options are
+    ``immutable``.
+  in: body
+  required: false
+  type: object
 request_region_id_registered_limit_body_not_required:
   description: |
     The ID of the region that contains the service endpoint.
@@ -1698,6 +1712,13 @@ request_resource_name_body_not_required:
   in: body
   required: false
   type: string
+request_role_options_body_not_required:
+  description: |
+    The resource options for the role. Available resource options are
+    ``immutable``.
+  in: body
+  required: false
+  type: object
 request_service_id_registered_limit_body_not_required:
   description: |
     The UUID of the service to update to which the registered
@@ -1842,12 +1863,33 @@ response_body_system_required:
   in: body
   required: true
   type: array
+response_domain_options_body_required:
+  description: |
+    The resource options for the domain. Available resource options are
+    ``immutable``.
+  in: body
+  required: true
+  type: object
 response_limit_domain_id_body:
   description: |
     The ID of the domain.
   in: body
   required: true
   type: string
+response_project_options_body_required:
+  description: |
+    The resource options for the project. Available resource options are
+    ``immutable``.
+  in: body
+  required: true
+  type: object
+response_role_options_body_required:
+  description: |
+    The resource options for the role. Available resource options are
+    ``immutable``.
+  in: body
+  required: true
+  type: object
 response_user_options_body_required:
   description: |
     The resource options for the user. Available resource options are
diff --git a/api-ref/source/v3/projects.inc b/api-ref/source/v3/projects.inc
index 0a63d6f63..348b9c2a1 100644
--- a/api-ref/source/v3/projects.inc
+++ b/api-ref/source/v3/projects.inc
@@ -126,6 +126,7 @@ Parameters
    - enabled: project_enabled_request_body
    - parent_id: project_parent_id_request_body
    - tags: project_tags_request_body
+   - options: request_project_options_body_not_required
 
 Examples
 ~~~~~~~~
@@ -157,6 +158,7 @@ Parameters
    - links: link_response_body
    - name: project_name_response_body
    - parent_id: project_parent_id_response_body
+   - options: response_project_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
@@ -213,6 +215,7 @@ Parameters
    - links: link_response_body
    - name: project_name_response_body
    - parent_id: project_parent_id_response_body
+   - options: response_project_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
@@ -272,6 +275,7 @@ Parameters
    - domain_id: project_domain_id_update_request_body
    - enabled: project_enabled_update_request_body
    - tags: project_tags_request_body
+   - options: request_project_options_body_not_required
 
 Example
 ~~~~~~~
@@ -296,6 +300,7 @@ Parameters
    - name: project_name_response_body
    - links: link_response_body
    - parent_id: project_parent_id_response_body
+   - options: response_project_options_body_required
 
 
 Status Codes
@@ -354,4 +359,4 @@ Status Codes
    - 400
    - 401
    - 403
-   - 404
\ No newline at end of file
+   - 404
diff --git a/api-ref/source/v3/roles.inc b/api-ref/source/v3/roles.inc
index b362524ed..3073e241d 100644
--- a/api-ref/source/v3/roles.inc
+++ b/api-ref/source/v3/roles.inc
@@ -176,6 +176,7 @@ Parameters
    - name: role_name_create_body
    - domain_id: role_domain_id_request_body
    - description: role_description_create_body
+   - options: request_role_options_body_not_required
 
 Example
 ~~~~~~~
@@ -203,6 +204,7 @@ Parameters
    - links: link_response_body
    - name: role_name_response_body
    - description: role_description_response_body_required
+   - options: response_role_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
@@ -252,6 +254,7 @@ Parameters
    - links: link_response_body
    - name: role_name_response_body
    - description: role_description_response_body_required
+   - options: response_role_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
@@ -295,6 +298,7 @@ Parameters
    - role: role
    - name: role_name_update_body
    - description: role_description_update_body
+   - options: request_role_options_body_not_required
 
 Example
 ~~~~~~~
@@ -316,6 +320,7 @@ Parameters
    - links: link_response_body
    - name: role_name_response_body
    - description: role_description_response_body_required
+   - options: response_role_options_body_required
 
 Status Codes
 ~~~~~~~~~~~~
diff --git a/api-ref/source/v3/samples/admin/domain-create-response.json b/api-ref/source/v3/samples/admin/domain-create-response.json
index e6665ff64..99e81532f 100644
--- a/api-ref/source/v3/samples/admin/domain-create-response.json
+++ b/api-ref/source/v3/samples/admin/domain-create-response.json
@@ -6,6 +6,7 @@
         "links": {
             "self": "http://example.com/identity/v3/domains/161718"
         },
-        "name": "myDomain"
+        "name": "myDomain",
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/domain-show-response.json b/api-ref/source/v3/samples/admin/domain-show-response.json
index 35b943ef3..68a1432c9 100644
--- a/api-ref/source/v3/samples/admin/domain-show-response.json
+++ b/api-ref/source/v3/samples/admin/domain-show-response.json
@@ -6,6 +6,7 @@
         "links": {
             "self": "http://example.com/identity/v3/domains/default"
         },
-        "name": "Default"
+        "name": "Default",
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/domain-update-response.json b/api-ref/source/v3/samples/admin/domain-update-response.json
index cc5ca0f7f..bcc6d2553 100644
--- a/api-ref/source/v3/samples/admin/domain-update-response.json
+++ b/api-ref/source/v3/samples/admin/domain-update-response.json
@@ -6,6 +6,7 @@
         "enabled": true,
         "description": "Owns users and projects on Identity API v2.",
         "name": "Default",
-        "id": "default"
+        "id": "default",
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/project-create-request.json b/api-ref/source/v3/samples/admin/project-create-request.json
index 409dae86a..6878e3ed6 100644
--- a/api-ref/source/v3/samples/admin/project-create-request.json
+++ b/api-ref/source/v3/samples/admin/project-create-request.json
@@ -4,6 +4,7 @@
         "domain_id": "default",
         "enabled": true,
         "is_domain": false,
-        "name": "myNewProject"
+        "name": "myNewProject",
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/project-create-response.json b/api-ref/source/v3/samples/admin/project-create-response.json
index 9c7dbe3a6..390653ea2 100644
--- a/api-ref/source/v3/samples/admin/project-create-response.json
+++ b/api-ref/source/v3/samples/admin/project-create-response.json
@@ -10,6 +10,7 @@
         },
         "name": "myNewProject",
         "parent_id": "default",
-        "tags": []
+        "tags": [],
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/project-show-parents-response.json b/api-ref/source/v3/samples/admin/project-show-parents-response.json
index d01cdf917..ee9fc177b 100644
--- a/api-ref/source/v3/samples/admin/project-show-parents-response.json
+++ b/api-ref/source/v3/samples/admin/project-show-parents-response.json
@@ -7,6 +7,7 @@
             "self": "http://example.com/identity/v3/projects/263fd9"
         },
         "name": "Dev Group A",
+        "options": {},
         "parent_id": "183ab2",
         "parents": [
             {
diff --git a/api-ref/source/v3/samples/admin/project-show-response.json b/api-ref/source/v3/samples/admin/project-show-response.json
index 573bf16d6..8127240ae 100644
--- a/api-ref/source/v3/samples/admin/project-show-response.json
+++ b/api-ref/source/v3/samples/admin/project-show-response.json
@@ -9,6 +9,7 @@
             "self": "http://example.com/identity/v3/projects/0c4e939acacf4376bdcd1129f1a054ad"
         },
         "name": "admin",
-        "parent_id": "default"
+        "parent_id": "default",
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/project-show-subtree-response.json b/api-ref/source/v3/samples/admin/project-show-subtree-response.json
index 383d93d4b..aa0984cbd 100644
--- a/api-ref/source/v3/samples/admin/project-show-subtree-response.json
+++ b/api-ref/source/v3/samples/admin/project-show-subtree-response.json
@@ -7,6 +7,7 @@
             "self": "http://example.com/identity/v3/projects/263fd9"
         },
         "name": "Dev Group A",
+        "options": {},
         "parent_id": "183ab2",
         "subtree": [
             {
diff --git a/api-ref/source/v3/samples/admin/project-update-response.json b/api-ref/source/v3/samples/admin/project-update-response.json
index 31a943a88..a66946a82 100644
--- a/api-ref/source/v3/samples/admin/project-update-response.json
+++ b/api-ref/source/v3/samples/admin/project-update-response.json
@@ -10,6 +10,7 @@
         "is_domain": true,
         "name": "myUpdatedProject",
         "parent_id": null,
-        "tags": []
+        "tags": [],
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/role-create-response.json b/api-ref/source/v3/samples/admin/role-create-response.json
index 3a1c8ae8d..dd8575112 100644
--- a/api-ref/source/v3/samples/admin/role-create-response.json
+++ b/api-ref/source/v3/samples/admin/role-create-response.json
@@ -5,6 +5,7 @@
             "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
         },
         "description": "My new role",
-        "name": "developer"
+        "name": "developer",
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/role-show-response.json b/api-ref/source/v3/samples/admin/role-show-response.json
index 4cb7000c4..c64e0c44d 100644
--- a/api-ref/source/v3/samples/admin/role-show-response.json
+++ b/api-ref/source/v3/samples/admin/role-show-response.json
@@ -6,6 +6,7 @@
             "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
         },
         "description": "My new role",
-        "name": "Developer"
+        "name": "Developer",
+        "options": {}
     }
 }
diff --git a/api-ref/source/v3/samples/admin/role-update-response.json b/api-ref/source/v3/samples/admin/role-update-response.json
index 1fd075f3e..27e681390 100644
--- a/api-ref/source/v3/samples/admin/role-update-response.json
+++ b/api-ref/source/v3/samples/admin/role-update-response.json
@@ -6,6 +6,7 @@
             "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"
         },
         "description": "My new role",
-        "name": "Developer"
+        "name": "Developer",
+        "options": {}
     }
 }