f5-icontrol 0.2.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '079f80f372c7d031cc361e3d1cacc3c04329c243'
-  data.tar.gz: 8eab333591c73ee9515a4235b80a88b81598ba40
+  metadata.gz: 6ab74fd490e1b266c571be1645b623203f869e83
+  data.tar.gz: 956cab3ba87c5cbc478d3404c78a9808668ac526
 SHA512:
-  metadata.gz: a26d7a1280542e2200747bce5c3c2d9fbfffc92eef05791d5025f6bb8bbb765e3d66303dd3c5198a779a92f76b0a92405b7c1642ff10505ab1372095a0e6d798
-  data.tar.gz: 938eda0411523fe63108e09f9931d63c11ebb1141cc6f39619bcd1ff6158073d5a8afc3375e431d24af170cf0cd5c7fe8aa0a4799092fd1ced16fa2f0b4b77d8
+  metadata.gz: d6c6c35ce03680285ee8a035ba9bbd8b35b0cdb2a8591bb1305357ba16d5ceb0e3d63969d8666b2a6905135f86646f4d1124e8433be049935244ff557e24b913
+  data.tar.gz: a3eeaddfeed7c3a38b471e8d5ead2887100f94079a56ee1ba4c0461cf71122202784aac473b2d583a339f3776ee206f01a44f54f7cc1d7e9b30f1006c815f5f0

data/.gitignore

@@ -16,3 +16,7 @@ test/tmp
 test/version_tmp
 tmp
 *.swp
