NetworkingV2 (neutron)¶ ↑

This document explains how to get started using NetworkingV2 with Fog. It assumes you have read the Getting Started with Fog and the Rackspace Open Cloud document.

Starting irb console¶ ↑

Start by executing the following command:

irb

Once irb has launched you need to require the Fog library.

If using Ruby 1.8.x execute:

    require 'rubygems'
    require 'fog'

If using Ruby 1.9.x execute:

    require 'fog'

Create Service¶ ↑

Next, create a connection to Rackspace's NetworkingV2 API:

Using a US-based account:

    service = Fog::Rackspace::NetworkingV2.new({
            :rackspace_username  => RACKSPACE_USER_NAME, # Your Rackspace Username
            :rackspace_api_key       => RACKSPACE_API,       # Your Rackspace API key
            :rackspace_region        => :ord,                # Defaults to :dfw
    })

Using a UK-based account:

    service = Fog::Compute.new({
            :rackspace_username  => RACKSPACE_USER_NAME,        # Your Rackspace Username
            :rackspace_api_key   => RACKSPACE_API,              # Your Rackspace API key
            :rackspace_auth_url  => Fog::Rackspace::UK_AUTH_ENDPOINT,
            :rackspace_region    => :lon,
    })

To learn more about obtaining cloud credentials refer to the Getting Started with Fog and the Rackspace Open Cloud document.

By default Fog::Rackspace::NetworkingV2 will authenticate against the US authentication endpoint and connect to the DFW region. You can specify alternative authentication endpoints using the key :rackspace_auth_url. Please refer to Alternate Authentication Endpoints for a list of alternative Rackspace authentication endpoints.

Alternative regions are specified using the key :rackspace_region. A list of regions available for Cloud Servers can be found by executing the following:

    identity_service = Fog::Identity({
            :provider            => 'Rackspace',                     # Rackspace Fog provider
            :rackspace_username  => RACKSPACE_USER_NAME,             # Your Rackspace Username
            :rackspace_api_key   => RACKSPACE_API,                   # Your Rackspace API key
            :rackspace_auth_url  => Fog::Rackspace::UK_AUTH_ENDPOINT # Not specified for US Cloud
    })

    identity_service.service_catalog.display_service_regions :cloudServersOpenStack

Optional Connection Parameters¶ ↑

Fog supports passing additional connection parameters to its underlying HTTP library (Excon) using the :connection_options parameter.

Key	Description
:connect_timeout	Connection timeout (default: 60 seconds)
:read_timeout	Read timeout for connection (default: 60 seconds)
:write_timeout	Write timeout for connection (default: 60 seconds)
:proxy	Proxy for HTTP and HTTPS connections
:ssl_ca_path	Path to SSL certificate authorities
:ssl_ca_file	SSL certificate authority file
:ssl_verify_peer	SSL verify peer (default: true)

Fog Abstractions¶ ↑

Fog provides both a model and request abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient ActiveModel like interface.

Request Layer¶ ↑

The request abstraction maps directly to the NetworkingV2 API. It provides the most efficient interface to the Rackspace NetworkingV2

To see a list of requests supported by the service:

    service.requests

This returns:

[:list_networks, :create_network, :show_network, :update_network, :delete_network, :list_subnets, :create_subnet, :show_subnet, :update_subnet, :delete_subnet, :list_ports, :create_port, :show_port, :update_port, :delete_port]

Example Request¶ ↑

To request a list of flavors:

    response = service.list_networks

This returns in the following Excon::Response:

      #<Excon::Response:0x007fbce39798a0 @data={:body=>{"networks"=>[{"status"=>"ACTIVE", "subnets"=>["79a2a078-84bd-4ffd-8e68-67f7854bb772"], "name"=>"Testing", "admin_state_up"=>true, "tenant_id"=>"000000", "shared"=>false, "id"=>"eff4da21-e006-4468-b9ce-798eb2fed3e8"}]}, :headers=>{"Content-Type"=>"application/json; charset=UTF-8", "Via"=>"1.1 Repose (Repose/2.12)", "Content-Length"=>"218", "Date"=>"Wed, 17 Dec 2014 19:37:49 GMT", "Server"=>"Jetty(8.0.y.z-SNAPSHOT)"}, :status=>200, :reason_phrase=>"OK", :remote_ip=>"69.20.65.143", :local_port=>63382, :local_address=>"192.168.1.80"}, @body="{\"networks\": [{\"status\": \"ACTIVE\", \"subnets\": [\"79a2a078-84bd-4ffd-8e68-67f7854bb772\"], \"name\": \"Testing\", \"admin_state_up\": true, \"tenant_id\": \"000000\", \"shared\": false, \"id\": \"eff4da21-e006-4468-b9ce-798eb2fed3e8\"}]}", @headers={"Content-Type"=>"application/json; charset=UTF-8", "Via"=>"1.1 Repose (Repose/2.12)", "Content-Length"=>"218", "Date"=>"Wed, 17 Dec 2014 19:37:49 GMT", "Server"=>"Jetty(8.0.y.z-SNAPSHOT)"}, @status=200, @remote_ip="69.20.0.0", @local_port=63382, @local_address="192.168.1.80">

