Documentation examples are wrong and misleading creation of DSL rules

[Gilles Dubreuil]

Using ironic-inspector REST API, the rules are accessible, although initially empty, meanwhile the creation of rules fails:

$ curl -s -H "X-Auth-Token: $OS_TOKEN" http://192.0.2.1:5050/v1/rules | python -mjson.tool
{
    "rules": []
}

$ curl -s -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json" -d '{"actions": {"action": "set-attribute", "path": "/driver_info/ipmi_address", "value": "{data[inventory][bmc_address]}"}, "conditions": {"field": "node://property.path", "op": "eq", "value": "val"}, "description": "blah", "uuid": "445f0661-f059-4671-affc-cc667ec8fb68"}' http://192.0.2.1:5050/v1/types
{
  "error": { "message": "404: Not Found" }
}

ironic-inspector logs:
------------------------
Mar 31 01:06:41 undercloud.gildub.lab ironic-inspector[3926]: 2016-03-31 01:06:41.473 3926 DEBUG ironic_inspector.main [-] Returning error to client: 404: Not Found error_response /usr/lib/python2.7/site-packages/ironic_inspector/main.py:64
Mar 31 01:06:41 undercloud.gildub.lab ironic-inspector[3926]: 2016-03-31 01:06:41.473 3926 INFO werkzeug [-] 192.0.2.200 - - [31/Mar/2016 01:06:41] "POST /v1/types HTTP/1.1" 404 -
------------------------

Initial investigation shows the "/v1/rules" request with POST data doesn't even reach the api_rules block:
https://github.com/openstack/ironic-inspector/blob/master/ironic_inspector/main.py#L248

Tested:
On Liberty with:
openstack-ironic-conductor-4.2.2-4.el7ost.noarch
openstack-ironic-inspector-2.2.5-2.el7ost.noarch
python-ironicclient-0.8.1-1.el7ost.noarch
openstack-ironic-api-4.2.2-4.el7ost.noarch
openstack-ironic-common-4.2.2-4.el7ost.noarch
python-ironic-inspector-client-1.2.0-6.el7ost.noarch

Also tried above with:
openstack-ironic-inspector-3.0.1-0.20160303184238.e8ecb99.el7.centos.noarch

[Dmitry Tantsur (divius)]

Hello!

I'm not sure what you mean by http://${OS_HOST}:5050/v1/types, this /types postfix is not something we provide. Also note that conditions and actions keys should be lists of dicts. Please see http://docs.openstack.org/developer/ironic-inspector/http-api.html for details. You can also use the client source code as reference: https://github.com/openstack/python-ironic-inspector-client/blob/master/ironic_inspector_client/v1.py#L179-L208

Let us know if that worked.

[Gilles Dubreuil (gdubreui)]

Never mind OS_HOST, it's the IP address of inspector enpoint, I've replaced the value and the revisited the bug's description.

I've been following API [1] and rules [2] documentations.

[1] http://docs.openstack.org/developer/ironic-inspector/http-api.html
[2] http://docs.openstack.org/developer/ironic-inspector/usage.html#rules

It seems conditions and actions keys cannot be Python list of dicts because JSON data is expected.
Unless there is an undocumented way to wrap them.
Whether using REST API or OSC (OpenStack client), both require the data in a JSON format.

Given the following file, following recommended format:
-------------rules-list-of-dicts-format.json--------------
{
  "description": "Just fails",
  "actions": [ { 'action': 'fail', 'message': 'Failure' } ],
  "conditions": [ {'field': 'data://introspection.path', 'op': 'eq', 'value': 'val'} ]
}
-------------rules-list-of-dicts-format.json--------------

It gets rejected by OSC import:
$ openstack baremetal introspection rule import rules-list-of-dicts-format.json
Expecting property name: line 3 column 18 (char 49)

Using REST API, the file get rejected because it's not a JSON format.

