orchestrator_client 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1b2b6d87e920753f666409e3a6c91b70913137c9
+  data.tar.gz: fbd13b48bf866358c5c11242176ed0ed319b667b
+SHA512:
+  metadata.gz: f1c0eb3a348d3da0b56a29bc8457a9a98f7243d5f9c59930ef0a1edc1e0914d01bca0bbf01ce194d1b1b0495b486377478d5d5f15bbc33d1d1a07bab5afa9102
+  data.tar.gz: 4968053c6c727a79c960ce2756118572d9096675d2c3087bf59f38631f7c423c8c15b96a94821038b86c41ccdd2d1d53029977e1629d85bc412f4d4ddf73354a

data/.gitignore

@@ -0,0 +1,2 @@
+Gemfile.lock
+*.gem

data/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# How to contribute
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Fork the repository on GitHub
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work (this is almost
+definitely the master branch).
+  * To quickly create a topic branch based on master; `git branch
+    fix/master/my_contribution master` then checkout the new branch with `git
+    checkout fix/master/my_contribution`.
+  * Please avoid working directly on the
+    `master` branch.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+
+````
+    Make the example in CONTRIBUTING imperative and concrete
+
+    Without this patch applied the example commit message in the CONTRIBUTING
+    document is not a concrete example.  This is a problem because the
+    contributor is left to imagine what the commit message should look like
+    based on a description rather than an example.  This patch fixes the
+    problem by making the example concrete and imperative.
+
+    The first line is a real life imperative statement with a ticket number
+    from our issue tracker.  The body describes the behavior without the patch,
+    why this is a problem, and how the patch fixes the problem when applied.
+````
+
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+## Submitting Changes
+
+* Sign the [Contributor License Agreement](http://links.puppet.com/cla).
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository in the puppetlabs organization.
+
+# Additional Resources
+
+* [Contributor License Agreement](http://links.puppet.com/cla)
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec'
+gem 'webmock'
+
+gem 'pry'

data/LICENSE

@@ -0,0 +1,17 @@
+orchestrator_api
+
+Copyright (C) 2016 Puppet Labs Inc
+
+Puppet,Inc. can be contacted at: info@puppet.com
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

data/README.md

@@ -0,0 +1,75 @@
+# OrchestratorClient
+
+A simple client for interacting with the Orchestration Services API in Puppet Enterprise
+[Puppet orchestration API](https://docs.puppet.com/pe/latest/api_index.html#puppet-orchestrator-api)
+
+## Compatibility
+
+Currently, this client supports the "V1" endpoints shipped as part of Puppet Enterprise 2016.2.
+
+## Installation
+
+```shell
+gem install orchestrator_client
+```
+
+## Usage
+
+Requires a token with 'Orchestration' permissions. By default the token is
+expected to be at `~/.puppetlabs/token` which is the default location used by
+`puppet-access` when creating token.
+
+### initialization Settings
+
+* `service-url` **[required]** - Base URL for the location of the Orchestrator API service
+* `ca_cert` **[required]** - Path to the CA certificate file needed to verify the SSL connection to the API.
+* `token_path`- Path to a file with the RBAC token in it (defaults to `~/.puppetlabs/token`)
+* `token` - Pass directly the RBAC token, if specified the token will be used instead of a token from file.
+
+### Example
+
+```ruby
+require 'orchestrator_client'
+
+# Create a new client
+# Requires at least a server name and path to the CA certificate
+
+client = OrchestratorClient.new({
+                                'service-url' => 'https://orchestrator.example.lan:8143/orchestrator/v1',
+                                'ca_cert'     => '/path/to/cert'
+                              })
+
+## Access endpoints through the client object
+
+# Get details on all known jobs
+result = client.jobs.all
+
+# Get details on Individual jobs (job "5" in this example)
+client.jobs.details(5)
+
+# Perform an orchestrator deployment
+new_job_details = client.command.deploy('production', {'noop' => true })
+```
+
+## Tests
+
+```shell
+bundle install
+bundle exec rspec
+```
+
+## Issues & Contributions
+
+File issues or feature requests using [GitHub
+issues](https://github.com/puppetlabs/orchestrator_api-ruby/issues).
+
+If you are interested in contributing to this project, please see the
+[Contribution Guidelines](CONTRIBUTING.md)
+
+## Authors
+
+Tom Linkin <tom@puppet.com>
+
+## License
+
+See LICENSE.

data/lib/orchestrator_client.rb

@@ -0,0 +1,87 @@
+require 'net/https'
+require 'uri'
+require 'json'
+require 'openssl'
+
+class OrchestratorClient
+  require 'orchestrator_client/error'
+  require 'orchestrator_client/command'
+  require 'orchestrator_client/jobs'
+  require 'orchestrator_client/job'
+  require 'orchestrator_client/config'
+
+  attr_accessor :config
+
+  def initialize(overrides, load_files=false)
+    @config = Config.new(overrides, load_files)
+    @config.validate
+  end
+
+  def make_uri(path)
+    URI.parse("#{config.root_url}#{path}")
+  end
+
+  def create_http(uri)
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+    http.ssl_version = :TLSv1
+    http.ca_file = config['cacert']
+    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+    http
+  end
+
+  def get(location)
+    uri = make_uri(location)
+    https = create_http(uri)
+    req = Net::HTTP::Get.new(uri)
+    req['Content-Type'] = "application/json"
+    req.add_field('X-Authentication', @config.token)
+    res = https.request(req)
+
+    if res.code != "200"
+      raise OrchestratorClient::ApiError.make_error_from_response(res)
+    end
+
+    JSON.parse(res.body)
+  end
+
+  def post(location, body)
+    uri = make_uri(location)
+    https = create_http(uri)
+
+    req = Net::HTTP::Post.new(uri)
+    req['Content-Type'] = "application/json"
+    req.add_field('X-Authentication', @config.token)
+    req.body = body.to_json
+    res = https.request(req)
+
+    if res.code != "202"
+      raise OrchestratorClient::ApiError.make_error_from_response(res)
+    end
+
+    JSON.parse(res.body)
+  end
+
+  def command
+    @command ||= OrchestratorClient::Command.new(self)
+  end
+
+  def jobs
+    @jobs ||= OrchestratorClient::Jobs.new(self)
+  end
+
+  def new_job(options, type = :deploy)
+    OrchestratorClient::Job.new(self, options, type)
+  end
+
+  def run_task(options)
+    job = OrchestratorClient::Job.new(self, options, :task)
+    job.start
+    job.wait
+    job.nodes['items']
+  end
+
+  def root
+    get(url)
+  end
+end

data/lib/orchestrator_client/command.rb

@@ -0,0 +1,21 @@
+class OrchestratorClient::Command
+
+  def initialize(https)
+    @https = https
+  end
+
+  def task(options = {})
+    raise ArgumentError, 'Must pass options as a hash' unless options.is_a? Hash
+    @https.post("command/task", options)
+  end
+
+  def deploy(options = {})
+    raise ArgumentError, 'Must pass options as a hash' unless options.is_a? Hash
+    @https.post("command/deploy", options)
+  end
+
+  def stop(job_number)
+    data = {"job" => "#{job_number}"}
+    @https.post("command/stop",data)
+  end
+end

data/lib/orchestrator_client/config.rb

@@ -0,0 +1,96 @@
+require 'json'
+
+class OrchestratorClient::Config
+
+  def initialize(overrides = nil, load_files=false)
+    @overrides = overrides || {}
+    @load_files = load_files
+  end
+
+  def load_file(path)
+    File.open(path) {|f| JSON.parse(f.read)['options']}
+  end
+
+  def puppetlabs_root
+    "/etc/puppetlabs"
+  end
+
+  def global_conf
+    File.join(puppetlabs_root, 'client-tools', 'orchestrator.conf')
+  end
+
+  def user_root
+    File.join(Dir.home, '.puppetlabs')
+  end
+
+  def user_conf
+    File.join(user_root, 'client-tools', 'orchestrator.conf')
+  end
+
+  def cacert
+    "#{puppetlabs_root}/puppet/ssl/certs/ca.pem"
+  end
+
+  def defaults
+    { 'cacert' => cacert,
+      'token-file' => File.join(user_root, 'token'),
+    }
+  end
+
+  def load_config
+    config = defaults
+    if @load_files
+      if File.exists?(global_conf) && file.readable?(global_conf)
+        config = config.merge(load_file(global_conf))
+      end
+
+      if @overrides['config-file']
+        config = config.merge(load_file(@overrides['config-file']))
+      elsif File.exists?(user_conf) && File.readable?(user_conf)
+        config = config.merge(load_file(user_conf))
+      end
+    end
+
+    config.merge(@overrides)
+  end
+
+  def validate
+    if config['service-url'].nil?
+      raise OrchestratorClient::ConfigError.new("'service-url' is required in config")
+    end
+
+    if config['cacert'].nil?
+      raise  OrchestratorClient::ConfigError.new("'cacert' is required in config")
+    end
+  end
+
+  def config
+    @config ||= load_config
+  end
+
+  def overrides_only
+    @config = @overrides
+  end
+
+  def load_token
+    @config['token'] || File.open(config['token-file']) { |f| f.read }
+  end
+
+  def token
+    @token ||= load_token
+  end
+
+  def root_url
+    unless @root_url
+     url = @config['service-url']
+     url += '/' if url !~ /\/$/
+     url += 'orchestrator/v1/'
+     @root_url = url
+    end
+    @root_url
+  end
+
+  def [](key)
+    @config[key]
+  end
+end

data/lib/orchestrator_client/error.rb

@@ -0,0 +1,59 @@
+
+class OrchestratorClient::ConfigError < RuntimeError
+end
+
+class OrchestratorClient::ApiError < RuntimeError
+
+  def initialize(data,code)
+    @code = code
+    @kind = data['kind']
+    @details = data['details']
+    super(data['msg'])
+  end
+
+  def self.make_error_from_response(res)
+    begin
+      data = JSON.parse(res.body)
+    rescue
+      return OrchestratorClient::BadResponse.new("Response body was not valid JSON: #{res.body}")
+    end
+    code = res.code
+
+    case data['kind']
+    when 'puppetlabs.validators/validation-error'
+      ValidationError.new(data, code)
+    when 'puppetlabs.orchestrator/unknown-job'
+      UnknownJob.new(data, code)
+    when 'puppetlabs.orchestrator/unknown-environment'
+      UnknownEnvironment.new(data, code)
+    when 'puppetlabs.orchestrator/empty-environment'
+      EmptyEnvironment.new(data, code)
+    when 'puppetlabs.orchestrator/empty-target'
+      EmptyTarget.new(data, code)
+    when 'puppetlabs.orchestrator/dependency-cycle'
+      DependencyCycle.new(data, code)
+    when 'puppetlabs.orchestrator/puppetdb-error'
+      PuppetdbError.new(data, code)
+    when 'puppetlabs.orchestrator/query-error'
+      QueryError.new(data, code)
+    when 'puppetlabs.orchestrator/unknown-error'
+      UnknownError.new(data, code)
+    when 'puppetlabs.orchestrator/not-permitted'
+      UnauthorizedError.new(data, code)
+    else
+      OrchestratorClient::ApiError.new(data, code)
+    end
+  end
+end
+
+class OrchestratorClient::ApiError::ValidationError < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::UnknownJob < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::UnknownEnvironment < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::EmptyEnvironment < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::EmptyTarget < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::DependencyCycle < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::PuppetdbError < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::QueryError < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::UnknownError < OrchestratorClient::ApiError; end
+class OrchestratorClient::ApiError::UnauthorizedError < OrchestratorClient::ApiError; end
+class OrchestratorClient::BadResponse < RuntimeError; end

data/lib/orchestrator_client/job.rb

@@ -0,0 +1,93 @@
+class OrchestratorClient::Job
+
+  DONE_STATES = ['stopped', 'finished', 'failed']
+  DONE_EVENTS = ['job_aborted', 'job_finished']
+
+  attr_accessor :job_name, :options, :job_id
+
+  def validate_scope
+    scope = @options['scope']
+    if scope.empty
+      Raise ArgumentError 'Scope cannot be empty'
+    elif  scope['whole_environment']
+      puts 'Deprecation Warning: Whole environment behavior may not be stable'
+    end
+  end
+
+  def initialize(client, options = {}, type=:deploy)
+    @client = client
+    @options = options
+    @type = type
+  end
+
+  def start
+    case @type
+    when :deploy
+      result = @client.command.deploy(options)
+    when :task
+      result = @client.command.task(options)
+    end
+
+    @job_name = result['job']['name']
+    @job_id = result['job']['id']
+    @next_event=nil
+    @job_name
+  end
+
+  def stop
+    unless job_name
+      Raise ArgumentError "Job name not known to stop"
+    end
+  end
+
+  def assert_started?
+    Raise ArgumentError "Job is not yet started" unless @job_name
+  end
+
+  def get_details
+    assert_started?
+    @details = @client.jobs.details(@job_name)
+  end
+
+  def details
+    @details ||= get_details
+  end
+
+  def report
+    @client.jobs.report(@job_name)
+  end
+
+  def nodes
+    @client.jobs.nodes(@job_name)
+  end
+
+  # A poll the events endpoint yielding each event
+  def each_event
+    finished = false
+    start = nil
+    while !finished
+      events = @client.jobs.events(@job_name)
+      start = events['next-events']['event']
+      if events['items'].empty?
+        sleep 1
+      else
+        events['items'].each do |event|
+          finished = true if DONE_EVENTS.include?(event['type'])
+          yield event
+        end
+      end
+    end
+  end
+
+  def wait(timeout=1000)
+    counter = 0
+    while counter < timeout
+      get_details
+      if DONE_STATES.include?(details['state'])
+        return report
+      end
+      sleep 1
+      counter += 1
+    end
+  end
+end

data/lib/orchestrator_client/jobs.rb

@@ -0,0 +1,36 @@
+class OrchestratorClient::Jobs
+
+  def initialize(http)
+    @https = http
+  end
+
+  def all(limit=nil)
+    url = "jobs"
+    if limit
+      url << "?limit=#{limit}"
+    end
+
+    @https.get(url)
+  end
+
+  def details(id)
+    @https.get("jobs/#{id}")
+  end
+
+  def nodes(id)
+    @https.get("jobs/#{id}/nodes")
+  end
+
+  def report(id)
+    @https.get("jobs/#{id}/report")
+  end
+
+  def events(id, start = nil)
+    url = "jobs/#{id}/events"
+    if start
+      url << "?start=#{start}"
+    end
+
+    @https.get(url)
+  end
+end

data/lib/orchestrator_client/version.rb

@@ -0,0 +1,3 @@
+class OrchestratorClient
+  VERSION = '0.2.1'.freeze
+end

data/orchestrator_client.gemspec

@@ -0,0 +1,17 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'orchestrator_client/version'
+Gem::Specification.new do |s|
+  s.name          = 'orchestrator_client'
+  s.version       = OrchestratorClient::VERSION
+  s.summary       = "Simple Ruby client library for PE Orchestration Services"
+  s.authors       = "Puppet"
+  s.email         = 'info@puppetlabs.com'
+  s.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(spec|scripts)/})
+  end
+  s.homepage      = 'https://github.com/puppetlabs/ruby-orchestrator_api'
+  s.license       = "Apache-2.0"
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: orchestrator_client
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Puppet
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-10-04 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: info@puppetlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE
+- README.md
+- lib/orchestrator_client.rb
+- lib/orchestrator_client/command.rb
+- lib/orchestrator_client/config.rb
+- lib/orchestrator_client/error.rb
+- lib/orchestrator_client/job.rb
+- lib/orchestrator_client/jobs.rb
+- lib/orchestrator_client/version.rb
+- orchestrator_client.gemspec
+homepage: https://github.com/puppetlabs/ruby-orchestrator_api
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Simple Ruby client library for PE Orchestration Services
+test_files: []