To view the status of the response:

    response.status

Note: Fog is aware of valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.

To view response body:

    response.body

This will return:

      {"networks"=>[{"status"=>"ACTIVE", "subnets"=>["79a2a078-84bd-4ffd-8e68-67f7854bb772"], "name"=>"Testing", "admin_state_up"=>true, "tenant_id"=>"000000", "shared"=>false, "id"=>"eff4da21-e006-4468-b9ce-798eb2fed3e8"}]}

To learn more about NetworkingV2 request methods refer to rdoc. To learn more about Excon refer to Excon GitHub repo.

Model Layer¶ ↑

Fog models behave in a manner similar to ActiveModel. Models will generally respond to create, save, persisted?, destroy, reload and attributes methods. Additionally, fog will automatically create attribute accessors.

Here is a summary of common model methods:

Method	Description
create	Accepts hash of attributes and creates object. Note: creation is a non-blocking call and you will be required to wait for a valid state before using resulting object.
save	Saves object. Note: not all objects support updating object.
persisted?	Returns true if the object has been persisted.
destroy	Destroys object. Note: this is a non-blocking call and object deletion might not be instantaneous.
reload	Updates object with latest state from service.
ready?	Returns true if object is in a ready state and able to perform actions. This method will raise an exception if object is in an error state.
attributes	Returns a hash containing the list of model attributes and values.
identity	Returns the identity of the object. Note: This might not always be equal to object.id.
wait_for	This method periodically reloads model and then yields to specified block until block returns true or a timeout occurs.

The remainder of this document details the model abstraction.

List Networks¶ ↑

To retrieve a list of available networks:

    service.networks

This returns a collection of Fog::Rackspace::NetworkingV2::Network models:

      <Fog::Rackspace::NetworkingV2::Networks
        [
          <Fog::Rackspace::NetworkingV2::Network
            id="eff4da21-e006-4468-b9ce-798eb2fed3e8",
            admin_state_up=true,
            label=nil,
            name="Testing",
            shared=false,
            status="ACTIVE",
            subnets=["79a2a078-84bd-4ffd-8e68-67f7854bb772"],
            tenant_id="000000"
          >
        ]
      >

Create Network¶ ↑

Create a network:

            service.networks.create(label: "new_network", cidr: "192.168.0.0/24")

Get Network¶ ↑

To retrieve individual network:

      service.networks.get "eff4da21-e006-4468-b9ce-798eb2fed3e8"

This returns an Fog::Rackspace::NetworkingV2::Network instance:

      <Fog::Rackspace::NetworkingV2::Network
        id="eff4da21-e006-4468-b9ce-798eb2fed3e8",
        admin_state_up=true,
        label=nil,
        name="Testing",
        shared=false,
        status="ACTIVE",
        subnets=["79a2a078-84bd-4ffd-8e68-67f7854bb772"],
        tenant_id="000000"
      >

Delete Network¶ ↑

To delete a network:

network.destroy

Note: The network is not immediately destroyed, but it does occur shortly there after.

List Subnets¶ ↑

To retrieve a list of available subnets:

    service.subnets

This returns a collection of Fog::Rackspace::NetworkingV2::Subnet models:

      <Fog::Rackspace::NetworkingV2::Subnets
        [
          <Fog::Rackspace::NetworkingV2::Subnet
            id="79a2a078-84bd-4ffd-8e68-67f7854bb772",
            name="",
            enable_dhcp=nil,
            network_id="eff4da21-e006-4468-b9ce-798eb2fed3e8",
            tenant_id="000000",
            dns_nameservers=[],
            allocation_pools=[{"start"=>"192.168.3.1", "end"=>"192.168.3.254"}],
            host_routes=[],
            ip_version=4,
            gateway_ip=nil,
            cidr="192.168.3.0/24"
          >
        ]
      >

