sfa/managers/driver.py

   1 #
   2 # an attempt to document what a driver class should provide,
   3 # and implement reasonable defaults
   4 #
   5
   6
   7 class Driver:
   8
   9     def __init__(self, api):
  10         self.api = api
  11         # this is the hrn attached to the running server
  12         self.hrn = api.config.SFA_INTERFACE_HRN
  13
  14     ########################################
  15     # registry oriented
  16     ########################################
  17
  18     # NOTE: the is_enabled method is deprecated
  19     # it was only making things confusing, as the (PL) import mechanism would
  20     # ignore not enabled users anyway..
  21
  22     # the following is used in Resolve (registry) when run in full mode
  23     #     after looking up the sfa db, we wish to be able to display
  24     #     testbed-specific info as well
  25     # based on the principle that SFA should not rely on the testbed database
  26     # to perform such a core operation (i.e. getting rights right)
  27     # this is no longer in use when performing other SFA operations
  28     def augment_records_with_testbed_info(self, sfa_records):
  29         return sfa_records
  30
  31     # incoming record, as provided by the client to the Register API call
  32     # expected retcod 'pointer'
  33     # 'pointer' is typically an int db id, that makes sense in the testbed environment
  34     # -1 if this feature is not relevant
  35     def register(self, sfa_record, hrn, pub_key):
  36         return -1
  37
  38     # incoming record is the existing sfa_record
  39     # expected retcod boolean, error message logged if result is False
  40     def remove(self, sfa_record):
  41         return True
  42
  43     # incoming are the sfa_record:
  44     # (*) old_sfa_record is what we have in the db for that hrn
  45     # (*) new_sfa_record is what was passed in the Update call
  46     # expected retcod boolean, error message logged if result is False
  47     # NOTE 1. about keys
  48     # this is confusing because a user may have several ssh keys in
  49     # the planetlab database, but we need to pick one to generate its cert
  50     # so as much as in principle we should be able to use new_sfa_record['keys']
  51     # the manager code actually picks one (the first one), and it seems safer
  52     # to pass it along rather than depending on the driver code to do the same
  53     #
  54     # NOTE 2. about keys
  55     # when changing the ssh key through this method the gid gets changed too
  56     # should anything be passed back to the caller in this case ?
  57     def update(self, old_sfa_record, new_sfa_record, hrn, new_key):
  58         return True
  59
  60     # callack for register/update
  61     # this allows to capture changes in the relations between objects
  62     # the ids below are the ones found in the 'pointer' field
  63     # this can get typically called with
  64     # 'slice' 'user' 'researcher' slice_id user_ids
  65     # 'authority' 'user' 'pi' authority_id user_ids
  66     def update_relation(self, subject_type, target_type, relation_name, subject_id, link_ids):
  67         pass
  68
  69     ########################################
  70     # aggregate oriented
  71     ########################################
  72
  73     # a name for identifying the kind of testbed
  74     def testbed_name(self): return "undefined"
  75
  76     # a dictionary that gets appended to the generic answer to GetVersion
  77     # 'geni_request_rspec_versions' and 'geni_ad_rspec_versions' are mandatory
  78     def aggregate_version(self): return {}
  79
  80     # answer to ListResources
  81     # returns : advertisment rspec (xml string)
  82     def list_resources(self, version=None, options=None):
  83         if options is None:
  84             options = {}
  85         return "dummy Driver.list_resources needs to be redefined"
  86
  87     # the answer to Describe on a slice or a set of the slivers in a slice
  88     # returns: a struct:
  89     #{
  90     #  geni_rspec: <geni.rspec, a Manifest RSpec>
  91     #  geni_urn: <string slice urn of the containing slice>
  92     #  geni_slivers: [
  93     #              {
  94     #                geni_sliver_urn: <string sliver urn>
  95     #                geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>,
  96     #                geni_allocation_status: <string sliver state - e.g. geni_allocated or geni_provisioned >,
  97     #                geni_operational_status: <string sliver operational state>,
  98     #                geni_error: <optional string. The field may be omitted entirely but may not be null/None, explaining any failure for a sliver.>
  99     #              },
 100     #              ...
 101     #                ]
 102     #}
 103     def describe(self, urns, version, options=None):
 104         if options is None:
 105             options = {}
 106         return "dummy Driver.describe needs to be redefined"
 107
 108     # the answer to Allocate on a given slicei or a set of the slivers in a slice
 109     # returns: same struct as for describe.
 110     def allocate(self, urn, rspec_string, expiration, options=None):
 111         if options is None:
 112             options = {}
 113         return "dummy Driver.allocate needs to be redefined"
 114
 115     # the answer to Provision on a given slice or a set of the slivers in a slice
 116     # returns: same struct as for describe.
 117     def provision(self, urns, options=None):
 118         if options is None:
 119             options = {}
 120         return "dummy Driver.provision needs to be redefined"
 121
 122     # the answer to PerformOperationalAction on a given slice or a set of the slivers in a slice
 123     # returns: struct containing "geni_slivers" list of the struct returned by
 124     # describe.
 125     def perform_operational_action(self, urns, action, options=None):
 126         if options is None:
 127             options = {}
 128         return "dummy Driver.perform_operational_action needs to be redefined"
 129
 130     # the answer to Status on a given slice or a set of the slivers in a slice
 131     # returns: struct containing "geni_urn" and "geni_slivers" list of the
 132     # struct returned by describe.
 133     def status(self, urns, options=None):
 134         if options is None:
 135             options = {}
 136         return "dummy Driver.status needs to be redefined"
 137
 138     # the answer to Renew on a given slice or a set of the slivers in a slice
 139     # returns: struct containing "geni_slivers" list of the struct returned by
 140     # describe.
 141     def renew(self, urns, expiration_time, options=None):
 142         if options is None:
 143             options = {}
 144         return "dummy Driver.renew needs to be redefined"
 145
 146     # the answer to Delete on a given slice
 147     # returns: struct containing "geni_slivers" list of the struct returned by
 148     # describe.
 149     def delete(self, urns, options=None):
 150         if options is None:
 151             options = {}
 152         return "dummy Driver.delete needs to be redefined"
 153
 154     # the answer to Shutdown on a given slice
 155     # returns: boolean
 156     def shutdown(self, xrn, options=None):
 157         if options is None:
 158             options = {}
 159         return False