Project

General

Profile

Download (7.63 KB) Statistics
| Branch: | Tag: | Revision:
243b30b6 Eric D Helms
# Runcible

11715b4b Eric D. Helms
[![Build Status](https://secure.travis-ci.org/Katello/runcible.png)](http://travis-ci.org/Katello/runcible)

Exposing Pulp's juiciest parts. http://www.pulpproject.org/
243b30b6 Eric D Helms
63540c7c Eric D. Helms
Latest Live Tested Version: **pulp-server-2.6.2-1.el7.noarch**
db369a17 Eric D. Helms
49458300 Eric D. Helms
Current stable Runcible: https://github.com/Katello/runcible/tree/0.3

83531b29 Eric D. Helms
For in-depth class and method documentation: http://katello.github.com/runcible/

ed3a37ae Eric D. Helms
Please file new issues here: [Readmine](http://projects.theforeman.org/projects/runcible/issues/new)

243b30b6 Eric D Helms
## Installation

Add this line to your application's Gemfile:

gem 'runcible'

And then execute:

$ bundle

Or install it yourself as:

$ gem install runcible

## Usage

5731e8a7 Eric D. Helms
### Set Configuration

661ca339 Justin Sherrill
To use a single resource or extension, the configuration can be set:
5731e8a7 Eric D. Helms
661ca339 Justin Sherrill
repo_api = Runcible::Resources::Repository.new({
5731e8a7 Eric D. Helms
:url => "",
:api_path => "",
:user => "",
:logger => ""
661ca339 Justin Sherrill
})
repo_api.find(id)
5731e8a7 Eric D. Helms
661ca339 Justin Sherrill
Alternatively, a single 'server' instance which can easily use all
resources and extensions can be instantiated:

my_runcible = Runcible::Instance.new({
:url => "",
:api_path => "",
:user => "",
:logger => ""
})
72db3c84 Dmitri Dolguikh
my_runcible.resources.repository.find(id)
661ca339 Justin Sherrill
Required Configuration:
5731e8a7 Eric D. Helms
:uri => The base URI of the Pulp server (default: https://localhost)
:api_path => The API path of the Pulp server (default: pulp/api/v2/)
:user => The Pulp username to be used in authentication
:logger => The location to log RestClient calls (e.g. stdout)
de6a916a Eric D. Helms
Authentication Options are either HTTP or Oauth:
5731e8a7 Eric D. Helms
:http_auth => {:password => ''}

:oauth => {:oauth_secret => "",
:oauth_key => "" }

For an example on parsing the Pulp server.conf and using values provided within for the configuration see the [test_runner](https://github.com/Katello/runcible/blob/master/test/integration/test_runner.rb)

### Make a Request

661ca339 Justin Sherrill
Runcible provides two representations of Pulp entities to make API calls: [resources](https://github.com/Katello/runcible/tree/master/lib/runcible/resources) and [extensions](https://github.com/Katello/runcible/tree/master/lib/runcible/extensions)
5731e8a7 Eric D. Helms
de6a916a Eric D. Helms
The best examples of how to use either the resources or extensions can be found within the [tests](https://github.com/Katello/runcible/tree/master/test/integration)
5731e8a7 Eric D. Helms
#### Resources

Resources are designed to be one-for-one with the Pulp API calls in terms of required parameters and naming of the calls. For example, in order to create a repository, associate a Yum importer and a distributor:

661ca339 Justin Sherrill
my_runcible = Runcible::Instance.new(config)
my_runcible.resources.repository.create("Repository_ID")
my_runcible.resources.repository.associate_importer("Repository_ID", "yum_importer", {})
my_runcible.resources.repository.associate_distributor("Repository_ID", "yum_distributor", {"relative_url" => "/", "http" => true, "https" => true})

or

Runcible::Resources::Repository.new(config).create("Repository_ID")
Runcible::Resources::Repository.new(config).associate_importer("Repository_ID", "yum_importer", {})
Runcible::Resources::Repository.new(config).associate_distributor("Repository_ID", "yum_distributor", {"relative_url" => "/", "http" => true, "https" => true})
5731e8a7 Eric D. Helms
#### Extensions

Extensions are constructs around the Pulp API that make retrieving, accessing or creating certain data types easier. For example, providing objects that represent the details of a yum importer or distributor, and providing functions to create a Repository with an importer and distributors in a single call. The same three step process above using extensions is:

661ca339 Justin Sherrill
my_runcible = Runcible::Instance.new(config)
my_runcible.extensions.repository.create_with_importer_and_distributor("Repository_ID", {:id=>'yum_importer'}, [{'type_id' => 'yum_distributor', 'id'=>'123', 'auto_publish'=>true, 'config'=>{'relative_url' => '/', 'http' => true, 'https' => true}}])

or

Runcible::Extensions::Repository.new(config).create_with_importer_and_distributors("Repository_ID", {:id=>'yum_importer'}, [{'type_id' => 'yum_distributor', 'id'=>'123', 'auto_publish'=>true, 'config'=>{'relative_url' => '/', 'http' => true, 'https' => true}}])
5731e8a7 Eric D. Helms
Alternatively, using distributor and importer objects:

661ca339 Justin Sherrill
distributors = [Runcible::Models::YumDistributor.new('/path', true, true, :id => '123')]
importer = Runcible::Models::YumImporter.new()

my_runcible = Runcible::Instance.new(config)
my_runcible.extensions.repository.create_with_importer_and_distributors("Repository_ID", importer, distributors)

or
5731e8a7 Eric D. Helms
661ca339 Justin Sherrill
Runcible::Extensions::Repository.new(config).create_with_importer_and_distributors("Repository_ID", importer, distributors)
243b30b6 Eric D Helms
12a95cc1 Justin Sherrill
## Testing

To run all tests using recorded data, run:
de6a916a Eric D. Helms
27ba8849 Justin Sherrill
rake test mode=none
12a95cc1 Justin Sherrill
To run all tests to record data:
de6a916a Eric D. Helms
e2989b74 Brad Buckingham
rake test mode=all
12a95cc1 Justin Sherrill
To run a single test using recorded data, run:
de6a916a Eric D. Helms
27ba8849 Justin Sherrill
rake test mode=none test=extensions/respository
or (by filename)
rake test mode=none test=./test/extensions/respository_test.rb
12a95cc1 Justin Sherrill
5c600f2f Eric D. Helms
To run tests against your live Pulp without recording a new cassette set record flag to false (does not apply to mode=none):

record=false

12a95cc1 Justin Sherrill
To run with oauth, simply append the following to any commend:
de6a916a Eric D. Helms
auth_type=oauth
12a95cc1 Justin Sherrill
11715b4b Eric D. Helms
To see RestClient logs while testing:
de6a916a Eric D. Helms
logging=true
12a95cc1 Justin Sherrill
dcec3cd2 Eric D Helms
## Updating Documentation
c9b73a63 Eric D. Helms
dcec3cd2 Eric D Helms
The documentation is built with yard and hosted on Github via the gh-pages branch of the repository. To update the documentation on Github:

yard doc
git checkout gh-pages
cp -rf doc/* ./
git add ./
git commit -a -m 'Updating docs to version X.X'
git push <upstream> gh-pages
c9b73a63 Eric D. Helms
## Building and Releasing

9f7ede0e Eric D Helms
An official release of Runcible should include the release of a gem on rubygems.org and an update to the documentation branch. At a minimum, the following two actions should be performed for each release:

1. [Build and Release Gem](#gem)
2. [Updating Documentation](#updating-documentation)

c9b73a63 Eric D. Helms
### Gem

While anyone can grab the source and build a new version of the gem, only those with Rubygems.org permissions on the project can release an official version.

To build a new version of Runcible, first bump the version depending on the type of release.

cd runcible/
vim lib/runcible/version.rb

Now update the version to the new version, and commit the changes.

git commit -a -m 'Version bump'

Now build:
gem build runcible.gemspec


#### Official Release
For an official release, again assuming you have the right permssions:

gem push runcible-<version>.gem

### RPM Release

If you are wanting to generate a new RPM build, please make sure you have followed the steps above if the build is going to include new code. All builds should first go in gem form to Rubygems. You'll need to make sure tito is installed:

yum install tito

Now tag, making sure the tag version matches the gem version:

tito tag

Assuming you have the right dependencies available, you can do a local test build with tito (although we recommend using mock):

tito build --test --rpm

With mock:

tito build --test --rpm --builder=mock --builder-arg mock=<name_of_mock_config>

From here there are a variety of options to build and release an RPM pakaged version of Runcible (e.g. you can build an SRPM to feed to Koji, or use mock locally)

243b30b6 Eric D Helms
## Contributing

1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
5731e8a7 Eric D. Helms
4. Ensure all tests are passing
5. Push to the branch (`git push origin my-new-feature`)
6. Create new Pull Request