Create Subnet¶ ↑

Create a subnet:

      subnet = service.subnets.new({
        :name       => "ANewsubnet",
        :cidr       => "192.168.101.1/24",
        :network_id => "79a2a078-84bd-4ffd-8e68-67f7854bb772",
        :ip_version => "4"
      }).save

Get Subnet¶ ↑

To retrieve individual subnet:

      service.subnets.get "79a2a078-84bd-4ffd-8e68-67f7854bb772"

This returns an Fog::Rackspace::NetworkingV2::Subnet instance:

      <Fog::Rackspace::NetworkingV2::Subnet
        id="79a2a078-84bd-4ffd-8e68-67f7854bb772",
        name="",
        enable_dhcp=nil,
        network_id="eff4da21-e006-4468-b9ce-798eb2fed3e8",
        tenant_id="000000",
        dns_nameservers=[],
        allocation_pools=[{"start"=>"192.168.3.1", "end"=>"192.168.3.254"}],
        host_routes=[],
        ip_version=4,
        gateway_ip=nil,
        cidr="192.168.3.0/24"
      >

Delete Subnet¶ ↑

To delete a subnet:

subnet.destroy

Note: The subnet is not immediately destroyed, but it does occur shortly there after.

List Ports¶ ↑

To retrieve a list of available ports:

    service.ports

This returns a collection of Fog::Rackspace::NetworkingV2::Port models:

      <Fog::Rackspace::NetworkingV2::Ports
        [
          <Fog::Rackspace::NetworkingV2::Port
            id="79a2a078-84bd-4ffd-8e68-67f7854bb772",
            name="",
            enable_dhcp=nil,
            network_id="eff4da21-e006-4468-b9ce-798eb2fed3e8",
            tenant_id="000000",
            dns_nameservers=[],
            allocation_pools=[{"start"=>"192.168.3.1", "end"=>"192.168.3.254"}],
            host_routes=[],
            ip_version=4,
            gateway_ip=nil,
            cidr="192.168.3.0/24"
          >
        ]
      >

Create Port¶ ↑

Create a port:

      s.ports.new({name: "something", network_id: network.id}).save

      <Fog::Rackspace::NetworkingV2::Ports
        [
          <Fog::Rackspace::NetworkingV2::Port
            id="f90c5970-1bce-4403-82ee-7713854de7c7",
            admin_state_up=true,
            device_id="",
            device_owner=nil,
            fixed_ips=[{"subnet_id"=>"79a2a078-84bd-4ffd-8e68-67f7854bb772", "ip_address"=>"192.168.3.1"}],
            mac_address="BC:76:4E:20:CB:0D",
            name="something",
            network_id="eff4da21-e006-4468-b9ce-798eb2fed3e8",
            security_groups=[],
            status="ACTIVE",
            tenant_id="000000"
          >
        ]
      >

Get Port¶ ↑

To retrieve individual port:

    service.ports.get "f90c5970-1bce-4403-82ee-7713854de7c7"

This returns an Fog::Rackspace::NetworkingV2::Port instance:

      <Fog::Rackspace::NetworkingV2::Port
        id="f90c5970-1bce-4403-82ee-7713854de7c7",
        admin_state_up=true,
        device_id="",
        device_owner=nil,
        fixed_ips=[{"subnet_id"=>"79a2a078-84bd-4ffd-8e68-67f7854bb772", "ip_address"=>"192.168.3.1"}],
        mac_address="BC:76:4E:20:CB:0D",
        name="something",
        network_id="eff4da21-e006-4468-b9ce-798eb2fed3e8",
        security_groups=[],
        status="ACTIVE",
        tenant_id="000000"
      >

Delete Port¶ ↑

To delete a port:

port.destroy

Note: The port is not immediately destroyed, but it does occur shortly there after.

Examples¶ ↑

Example code using Networking can be found here.

Additional Resources¶ ↑

Support and Feedback¶ ↑

Your feedback is appreciated! If you have specific issues with the fog SDK, you should file an issue via Github.

For general feedback and support requests, send an email to: sdk-support@rackspace.com.