Latest revision as of 18:16, 14 April 2014

Proposed New Schema for Satori Discovery

We need to formalize the schema of the data returned by Satori and address some current deficiencies in it.

Some Current Deficiencies:

• Satori right now returns a haphazard list of resources, discovered data, and metadata.
• Satori right now returns a list of fixed items that it discovers (ex. DNS info, IP info, …). Some of these items may succeed and some may fail. Right now, we return the items that succeed and return errors describing what failed.
• At some point in the future, we will allow that list of items to discover to be supplied by the client or user. When that happens, we want to be able to attach results (success or error) to the individually requested items. The current schema does not support that.

Proposed Schema Example

   {
       "target": "http://somedomain.com",
       "created": "2014-03-29 09:08:08 +0000",
       "updated": "2014-03-29 09:12:02 +0000",
       "status": "SUCCESS",
       "found":  {
           "fqdn": "discovery.example.com",
           "registered-domain": "example.com",
           "ip-address": "192.168.2.23"
       },
       "resources": {
           "OS::DNS::Domain:123456": {
               ...
           },
           "OS::DNS::Record:abcdef": {
               ...
           }, ...
       }
   }

Target Key

Use Case: It would be useful to keep track of what the discovery ran against.

Schema: create a `target` key at the root.

Discovery Attributes

Use Case: We need to know when the discovery ran and other attributes about it..

Schema: create `created`, `updated`, and `status` keys at the root.

Found Items

Use Case: To hold discovered information that is not a resource and to support future use where the list of items to discover is supplied and variable, we need a keyed list of the items that we did discover.

Schema: create a `found` key at the root and place discovered data under it using the keys [that will be] supplied by the client/user.

Multiple Resources

Use Case: We need to be able to support multiple resources in a single discovery.

Schema: create a `resources` key at the root and place all resources under it. Generate a globally unique key for each.

DNS Resources

Use Case: The DNS domain and DNS records are part of the configuration. They should go under resources discovered.

Schema: add DNS Record and DNS Domain to `resources` like any other discovered resource.

Discovery Errors and Warnings

Errors

Use Case: When a discovery completes, it may have some partial errors or warnings, such as not being able to reach a specific server.

Schema: We’re going to return errors in separate dict with its own schema:

   results, errors = satori.discover(…)

• The keys of the errors dict will be the requested items that we failed to discover so that in the future we can identify which items we discovered and which we did not.
• We will return tracebacks in the error list. The caller (ex. shell.py) will determine how to parse that and display that data.
• The error messages should be clearly written to be used for end-user display.
• The original exception and tracebacks can also be added in the response.

   errors = {
       "domain-info": {“type”: "ERROR", "message": "Invalid domain name ‘foo’", "exception": Exception(...), "traceback": [...]},
       "system-info": {"type": "WARNING", "message": "The user 'john' did not have root access, so data requiring root access was not included."}
   }

Logs

Per-discovery logs will not be available separately. All logs will be written to standard python logging framework and can be redirected to a file, for example, by the calling code.