View source for Rackspace API/Cloud Networks

This article will show various examples and techniques for working with Rackspace's [http://www.rackspace.com/cloud/networks Cloud Networks] (NaaS) RESTful API.

==HOWTO: create a Cloud Network and attach it to a Cloud Server==

''NOTE: This section will only cover the OpenStack Nova-Network API, not the new OpenStack Neutron API (see: "[http://docs.rackspace.com/networks/api/v2/cn-devguide/content/section_nova_v_neutron.html Networking: Neutron versus Nova-Network]" for details on the difference).''

*Step #0: Setup your environment variables (and authenticate to receive your 24-hour valid token):
	
 $ ACCOUNT=<RAX_ACCOUNT>
 $ USERNAME=<RAX_USERNAME>
 $ APIKEY=<RAX_API_KEY>
 $ TOKEN=`curl -sXPOST <nowiki>https://identity.api.rackspacecloud.com/v2.0/tokens</nowiki> \
          -d'{"auth":{"RAX-KSKEY:apiKeyCredentials": "username":"'$USERNAME'","apiKey":"'$APIKEY'"}}}' \
          -H"Content-type:application/json" | \
          python -c 'import sys,json;data=json.loads(sys.stdin.read());print data["access"]["token"]["id"]'`

*Step #1: Gather the Cloud Server details:

You first need the "<code>server_id</code>" (aka the UUID of the Cloud Server you wish to attach a Cloud Network). You can either obtain the UUID of the server in question, or you can query the API like so:

 $ REGION=dfw
 $ ENDPOINT=<nowiki>https://${REGION}.servers.api.rackspacecloud.com/v2/${ACCOUNT}</nowiki>
 $ # Get a list of all of your Cloud Servers:
 $ curl -sH "X-Auth-Token: $TOKEN" \
        -H "Accept: application/json" \
        "$ENDPOINT/servers" |\
        python -mjson.tool
 $ # Or, get only UUID of the Cloud Server in question by using the server's name:
 $ SERVER_NAME="my-server-name"
 $ SERVER_ID=`curl -sH "X-Auth-Token: $TOKEN" -H "Content-Type: application/json"\
              -H "Accept: application/json" "${ENDPOINT}/servers"|\
              python -c 'import sys,json;data=json.loads(sys.stdin.read());\
                         print [i["id"] for i in data["servers"]\
                                if i["name"]=="'$SERVER_NAME'"][0]'`

* Step #2: Create a Cloud Network:

 $ NETWORK_NAME="my-network-name"
 $ CIDR="192.168.0.0/24"
 $ curl -XPOST \
        -H "X-Auth-Token: $TOKEN" \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        "${ENDPOINT}/os-networksv2" \
        -d '{\"network\": {\"cidr\": \"$CIDR\", "label": "\$NETWORK_NAME\"}}' |\
        python -m json.tool

Grab your new Cloud Network's UUID ("id") from the above output, or capture it with the following command:

 $ NETWORK_ID=`curl -sH "X-Auth-Token: $TOKEN" -H "Content-Type: application/json"\
              -H "Accept: application/json" "${ENDPOINT}/os-networksv2"|\
              python -c 'import sys,json;data=json.loads(sys.stdin.read());\
                         print [i["id"] for i in data["networks"]\
                                if i["label"]=="'$NETWORK_NAME'"][0]'`

* Step #3: Attach your Cloud Network to your Cloud Server:

 $ # List attached networks (before):
 $ curl -H "Content-Type:application/json" \
        -H "X-Auth-Token: $TOKEN" \
        "$ENDPOINT/servers/${SERVER_ID}/os-virtual-interfacesv2" |\
        python -mjson.tool
 
 $ # Attach a Cloud Network:
 $ curl -XPOST \
        -H "Content-Type:application/json" \
        -H "X-Auth-Token: $TOKEN" \
        "$ENDPOINT/servers/${SERVER_ID}/os-virtual-interfacesv2" \
        -d "{\"virtual_interface\":{\"network_id\": \"$NETWORK_ID\"}}"
 
 $ # List attached networks (after):
 $ curl -H "Content-Type:application/json" \
        -H "X-Auth-Token: $TOKEN" \
        "$ENDPOINT/servers/${SERVER_ID}/os-virtual-interfacesv2" |\
        python -mjson.tool

Note: If you are logged into your Cloud Server (via SSH; as root), you can watch the Cloud Network being attached by leaving the following command running from within the Cloud Server while you are attaching the Cloud Network:
 $ xenstore-watch vm-data

The output of the above command before, during, and after attaching the Cloud Network will look something like the following:
 vm-data
 vm-data/meta
 vm-data/networking/BC764EFFFFFF  # <- Cloud Network attached
 vm-data/networking/BC764EFFFFFF
 vm-data/networking/BC764EFFFFFF

As a side note, you might have noticed that all NextGen virtual interfaces (PublicNet, PrivateNet, and Cloud Networks) on Cloud Servers have the same first three octets in their MAC addresses: "BC:76:4E". This is Rackspace's [http://en.wikipedia.org/wiki/Organizationally_unique_identifier Organizationally Unique Identifier] (OUI), so all of your virtual interfaces should match that (and something might have gone wrong if they do not). If you have [https://www.wireshark.org/ Wireshark] installed on your Cloud Server, you can get Rackspace's OUI with:

 $ grep Rackspace /usr/share/wireshark/manuf
 BC:76:4E        Rackspac               # Rackspace US, Inc.

* Step #4: Test your new Cloud Network:

The new Cloud Network's configuration settings will be stored in the following file (it might not be "eth2" on your server):
 /etc/sysconfig/network-scripts/ifcfg-eth2  # Red Hat-based systems

Checking your server network
 $ ifconfig
 $ #~OR~
 $ ip a show

should report the new virtual interface for your new Cloud Network.

You can also check your local XenStore data by running either of the following commands from within your Cloud Server (run as root):
 $ xenstore-ls vm-data/networking
 $ xenstore-read vm-data/networking/BC764EFFFFFF

Finally, you can attach this same Cloud Network to another Cloud Server (in the same region/data centre) and make sure these two servers can communicate with each other on this private Cloud Network.

==See also==
* [[Rackspace API]]

[[Category:Rackspace]]