ruby-pulp

A ruby gem to talk to a pulp server using its REST-api.

Pulp is juicy software repository managment and so we want to talk to it in a juicy language.

The library provides easy to use, ‘activerecord`-like objects for the different resources you can manage via Pulp’s REST-Api. So that if you for example like to create a new repository you need to do only the following:

repo = Pulp::Repository.create(
  :id => 'pulp-rhel6-x86_64',
  :name => 'Example Repository for pulp on RHEL 6 x86_64',
  :arch => 'x86_64',
  :feed => "http://repos.fedorapeople.org/repos/pulp/pulp/6Server/x86_64/",
  :relative_path => "pulp_test/#{random_id}",
  :sync_schedule => '' 
)

You can then search by any field that is allowed as search field for that repository:

Pulp::Repository.find_by_arch('x86_64').find{{|r| r.name == 'pulp-rhel6-x86_64' }
puts repo.name

Or simply get it by its id:

repo = Pulp::Repository.get('pulp-rhel6-x86_64')
puts repo.name

If you don’t like it anymore, you can simply delete it:

repo.delete

As you would know things from working with activerecord.

Disclaimer

Not all parts have already been used and tested against a real pulp server. Pulp is still a piece of software that is moving very quickly forward. So use it only with the latest pulp version, and it might be that things are broken.

Bug reports / Pull requests (including tests) are welcome! See below.

Configuration

When requiring the gem, it is looking for the environment variable PULP_YML, if it points to an existing yaml file, or whether a yaml file exist at ‘~/.pulp.yaml` or `/etc/pulp/pulp.yaml`. It then tries to configure itself with the options from that file.

However, you can also later configure the access credentils with:

Pulp::Connection::Handler.hostname = 'localhost'
Pulp::Connection::Handler.username = 'admin'
Pulp::Connection::Handler.password = 'admin'

Examples

A few examples can be found in ‘examples/`. The main one `repositories.rb` can easily be run agains a local pulp server, that does have internet connection. It will generate a new repository, clone from it, and will cleanup at the end. Give it a shot, otherwise even reading the code, might give you already an idea of how to use this gem.

Defining resources

This gem comes with a little framework behind that provides various methods to create the classes for the resources in a very declarative manner. The main idea is that a Pulp resource inherits from ‘Pulp::Connection::Base` and then declares its field and their behavior with the various class methods. These fields and actions are mainly take from the existing PULP-Api documentation: fedorahosted.org/pulp/wiki/UGRESTAPI

The idea is to make it very easy to declare the fields and actions of resources and to not let you rewrite a lot of common code to just interact with the REST-API. What follows is a short description of the most important fields.

By default we assume that the objects have an ‘id` field that is their unique identifier.

We can then define further fields of the resource, with the ‘pulp_field(s)` method. For example for a `Pulp::Repository` we can define the fields `arch`, `name`, `release`.

module Pulp
  class Repository
    ...
    pulp_fields :arch, :name, :release
    ...
  end
end

puts repo.name
repo.name = 'some other name'
repo.save # will to an UPDATE including the new name

You can also execute various actions on the different pulp resources. These actions can be declared using ‘pulp_action`:

module Pulp
  class Repository
    ...
    pulp_action :create_packagegroupcategory, :returns => Pulp::PackageGroupCategory
    pulp_action :delete_errata, :parse => false
    ...
  end
end

This means that you can use ‘repo.create_packagegroupcategory(…)` and pass it a hash of options as described in the API documentation and it will return the newly created `Pulp::PackageGroupCategory`. `repo.delete_errata(…)` will delete an errata, but won’t parse the actual result, as it might simply return ‘true’ or ‘false’. Attention: the last part might change within the near future of pulp.

A ‘pulp_update_action` can be used to describe update methods for various special (usually locked fields).

Any other methods can simple be added added using short methods, for example like, getting all the schedules or deleting a node of a repository:

module Pulp
  class Repository
    ...
    def self.schedules
      self.base_get('schedules/')
    end
    def delete_note(key)
      self.class.base_unparsed_delete("notes/#{key}/",self.id)
      refresh
      self
    end
    ...
  end
end
Pulp::Repository.schedules
repo.delete_note('some_key')

If you are unsure how certain things are used or can be added, I recommend you to A) read the pulp API docuemntation, B) read the code of this gem and C) read the pulp python code, as some things might not work as documented or are not documented at all. But the pulp maintainers are doing a really great job to get this last point fixe. Kudos to them! And they are also very happy if you point things out in the api, that does currently not work very correctly, does not follow the REST-“Standard”, is undocumented or is somehow else weird.

Contributing to ruby-pulp