Skip to content

Latest commit

 

History

History
39 lines (20 loc) · 3.45 KB

design.md

File metadata and controls

39 lines (20 loc) · 3.45 KB
Raw

Design

entitlements-app is organized into a main controller class that runs as a CLI (lib/entitlements/cli.rb) which calculates memberships in all of the defined entitlements, and then calls various back ends to implement those changes. The backends which are available by default are dummy (does nothing) and ldap (manipulates LDAP groups).

The Entitlements system is meant to be pluggable. Plugins exist for these additional backends as well:

Backends

If you'd like to create a new plugin for an Entitlements backend, you'll effectively need to teach Entitlements how to create, read, update, and delete entries in that backend.

lib/entitlements/backend/<yourbackend> is where you will create file(s) for your backend. If you're just getting started, consider copying the dummy controller which has all of the methods stubbed with no actual code.

In this directory you will create:

  • controller.rb

    Your controller inherits from Entitlements::Cli::BaseController class. It contains specifically named methods that the CLI controller will call during the deployment process. Please see the comments in base_controller.rb for a list of the method signatures required (or more practically, look at one of the existing controllers). You will be overriding some or all of the following methods:

    • self.prefetch(cache) - (optional) Do something before all processing. If your backend supports a concept of "fetch everything at once so you don't have to fetch one by one later" this is a good place to fetch things and cache that result.

    • self.validate(cache) - (optional) Validate data in the cache. This should raise an error if something is wrong.

    • self.calculate(cache) - (required) This calculates differences between what's in the backend now and what should be there. The result is a list of actions which are later acted upon. This is typically delegated to lib/entitlements/data/groups/<yourbackend>.rb.

    • NOTE: If no-op mode is engaged, this is the point at which things stop.

    • self.preapply(cache) - (optional) Run any "pre-apply" steps. Example: in the LDAP provider this creates any missing OUs.

    • self.apply(cache, action) - (required) This applies a given action, so this is where you teach Entitlements to create, update, and delete entries in your backend. This method is called once per action and often delegates work to service classes in lib/entitlements/service.

  • provider.rb

    It may be helpful to treat each unique instance of your backend as a separate object (for example, the backend managing GitHub teams has one instance of the backend for each organization, since each organization might require unique credentials). Whether to use this, and how to structure it if you do, is not specified.

  • service.rb

    It may be helpful to put common methods associated with accessing an external service into a separate class. Whether to use this, and how to structure it if you do, is not specified.