+.direnv
+.envrc
+
+test.rb

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/swalberg/f5-icontrol.svg?branch=master)](https://travis-ci.org/swalberg/f5-icontrol)
 
-This is the F5-control gem. If you have an F5, it can use the iControl SOAP interface to automate things
+This is the F5-icontrol gem. If you have an F5, it can use the iControl API to automate things
 
 This is not the official library. That one is [here](https://devcentral.f5.com/d/icontrol-ruby-library). This copy is without warranty. Heck, it probably doesn't even work.
 
@@ -13,7 +13,7 @@ I originally set out to improve the official one:
 * Support Ruby 2.0.0 and 2.1.0
 * Make the interface to the library more Ruby-esque
 
-But given the original one was pretty bare-bones, I started over.
+But given the original one was pretty bare-bones, I started over. 
 
 ## Installation
 
@@ -29,7 +29,64 @@ Or install it yourself as:
 
     $ gem install f5-icontrol
 
-## Usage
+## Usage (REST interface)
+
+*NOTE:* The REST interface is still a work in progress! The conventions may change until we release.
+
+First configure an instance of the API to point to your F5
+
+```Ruby
+require 'f5/icontrol'
+
+f5 = F5::Icontrol::RAPI.new username: 'admin', password: 'admin', host: '10.1.1.1'
+```
+
+After that, the calls should line up directly to the [API Docs](https://devcentral.f5.com/wiki/iControlREST.APIRef.ashx). For collections, use the following methods:
+
+| HTTP Verb | Method         |
+|-----------|----------------|
+| GET       | get_collection |
+
+Note that `get_collection` is optional if you call `#each` or some `Enumberable` method. So `foo.get_collection.each` can be shortened to `foo.each`.
+
+For resources
+
+| HTTP Verb | Method         |
+|-----------|----------------|
+| GET       | load           |
+| PUT       | update         |
+| DELETE    | delete         |
+| POST      | create         |
+
+
+For example, to get all the pools:
+
+```Ruby
+pools = f5.mgmt.tm.ltm.pool.get_collection
+
+puts pools.map(&:name)
+
+# shorter method
+puts f5.mgmt.tm.ltm.pool.map(&:name)
+```
+
+It'll also understand subresources:
+
+```Ruby
+members = pools.members.load
+puts members.map(&:address)
+
+```
+
+Or, let's create a pool:
+
+```Ruby
+api.mgmt.tm.ltm.pool.create(name: 'seanstestrest')
+```
+
+## Usage (SOAP interface)
+
+*Note* - SOAP will likely be deprecated prior to version 1.0 of this gem. The REST interface is more intuitive and dropping SOAP makes this gem so much lighter.
 
 First, configure the gem:
 

data/f5-icontrol.gemspec

@@ -19,13 +19,16 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "savon", "~> 2.0"
+  spec.add_dependency "rest-client"
   spec.add_dependency "thor"
+  spec.add_dependency "rack", "~> 1.6.4"
+  spec.add_dependency "json"
 
   spec.add_development_dependency "awesome_print"
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "byebug"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "webmock", "~> 2.1.0"
   spec.add_development_dependency "vcr"
-  spec.add_development_dependency "webmock"
 end

data/lib/f5/icontrol.rb

@@ -1,4 +1,5 @@
 require "f5/icontrol/version"
+require "f5/icontrol/rapi"
 require "f5/icontrol/api"
 require 'f5/icontrol/common/enabled_state'
 require 'f5/icontrol/common/enum_item'
@@ -9,6 +10,7 @@ require 'f5/icontrol/locallb/enabled_status'
 require 'f5/icontrol/locallb/profile_context_type'
 require 'f5/icontrol/locallb/profile_type'
 require 'f5/icontrol/locallb/server_ssl_certificate_mode'
+require 'f5/icontrol/rapi/resource'
 require "openssl"
 require "savon"
 

data/lib/f5/icontrol/rapi.rb

@@ -0,0 +1,72 @@
+require 'rest-client'
+require 'json'
+
+module F5
+  module Icontrol
+    class RAPI
+      include Enumerable
+
+      def initialize(method_chain = nil, **args)
+        @method_chain = method_chain || ''
+        @args = args
+      end
+
+      def load(resource = nil)
+        tail = resource.nil? ? '' : "/#{resource}"
+        response = RestClient::Request.execute(method: :get,
+                                               url: "#{url}#{tail}",
+                                               user: @args[:username],
+                                               password: @args[:password],
+                                               verify_ssl: OpenSSL::SSL::VERIFY_NONE
+                                           )
+        object = JSON.parse response.body
+
+        if object.has_key? 'items'
+          object['items'].map { |r| Resource.new r, @args }
+        else
+          Resource.new object, @args
+        end
+      end
+
+      def get_collection
+        response = RestClient::Request.execute(method: :get,
+                                               url: "#{url}/",
+                                               user: @args[:username],
+                                               password: @args[:password],
+                                               verify_ssl: OpenSSL::SSL::VERIFY_NONE
+                                           )
+        objects = JSON.parse response.body
+
+        objects['items'].map { |r| Resource.new r, @args }
+      end
+
+      def create(options = {})
+        response = RestClient::Request.execute(method: :post,
+                                               url: url,
+                                               user: @args[:username],
+                                               password: @args[:password],
+                                               verify_ssl: OpenSSL::SSL::VERIFY_NONE,
+                                               payload: options.to_json,
+                                               headers: { "content-type" => "application/json" }
+                                              )
+        JSON.parse response.body
+      end
+
+      def method_missing(method, *args, &block)
+        new_method_chain = @method_chain == '/' ? '': "#{@method_chain}/"
+        F5::Icontrol::RAPI.new("#{new_method_chain}#{method}", @args)
+      end
+
+      def each(&block)
+        get_collection.each &block
+      end
+
+      private
+      def url
+        method_chain = @method_chain.gsub /_/, '-'
+        method_chain.gsub! %r{^/}, ''
+        "https://#{@args[:host]}/#{method_chain}"
+      end
+    end
+  end
+end

data/lib/f5/icontrol/rapi/resource.rb

@@ -0,0 +1,25 @@
+module F5
+  module Icontrol
+    class RAPI
+      class Resource
+        def initialize(args, credentials)
+          @args = args
+          @credentials = credentials
+        end
+
+        def method_missing(method, *args, &block)
+          if @args.key? method.to_s
+            return @args[method.to_s]
+          end
+
+          potential_collection = "#{method}Reference"
+          if @args.key? potential_collection
+            link = @args[potential_collection]["link"]
+            link.gsub! /^http?s:\/\/localhost\//, ""
+            return F5::Icontrol::RAPI.new(link, @credentials)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/f5/icontrol/version.rb

@@ -1,5 +1,5 @@
 module F5
   module Icontrol
-    VERSION = '0.2.7'
+    VERSION = '0.3.0'
   end
 end

data/spec/models/rapi/resource_spec.rb

@@ -0,0 +1,24 @@
+require 'spec_helper'
+
+describe F5::Icontrol::RAPI::Resource do
+  subject { described_class.new pool, {} }
+  describe "#initialize" do
+  end
+
+  describe "get attribute" do
+    it 'returns an attribute that exists' do
+      expect(subject.ipTosToServer).to eq 'pass-through'
+    end
+  end
+
+  describe "get subcollection" do
+    it 'returns an api reference' do
+      expect(subject.members).to be_an_instance_of F5::Icontrol::RAPI
+    end
+  end
+
+  def pool
+    JSON.parse '{"kind":"tm:ltm:pool:poolstate","name":"reallybasic","partition":"Common","fullPath":"/Common/reallybasic","generation":845,"selfLink":"https://localhost/mgmt/tm/ltm/pool/~Common~reallybasic?ver=11.5.1","allowNat":"yes","allowSnat":"yes","ignorePersistedWeight":"disabled","ipTosToClient":"pass-through","ipTosToServer":"pass-through","linkQosToClient":"pass-through","linkQosToServer":"pass-through","loadBalancingMode":"round-robin","minActiveMembers":0,"minUpMembers":0,"minUpMembersAction":"failover","minUpMembersChecking":"disabled","queueDepthLimit":0,"queueOnConnectionLimit":"disabled","queueTimeLimit":0,"reselectTries":0,"slowRampTime":10,"membersReference":{"link":"https://localhost/mgmt/tm/ltm/pool/~Common~reallybasic/members?ver=11.5.1","isSubcollection":true}}'
+  end
+end
+

data/spec/models/rapi_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe F5::Icontrol::RAPI do
+  let(:host) { 'somehost' }
+  let(:username) { 'me' }
+  let(:password) { 'secret' }
+  let(:base64) { Base64.encode64("#{username}:#{password}") }
+
+  let(:baseurl) { "https://#{host}" }
+
+  before(:all) { VCR.turn_off! }
+
+  subject { F5::Icontrol::RAPI.new(username: username, password: password, host: host) }
+
+  describe "asking for a collection" do
+    context "collections" do
+      it "calls the url based on the method chain" do
+        stub_request(:get, "#{baseurl}/foo/bar/").
+          to_return(body: pool_collection)
+        subject.foo.bar.get_collection
+        expect(WebMock).to have_requested(:get, "#{baseurl}/foo/bar/")
+      end
+
+      it "returns an array of resources" do
+        stub_request(:get, "#{baseurl}/foo/bar/").
+          to_return(body: pool_collection)
+
+        bars = subject.foo.bar.get_collection
+
+        expect(bars).to be_an_instance_of(Array)
+        expect(bars.first).to be_an_instance_of(F5::Icontrol::RAPI::Resource)
+      end
+
+      it "converts underscores to dashes in the call" do
+        stub_request(:get, "#{baseurl}/foo-bar/").
+          to_return(body: pool_collection)
+
+        subject.foo_bar.get_collection
+
+        expect(WebMock).to have_requested(:get, "#{baseurl}/foo-bar/")
+      end
+
+      it "understands `each` implicitly calls `get_collection`" do
+        stub_request(:get, "#{baseurl}/foo/bar/").
+          to_return(body: pool_collection)
+
+        bars = subject.foo.bar.each
+
+        expect(bars).to be_an_instance_of(Enumerator)
+      end
+
+      it "handles a block passed to an enumerable method" do
+        stub_request(:get, "#{baseurl}/foo/bar/").
+          to_return(body: pool_collection)
+
+        pools = subject.foo.bar.map(&:name)
+
+        expect(pools).to eq %w{reallybasic reallybasic2}
+      end
+    end
+
+    context "subcollections" do
+      it "resolves the url based on the method chain and object id" do
+        stub_request(:get, "#{baseurl}/mgmt/tm/ltm/pool/").
+          to_return(body: pool_collection)
+
+        pools = subject.mgmt.tm.ltm.pool.get_collection
+
+        stub_request(:get, "#{baseurl}/mgmt/tm/ltm/pool/~Common~reallybasic/members?ver=11.5.1/").
+          to_return(body: pool_collection)
+
+        pool = pools.first.members.get_collection
+
+        expect(WebMock).to have_requested(:get, "#{baseurl}/mgmt/tm/ltm/pool/~Common~reallybasic/members?ver=11.5.1/")
+      end
+
+    end
+  end
+
+  describe 'creating a new resource' do
+    before do
+      stub_request(:post, "#{baseurl}/mgmt/tm/ltm/pool").
+        with(body: /"name":"foobar"/, headers: { "Content-Type" => "application/json" }).
+        to_return(body: new_pool_response)
+    end
+
+    it 'posts to the api' do
+      new_pool = subject.mgmt.tm.ltm.pool.create(name: 'foobar')
+      expect(WebMock).to have_requested(:post, "#{baseurl}/mgmt/tm/ltm/pool")
+    end
+
+    it 'returns the hash containing the data' do
+      new_pool = subject.mgmt.tm.ltm.pool.create(name: 'foobar')
+
+      expect(new_pool).to be_an_kind_of Hash
+    end
+  end
+
+  def pool_collection
+    '{"kind":"tm:ltm:pool:poolcollectionstate","selfLink":"https://localhost/mgmt/tm/ltm/pool?ver=11.5.1","items":[{"kind":"tm:ltm:pool:poolstate","name":"reallybasic","partition":"Common","fullPath":"/Common/reallybasic","generation":845,"selfLink":"https://localhost/mgmt/tm/ltm/pool/~Common~reallybasic?ver=11.5.1","allowNat":"yes","allowSnat":"yes","ignorePersistedWeight":"disabled","ipTosToClient":"pass-through","ipTosToServer":"pass-through","linkQosToClient":"pass-through","linkQosToServer":"pass-through","loadBalancingMode":"round-robin","minActiveMembers":0,"minUpMembers":0,"minUpMembersAction":"failover","minUpMembersChecking":"disabled","queueDepthLimit":0,"queueOnConnectionLimit":"disabled","queueTimeLimit":0,"reselectTries":0,"slowRampTime":10,"membersReference":{"link":"https://localhost/mgmt/tm/ltm/pool/~Common~reallybasic/members?ver=11.5.1","isSubcollection":true}},{"kind":"tm:ltm:pool:poolstate","name":"reallybasic2","partition":"Common","fullPath":"/Common/reallybasic2","generation":819,"selfLink":"https://localhost/mgmt/tm/ltm/pool/~Common~reallybasic2?ver=11.5.1","allowNat":"yes","allowSnat":"yes","ignorePersistedWeight":"disabled","ipTosToClient":"pass-through","ipTosToServer":"pass-through","linkQosToClient":"pass-through","linkQosToServer":"pass-through","loadBalancingMode":"round-robin","minActiveMembers":0,"minUpMembers":0,"minUpMembersAction":"failover","minUpMembersChecking":"disabled","queueDepthLimit":0,"queueOnConnectionLimit":"disabled","queueTimeLimit":0,"reselectTries":0,"slowRampTime":10,"membersReference":{"link":"https://localhost/mgmt/tm/ltm/pool/~Common~reallybasic2/members?ver=11.5.1","isSubcollection":true}}]}'
+  end
+
+  def new_pool_response
+    '{"kind":"tm:ltm:pool:poolstate","name":"foobar","fullPath":"foobar","generation":848,"selfLink":"https://localhost/mgmt/tm/ltm/pool/foobar?ver=11.5.1","allowNat":"yes","allowSnat":"yes","ignorePersistedWeight":"disabled","ipTosToClient":"pass-through","ipTosToServer":"pass-through","linkQosToClient":"pass-through","linkQosToServer":"pass-through","loadBalancingMode":"round-robin","minActiveMembers":0,"minUpMembers":0,"minUpMembersAction":"failover","minUpMembersChecking":"disabled","queueDepthLimit":0,"queueOnConnectionLimit":"disabled","queueTimeLimit":0,"reselectTries":0,"slowRampTime":10,"membersReference":{"link":"https://localhost/mgmt/tm/ltm/pool/~Common~foobar/members?ver=11.5.1","isSubcollection":true}}'
+  end
+end

data/spec/spec_helper.rb

@@ -1,4 +1,5 @@
 require 'f5/icontrol'
+require 'webmock/rspec'
 require 'vcr'
 
 RSpec.configure do |c|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: f5-icontrol
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.3.0
 platform: ruby
 authors:
 - Sean Walberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-05 00:00:00.000000000 Z
+date: 2017-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: savon
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +52,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.4
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: awesome_print
   requirement: !ruby/object:Gem::Requirement
@@ -109,21 +151,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: vcr
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
-  name: webmock
+  name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -165,6 +207,8 @@ files:
 - lib/f5/icontrol/locallb/profile_type.rb
 - lib/f5/icontrol/locallb/server_ssl_certificate_mode.rb
 - lib/f5/icontrol/locallb/virtual_server/source_address_translation.rb
+- lib/f5/icontrol/rapi.rb
+- lib/f5/icontrol/rapi/resource.rb
 - lib/f5/icontrol/version.rb
 - lib/wsdl/ASM.LoggingProfile.wsdl
 - lib/wsdl/ASM.ObjectParams.wsdl
@@ -443,6 +487,8 @@ files:
 - spec/cassettes/F5_Icontrol_System_SystemInfo/retrieves_the_version.yml
 - spec/cli/pool_spec.rb
 - spec/models/api_spec.rb
+- spec/models/rapi/resource_spec.rb
+- spec/models/rapi_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/swalberg/f5-icontrol
 licenses:
@@ -464,7 +510,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A gem to manage F5 BigIP devices using the iControl API
@@ -475,4 +521,6 @@ test_files:
 - spec/cassettes/F5_Icontrol_System_SystemInfo/retrieves_the_version.yml
 - spec/cli/pool_spec.rb
 - spec/models/api_spec.rb
+- spec/models/rapi/resource_spec.rb
+- spec/models/rapi_spec.rb
 - spec/spec_helper.rb