Now after replacing the single quotes in double quotes:
-------------rules-pure-json.json--------------
{
  "description": "Just fail",
  "actions": [
    { "action": "fail",
      "message": "Failure"
    }
  ],
  "conditions": [
    { "field": "data://introspection.path",
      "op": "eq",
      "value": "val"
    }
  ]
}
-------------rules-pure-json.json--------------

OSC fails further:
$ openstack baremetal introspection rule import rules-pure-json.json
Unable to parse field JSON path data://introspection.path: Parse error at 1:4 near token : (:)

Same error when injecting rules-pure-json.json above to API via POST:
Excon::Errors::BadRequest: Expected(202) <=> Actual(400 Bad Request)
excon.error.response
  :body => "{\n \"error\": {\n \"message\": \"Unable to parse field JSON path data://introspection.path: Parse error at 1:4 near token : (:)\"\n }\n}"

Also I cannot get curl to work using any of those two formating

$ curl -s -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json" -d "{\"description\":\"Just fail\",\"actions\":[{action':'fail','message':'Failure'}],\"conditions\":[{'field':'data://introspection.path','op':'eq','value':'val'}]}" http://${OS_HOST}:5050/v1/types
{
  "error": {
    "message": "404: Not Found"
  }

$ curl -s -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json" -d '{"description":"Just fail","actions":[{"actio":"fail","message":"Failure"}],"conditions":[{"field":"data://introspection.path","op":"eq","value":"val"}]}' http://${OS_HOST}:5050/v1/types
{
  "error": {
    "message": "404: Not Found"
  }

Sorry but not very exciting results.

[Gilles Dubreuil (gdubreui)]

Ok, just realized I had "types" instead of "rules" in the curl commands.
So the curl commands are consistent with using OSC or either API.
But submitting types still doesn't work no matter the approach used.

$ curl -s -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json" -d @rules-list-of-dicts-format.json http://192.0.2.1:5050/v1/rules | python -mjson.tool
{
    "error": {
        "message": "400: Bad Request"
    }
}

$ curl -s -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json"-d @rules-pure-json.json http://192.0.2.1:5050/v1/rules | python -mjson.tool
{
    "error": {
        "message": "Unable to parse field JSON path data://introspection.path: Parse error at 1:4 near token : (:)"
    }
}

[Dmitry Tantsur (divius)]

Please start with validating your file through 'jq' utility, e.g.

 jq . rules-list-of-dicts-format.json

last time I checked JSON did not support single '

Here is the file we test in gate: https://github.com/openstack/ironic-inspector/blob/master/devstack/exercise.sh#L12-L36 (note that CLI supports several rules per request, but API does not, so the top-level item should be a dict)

[Gilles Dubreuil (gdubreui)]

The JSON are valid.
I think there are a couple of issues, the examples provided in the documentation [1] are wrong because:

1- They contains single quotes like if we're dealing with Python dicts.
This cause trouble because JSON doesn't like it.
Actually with double quotes the "actions" and "conditions" fields are perfectly valid JSON list as well (as Dicts).

2- The content doesn't necessarily work (DSL contraints).
It's working fine with the example used in gate test provided.

I propose to change the documentation accordingly.
Therefore change the title of this bug.

[1] http://docs.openstack.org/developer/ironic-inspector/usage.html#rules

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/314953

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/314953
Committed: https://git.openstack.org/cgit/openstack/ironic-inspector/commit/?id=ef8033679639854b1e86f0dbcda3088f96333f80
Submitter: Jenkins
Branch: master

commit ef8033679639854b1e86f0dbcda3088f96333f80
Author: Sam Betts <email address hidden>
Date: Wed May 11 11:25:50 2016 +0100

    Ensure rules documentation examples are valid JSON

    Current documentation uses python syntax to explain the structure of the
    introspection rules, this is misleading as we're actually expecting JSON
    input on the rules API. This patch converts all rule examples to use
    JSON syntax to prevent confusion.

    Change-Id: If442fe5db8484900a5bd688e02d77d5bed69b326
    Closes-Bug: #1564238

[Doug Hellmann (doug-hellmann)]

This issue was fixed in the openstack/ironic-inspector 3.3.0 release.