Neutron API Section Added

Change-Id: I53d05ef30665f26226054baf2f7e71ef824ad943

doc/user-guide/ch_sdk.xml

@@ -12,8 +12,21 @@
     Python by making calls on Python objects rather than making REST
     calls directly. All OpenStack command-line tools are implemented
     using the Python SDK.</para>
+    <para>You should also be familiar with:</para>
+    <itemizedlist spacing="compact">
+      <listitem>
+        <para>RESTful web services</para>
+      </listitem>
+      <listitem>
+        <para>HTTP/1.1</para>
+      </listitem>
+      <listitem>
+        <para>JSON and XML data serialization formats</para>
+      </listitem>
+    </itemizedlist>
   <xi:include href="section_sdk_install.xml"/>
   <xi:include href="section_sdk_authenticate.xml"/>
   <xi:include href="section_sdk_manage_images.xml"/>
   <xi:include href="section_sdk_configure_instances.xml"/>
+  <xi:include href="section_sdk_neutron.xml"/>
 </chapter>

doc/user-guide/section_sdk_auth_keystone.xml

@@ -3,8 +3,8 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:id="sdk_auth_keystone">
-  <title>Authenticate against an Identity Service endpoint</title>
+  <title>Authenticate against an Identity endpoint</title>
-  <para>To authenticate against the Identity Service v2.0 endpoint,
+  <para>To authenticate against the Identity v2.0 endpoint,
     instantiate a <link
       xlink:href="http://docs.openstack.org/developer/python-keystoneclient/api/keystoneclient.v2_0.client.html#keystoneclient.v2_0.client.Client"
       > keystoneclient.v_20.client.Client</link> object:</para>

doc/user-guide/section_sdk_auth_nova.xml

