Update policy descriptions for base.

These are the final policy rules that are missing a description.

The "network:attach_external_network" policy rule is moved from
base to servers policy since it's not really a base rule, it
applies to creating a server with requested networks or attaching
networking to a server. Therefore it is moved and the documentation
for it are both cleaned up.

Change-Id: I050c4f5f19aa79a682e076cc3e47eba597f272dd
Implements: blueprint policy-docs

nova/network/neutronv2/api.py

@@ -38,7 +38,7 @@ from nova.pci import manager as pci_manager
 from nova.pci import request as pci_request
 from nova.pci import utils as pci_utils
 from nova.pci import whitelist as pci_whitelist
-from nova.policies import base as base_policies
+from nova.policies import servers as servers_policies
 from nova import profiler
 from nova import service_auth
 
@@ -463,7 +463,7 @@ class API(base_api.NetworkAPI):
 
     def _check_external_network_attach(self, context, nets):
         """Check if attaching to external network is permitted."""
-        if not context.can(base_policies.NETWORK_ATTACH_EXTERNAL,
+        if not context.can(servers_policies.NETWORK_ATTACH_EXTERNAL,
                            fatal=False):
             for net in nets:
                 # Perform this check here rather than in validate_networks to

nova/policies/base.py

@@ -13,18 +13,27 @@
 from oslo_policy import policy
 
 COMPUTE_API = 'os_compute_api'
-NETWORK_ATTACH_EXTERNAL = 'network:attach_external_network'
 
 RULE_ADMIN_OR_OWNER = 'rule:admin_or_owner'
 RULE_ADMIN_API = 'rule:admin_api'
 RULE_ANY = '@'
 
+# NOTE(johngarbutt) The base rules here affect so many APIs the list
+# of related API operations has not been populated. It would be
+# crazy hard to manually maintain such a list.
 rules = [
-    policy.RuleDefault('context_is_admin', 'role:admin'),
-    policy.RuleDefault('admin_or_owner',
-                       'is_admin:True or project_id:%(project_id)s'),
-    policy.RuleDefault('admin_api', 'is_admin:True'),
-    policy.RuleDefault(NETWORK_ATTACH_EXTERNAL, 'is_admin:True'),
+    policy.RuleDefault(
+        "context_is_admin",
+        "role:admin",
+        "Decides what is required for the 'is_admin:True' check to succeed."),
+    policy.RuleDefault(
+        "admin_or_owner",
+        "is_admin:True or project_id:%(project_id)s",
+        "Default rule for most non-Admin APIs."),
+    policy.RuleDefault(
+        "admin_api",
+        "is_admin:True",
+        "Default rule for most Admin APIs.")
 ]
 
 

nova/policies/servers.py

@@ -18,6 +18,7 @@ from nova.policies import base
 
 RULE_AOO = base.RULE_ADMIN_OR_OWNER
 SERVERS = 'os_compute_api:servers:%s'
+NETWORK_ATTACH_EXTERNAL = 'network:attach_external_network'
 
 rules = [
     policy.DocumentedRuleDefault(
@@ -126,6 +127,22 @@ rules = [
                 'path': '/servers'
             }
         ]),
+    policy.DocumentedRuleDefault(
+        NETWORK_ATTACH_EXTERNAL,
+        'is_admin:True',
+        "Attach an unshared external network to a server",
+        [
+            # Create a server with a requested network or port.
+            {
+                'method': 'POST',
+                'path': '/servers'
+            },
+            # Attach a network or port to an existing server.
+            {
+                'method': 'POST',
+                'path': '/servers/{server_id}/os-interface'
+            }
+        ]),
     policy.DocumentedRuleDefault(
         SERVERS % 'delete',
         RULE_AOO,