Merge "Provide example policyd override - Extended server attributes"

2019-12-16 18:57:09 +00:00 · 2019-12-16 18:57:09 +00:00 · 4f8fa354e5
commit 4f8fa354e5
parent 5653da4965 565710807a
1 changed files with 115 additions and 0 deletions
--- a/deploy-guide/source/app-policy-overrides.rst
+++ b/deploy-guide/source/app-policy-overrides.rst
@ -137,3 +137,118 @@ the charm or disable the overrides entirely (i.e. set ``use-policyd-overrides``
 to 'false').

 Information on broken overrides will appear in the logs.
+
+Examples
++++++++
+
+This area contains examples of policy override usage.
+
+Showing extended server attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example involves changing the default policy affecting the
+nova-cloud-controller application.
+
+Ordinarily, when a non-admin user requests details for a cloud instance some
+fields are not shown. This is because some information is deemed inappropriate
+or too sensitive for the regular user. For instance, this is the (partial)
+default output to the :command:`openstack server show` command:
+
+.. code-block:: console
+
+   echo $OS_USERNAME
+   User1
+
+   openstack server show 9167b3e9-c653-43fc-858a-2d6f6da36daa
+
+   +-----------------------------+----------------------------------------------------------+
+   | Field                       | Value                                                    |
+   +-----------------------------+----------------------------------------------------------+
+   | OS-DCF:diskConfig           | MANUAL                                                   |
+   | OS-EXT-AZ:availability_zone | nova                                                     |
+   | OS-EXT-STS:power_state      | Running                                                  |
+   | OS-EXT-STS:task_state       | None                                                     |
+   | OS-EXT-STS:vm_state         | active                                                   |
+   | OS-SRV-USG:launched_at      | 2019-12-11T23:09:47.000000                               |
+   | OS-SRV-USG:terminated_at    | None                                                     |
+
+Compare that output to what an admin sees:
+
+.. code-block:: console
+
+   echo $OS_USERNAME
+   admin
+
+   openstack server show 9167b3e9-c653-43fc-858a-2d6f6da36daa
+
+   +-------------------------------------+--------------------------------------------------+
+   | Field                               | Value                                            |
+   +-------------------------------------+--------------------------------------------------+
+   | OS-DCF:diskConfig                   | MANUAL                                           |
+   | OS-EXT-AZ:availability_zone         | nova                                             |
+   | OS-EXT-SRV-ATTR:host                | virt-node-01.maas                                |
+   | OS-EXT-SRV-ATTR:hypervisor_hostname | virt-node-01.maas                                |
+   | OS-EXT-SRV-ATTR:instance_name       | instance-00000001                                |
+   | OS-EXT-STS:power_state              | Running                                          |
+   | OS-EXT-STS:task_state               | None                                             |
+   | OS-EXT-STS:vm_state                 | active                                           |
+   | OS-SRV-USG:launched_at              | 2019-12-11T23:09:47.000000                       |
+   | OS-SRV-USG:terminated_at            | None                                             |
+
+The admin user has three extra fields that are categorised as *extended server
+attributes*:
+
+.. code-block:: console
+
+   | OS-EXT-SRV-ATTR:host                | virt-node-01.maas                                |
+   | OS-EXT-SRV-ATTR:hypervisor_hostname | virt-node-01.maas                                |
+   | OS-EXT-SRV-ATTR:instance_name       | instance-00000001                                |
+
+For some environments, such as an internal company cloud, the benefits of
+providing this information to users may outweigh any perceived concerns. For
+example, users will know immediately whether an announced hypervisor
+maintenance procedure will affect their running instances, providing that the
+announcement includes the hypervisor name.
+
+To make this happen the default policy affecting the `Nova API`_ will need to
+be overridden to include the owner of the instance as well as the admin. The
+policy "target" that controls these particular fields is
+``os_compute_api:os-extended-server-attributes``.
+
+The final policy statement is placed in a file, say,
+``nova-server-attributes.yaml``:
+
+.. code-block:: ini
+
+   {
+       #"os_compute_api:os-extended-server-attributes": "rule:admin_api"
+       "os_compute_api:os-extended-server-attributes": "rule:admin_or_owner"
+   }
+
+The default statement is left as a comment in order to provide some extra
+context.
+
+Compress the file, attach it as a resource to the nova-cloud-controller
+application, and enable the override:
+
+.. code-block:: console
+
+   zip nova-server-attributes.zip nova-server-attributes.yaml
+   juju attach-resource nova-cloud-controller policyd-override=nova-server-attributes.zip
+   juju config nova-cloud-controller use-policyd-override=true
+
+Any non-admin user should now have access to three extra fields when querying
+the instances that they own with the :command:`openstack server show` command.
+
+More extended attributes can be displayed through the use of option
+``--os-compute-api-version``. For example:
+
+.. code-block:: console
+
+   openstack --os-compute-api-version 2.3 server show 9167b3e9-c653-43fc-858a-2d6f6da36daa
+
+See the upstream documentation on `Show Server Details`_.
+
+.. LINKS
+.. _Nova API: https://docs.openstack.org/nova/latest/configuration/policy.html
+.. _Show Server Details: https://docs.openstack.org/api-ref/compute/?expanded=show-server-details-detail#show-server-details