@@ -28,16 +28,16 @@ nova = novaclient.client.Client("1.1", auth_url=env['OS_AUTH_URL'],
   <para>If you authenticate against an endpoint that uses a custom
     authentication back-end, you must load the authentication plug-in
     and pass it to the constructor.</para>
-  <para>The Rackspace Public Cloud is an OpenStack deployment that
+  <para>The Rackspace public cloud is an OpenStack deployment that
-    uses a custom authentication back-end. To authenticate against
+    uses a custom authentication back end. To authenticate against
     this cloud, you must install the <link
       xlink:href="https://pypi.python.org/pypi/rackspace-novaclient/">
       rackspace-novaclient</link> library that contains the Rackspace
     authentication plug-in, called <literal>rackspace</literal>. The
     following Python code shows the additional modifications required
     to instantiate a <classname>Client</classname> object that can
-    authenticate against the Rackspace custom authentication
+    authenticate against the Rackspace custom authentication back
-    back-end.</para>
+    end.</para>
   <programlisting language="python">import novaclient.auth_plugin
 import novaclient.v1_1.client as nvclient
 from os import environ as env
@@ -52,8 +52,8 @@ nova = nvclient.Client(auth_url=env['OS_AUTH_URL'],
                        auth_plugin=auth_plugin)</programlisting>
   <para>If you set the <literal>OS_AUTH_SYSTEM</literal> environment
     variable, check for this variable in your Python script to
-    determine whether you need to load a custom authentication
+    determine whether you need to load a custom authentication back
-    back-end:</para>
+    end:</para>
   <programlisting language="python">import novaclient.auth_plugin
 import novaclient.v1_1.client as nvclient
 from os import environ as env

doc/user-guide/section_sdk_authenticate.xml

@@ -2,13 +2,13 @@
 <section xmlns="http://docbook.org/ns/docbook"
 xmlns:xi="http://www.w3.org/2001/XInclude"
 xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sdk_auth">
-  <title>Authentication</title>
+  <title>Authenticate</title>
-  <para>You must authenticate against an OpenStack endpoint before you can
+  <para>You must authenticate against an OpenStack endpoint before you
-  use OpenStack services. Each project uses a slightly different syntax for doing
+    can use OpenStack services. Each project uses a slightly different
-  authentication.</para>
+    syntax for authentication.</para>
   <para>You must typically authenticate against a specific version of
     a service. For example, a client might need to authenticate
-    against the Identity Service v2.0.</para>
+    against Identity v2.0.</para>
   <para>Python scripts that use the OpenStack SDK must have access to the
   credentials contained in the
   <link linkend="cli_openrc">OpenStack RC file</link>. Because credentials
@@ -17,6 +17,6 @@ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sdk_auth">
   the credentials by using the environment variables in the Python scripts.</para>
   <xi:include href="section_sdk_auth_keystone.xml"/>
   <xi:include href="section_sdk_auth_glance.xml"/>
-  <xi:include href="section_sdk_auth_nova.xml" />
+  <xi:include href="section_sdk_auth_nova.xml"/>
   <xi:include href="section_sdk_auth_neutron.xml" />
 </section>

doc/user-guide/section_sdk_configure_instances.xml

@@ -11,27 +11,25 @@
             <methodname>
             <link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.keypairs.html#novaclient.v1_1.keypairs.KeypairManager.create">novaclient.v1_1.keypairs.KeypairManager.create</link>
             </methodname>
-            method:
+            method:</para>
         <programlisting language="python">import novaclient.v1_1.client as nvclient
 nova = nvclient.Client(...)
 keypair_name = "staging"
 keypair = nova.keypairs.create(name=keypair_name)
 print keypair.private_key</programlisting>
-        </para>
+        <para>The Python script output looks something like this:</para>
-        <para>The Python script output looks something like this:
         <screen><computeroutput>-----BEGIN RSA PRIVATE KEY-----
 MIIEowIBAAKCAQEA8XkaMqInSPfy0hMfWO+OZRtIgrQAbQkNcaNHmv2GN2G6xZlb\nuBRux5Xk/6SZ
 ABaNPm1nRWm/ZDHnxCsFTcAl2LYOQXx3Cl2qKNY4r2di4G48GAkd\n7k5lDP2RgQatUM8npO0CD9PU
 ...
 mmrceYYK08/lQ7JKLmVkdzdQKt77+v1oBBuHiykLfI6h1m77NRDw9r8cV\nzczYeoALifpjTPMkKS8
 ECfDCuDn/vc9K1He8CRaJHf8AMLQLM3MN
------END RSA PRIVATE KEY-----</computeroutput></screen></para>
+-----END RSA PRIVATE KEY-----</computeroutput></screen>
-
+    <para>You typically write the private key to a file to use it
-    <para>You will typically write the private key to a file in order to use it
     later. The file must be readable and writeable by only the file owner,
     otherwise the ssh client will refuse to read the private key file. It
     is safest to create the file with the appropriate permissions, as shown in
-    the following example:
+    the following example:</para>
     <programlisting language="python">import novaclient.v1_1.client as nvclient
 import os
 nova = nvclient.Client(...)
@@ -43,9 +41,7 @@ keypair = nova.keypairs.create(name=keypair_name)
 fp = os.open(private_key_filename, os.O_WRONLY | os.O_CREAT, 0o600)
 with os.fdopen(fp, 'w') as f:
     f.write(keypair.private_key)</programlisting>
-    </para>
     </section>
-
     <section xml:id="import_keypair_sdk">
         <title>Import a keypair</title>
         <para>If you have already generated a keypair with the
@@ -53,58 +49,58 @@ with os.fdopen(fp, 'w') as f:
         pass the contents of the file to the <methodname>
             <link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.keypairs.html#novaclient.v1_1.keypairs.KeypairManager.create">
                 novaclient.v1_1.keypairs.KeypairManager.create</link></methodname>
-        method to import the public key to Compute:
+        method to import the public key to Compute:</para>
         <programlisting language="python">import novaclient.v1_1.client as nvclient
 import os.path
 with open(os.path.expanduser('~/.ssh/id_rsa.pub')) as f:
     public_key = f.read()
 nova = nvclient.Client(...)
-nova.keypairs.create('mykey', public_key)</programlisting></para>
+nova.keypairs.create('mykey', public_key)</programlisting>
     </section>
     <section xml:id="list_keypairs_sdk">
         <title>List keypairs</title>
         <para>To list keypairs, call the <methodname>
             <link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.keypairs.html#novaclient.v1_1.keypairs.KeypairManager.list">novaclient.v1_1.keypairs.KeypairManager.list</link></methodname>
-            method:
+            method:</para>
             <programlisting language="python">import novaclient.v1_1.client as nvclient
 nova = nvclient.Client(...)
-keypairs = nova.keypairs.list()</programlisting></para>
+keypairs = nova.keypairs.list()</programlisting>
     </section>
     <section xml:id="security_groups_sdk">
         <title>Create and manage security groups</title>
         <para>To list security groups for the current project, call the
-            <methodname><link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroupManager.list">novaclient.v_1.security_groups.SecurityGroupManager.list</link></methodname> method:
+            <methodname><link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroupManager.list">novaclient.v_1.security_groups.SecurityGroupManager.list</link></methodname> method:</para>
         <programlisting language="python">import novaclient.v1_1.client as nvclient
 nova = nvclient.Client(...)
-security_groups = nova.security_groups.list()</programlisting></para>
+security_groups = nova.security_groups.list()</programlisting>
         <para>To create a security group with a specified name and description,
-            call the <methodname><link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroupManager.create">novaclient.v_1.security_groups.SecurityGroupManager.create</link></methodname> method:
+            call the <methodname><link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroupManager.create">novaclient.v_1.security_groups.SecurityGroupManager.create</link></methodname> method:</para>
 <programlisting language="python">import novaclient.v1_1.client as nvclient
 nova = nvclient.Client(...)
-nova.security_groups.create(name="web", description="Web servers")</programlisting></para>
+nova.security_groups.create(name="web", description="Web servers")</programlisting>
         <para>To delete a security group, call the
             <methodname>
                 <link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroupManager.delete">
                     novaclient.v_1.security_groups.SecurityGroupManager.delete</link></methodname> method, passing either a <link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroup">novaclient.v1_1.security_groups.SecurityGroup</link>
-            object or group ID as an argument:
+            object or group ID as an argument:</para>
             <programlisting language="python">import novaclient.v1_1.client as nvclient
 nova = nvclient.Client(...)
 group = nova.security_groups.find(name="web")
 nova.security_groups.delete(group)
 # The following lines would also delete the group:
 # nova.security_groups.delete(group.id)
-# group.delete()</programlisting></para>
+# group.delete()</programlisting>
     </section>
     <section xml:id="sdk_secgroup_rules">
         <title>Create and manage security group rules</title>
         <para>Access the security group rules from the <literal>rules</literal>
-        attribute of a <link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroup">novaclient.v1_1.security_groups.SecurityGroup</link> object:
+        attribute of a <link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_groups.html#novaclient.v1_1.security_groups.SecurityGroup">novaclient.v1_1.security_groups.SecurityGroup</link> object:</para>
 <programlisting language="python">import novaclient.v1_1.client as nvclient
 nova = nvclient.Client(...)
 group = nova.security_groups.find(name="web")
-print group.rules</programlisting></para>
+print group.rules</programlisting>
         <para>To add a rule, to a security group, call the <methodname><link xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.security_group_rules.html#novaclient.v1_1.security_group_rules.SecurityGroupRuleManager.create">novaclient.v1_1.security_group_rules.SecurityGroupRuleManager.create</link></methodname>
-        method:
+        method:</para>
 <programlisting language="python">import novaclient.v1_1.client as nvclient
 nova = nvclient.Client(...)
 group = nova.security_groups.find(name="web")
@@ -114,6 +110,6 @@ nova.security_group_rules.create(group.id, ip_protocol="icmp",
 nova.security_group_rules.create(group.id, ip_protocol="tcp",
                                  from_port=80, to_port=80)
 nova.security_group_rules.create(group.id, ip_protocol="tcp",
-                                 from_port=443, to_port=443)</programlisting></para>
+                                 from_port=443, to_port=443)</programlisting>
     </section>
 </section>

doc/user-guide/section_sdk_neutron.xml

@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="sdk_neutron_apis">
+    <title>Networking</title>
+    <?dbhtml stop-chunking?>
+  <para>To use the information in this section, you should
+    have a general understanding of OpenStack Networking,
+    OpenStack Compute, and the integration between the two. You
+    should also have access to a plug-in that implements the
+    Networking API v2.0.</para>
+    <section xml:id="sdk_neutron_env">
+      <title>Set environment variables</title>
+      <para>Make sure that you set the relevant environment variables
+      appropriately.</para>
+    <para>As an example, see the sample shell file that sets the
+      variables used to get credentials:</para>
+      <programlisting language="bash">export OS_USERNAME="<replaceable>admin</replaceable>"
+export OS_PASSWORD="<replaceable>password</replaceable>"
+export OS_TENANT_NAME="admin"
+export OS_AUTH_URL="http://<replaceable>IPADDRESS</replaceable>/v2.0"</programlisting>
+    </section>
+    <section xml:id="sdk_neutron_common_code">
+      <title>Get credentials</title>
+      <para>The examples in this section use the following common <code>get_credentials</code> method:</para>
+      <programlisting language="python">def get_credentials():
+    d = {}
+    d['username'] = os.environ['OS_USERNAME']
+    d['password'] = os.environ['OS_PASSWORD']
+    d['auth_url'] = os.environ['OS_AUTH_URL']
+    d['tenant_name'] = os.environ['OS_TENANT_NAME']
+    return d</programlisting>
+      <para>This code is assumed to exist in the <filename>credentials.py</filename> file, which all
+      samples import.</para>
+    </section>
+    <?hard-pagebreak?>
+    <section xml:id="sdk_neutron_create_network">
+      <title>Create network</title>
+      <para>The following program creates a network:</para>
+      <programlisting language="python">from neutronclient.v2_0 import client
+from credentials import get_credentials
+from utils import print_networks
+
+network_name = "sample_network"
+credentials = get_credentials()
+neutron = client.Client(**credentials)
+try:
+    body_sample = {
+        "network":
+        {
+           "name": network_name,
+           "admin_state_up": True
+        }
+       }
+    netw = neutron.create_network(body=body_sample)
+    net_dict = netw['network']
+    network_id = net_dict['id']
+    print "Network %s created" % network_id
+
+    body_create_subnet = {
+      "subnets":[
+          {
+             "cidr":"192.168.199.0/24",
+             "ip_version":4,
+             "network_id": network_id
+          }
+      ]
+    }
+
+    subnet = neutron.create_subnet(body=body_create_subnet)
+    print "Created subnet %s" % subnet
+finally:
+    print "Execution completed"
+    #neutron.delete_network(network_id)
+    #print "Deleted Network %s" %network_id</programlisting>
+    </section>
+    <section xml:id="sdk_neutron_list_networks">
+      <title>List networks</title>
+      <para>The following program lists networks:</para>
+      <programlisting language="python">from neutronclient.v2_0 import client
+from credentials import get_credentials
+from utils import print_values
+
+
+credentials = get_credentials()
+neutron = client.Client(**credentials)
+netw = neutron.list_networks()
+
+print_values(netw, 'networks')</programlisting>
+    </section>
+    <section xml:id="sdk_neutron_create_port">
+      <title>Create port</title>
+      <para>The following program creates a port:</para>
+      <programlisting language="python">from neutronclient.v2_0 import client
+import novaclient.v1_1.client as nvclient
+from credentials import get_credentials
+from utils import print_values_server
+from credentials import get_nova_credentials
+
+credentials = get_nova_credentials()
+nova_client = nvclient.Client(**credentials)
+
+#replace with server_id and network_id from your environment
+
+server_id = '9a52795a-a70d-49a8-a5d0-5b38d78bd12d'
+network_id = 'ce5d204a-93f5-43ef-bd89-3ab99ad09a9a'
+server_detail = nova_client.servers.get(server_id)
+print server_detail.id
+
+if server_detail != None:
+    credentials = get_credentials()
+    neutron = client.Client(**credentials)
+
+    body_value = {
+                     "port": {
+                             "admin_state_up": True,
+                             "device_id": server_id,
+                             "name": "port1",
+                             "network_id": network_id
+                      }
+                 }
+    response = neutron.create_port(body=body_value)
+    print response</programlisting>
+    </section>
+    <section xml:id="sdk_neutron_list_ports">
+      <title>List ports</title>
+      <para>The following program lists ports:</para>
+      <programlisting language="python">from neutronclient.v2_0 import client
+from credentials import get_credentials
+from utils import print_values
+
+credentials = get_credentials()
+neutron = client.Client(**credentials)
+ports = neutron.list_ports()
+print print_values(ports, 'ports')</programlisting>
+    </section>
+    <section xml:id="sdk_neutron_list_server_ports">
+      <title>List server ports</title>
+      <para>The following program lists the ports for a server:</para>
+      <programlisting language="python">from neutronclient.v2_0 import client
+from credentials import get_credentials
+from utils import print_values
+
+
+credentials = get_credentials()
+neutron = client.Client(**credentials)
+ports = neutron.list_ports()
+print print_values(ports, 'ports')</programlisting>
+    </section>
+  </section>