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, please visit: developer.rackspace.com/support.