openstack/deb-python-pycadf
Code Issues Proposed changes

Merge "Additional doc clean up"

Browse Source
This commit is contained in:
Jenkins 2015-02-24 18:39:09 +00:00 committed by Gerrit Code Review
commit 88a4650133
11 changed files with 299 additions and 240 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

166
doc/source/event_concept.rst
View File

@ -72,7 +72,7 @@ Event Attribute Value Reason
eventType activity OBSERVER is required to report any user security activity
observer.typeURI service/security/identity Value from the CADF Resource Taxonomy most closely describes an "Identity Manager Service"
initiator.typeURI data/security/account/user Value from the CADF Resource Taxonomy most closely describes a "user"
action authenticate/logon Value from the CADF Action Taxonomy most closely describes a user "logon" action.
action authenticate/logon Value from the CADF Action Taxonomy most closely describes a user "logon" action.
target.typeURI service/compute/node Value from the CADF Resource Taxonomy most closely describes a target "server"
outcome success Any valid CADF Outcome Taxonomy value that describes result of action
measurement N/A A MEASUREMENT component is not required for "activity" type events.
@ -80,44 +80,78 @@ REASON N/A A REASON component is not required
================= ========================== ==========================================================================================
Event serialisation (including some optional attributes for additional
details)::
details):
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"eventTime": "2014-02-27T19:29:30.855665+0000",
"target": {
"typeURI": "service/compute/node",
# optional Endpoints to describe compute node
"addresses": [{"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "admin"},
{"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "private"},
{"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "public"}],
"id": "openstack:06747855d62547d4bfd707f75b8a1c54",
"name": "nova"},
"observer": {"id": "target"}, # shortform to show Observer Resource is the same as Target
# tags use to query events on
"tags": ["correlation_id?value=openstack:56cdde6f-6b4e-48a4-94e6-defb40522fb2"],
"eventType": "activity",
"initiator": {
"typeURI": "data/security/account/user",
"name": "admin",
# optional Credential to describe resource
"credential": {"token": "MIIQzgYJKoZIhvcNAQcCoIIQvzCCELsC xxxxxxxx zqvD9OPWZm7VQpYNK2EvrZi-mTvb5A==",
"identity_status": "Confirmed"},
# optional Host to describe resource
"host": {"agent": "python-novaclient", "address": "9.26.26.250"},
"project_id": "openstack:e7e2bcc9c0df4f3eabcd412ae62503f6",
"id": "openstack:68a3f50705a54f799ce94380fc02ed8a"},
# optional Reason for activity event
"reason": {"reasonCode": "200", "reasonType": "HTTP"},
# list of Resources which edited event
"reporterchain": [{"reporterTime": "2014-02-27T19:29:31.043902+0000",
"role": "modifier",
"reporter": {"id": "target"}}],
"action": "authenticate/logon",
"outcome": "success",
"id": "openstack:0a196053-95de-48f8-9890-4527b25b5007",
# Event model is extensible so additional attributes may be added to describe model
"requestPath": "/v2/e7e2bcc9c0df4f3eabcd412ae62503f6/os-certificates"}
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"eventTime": "2014-02-27T19:29:30.855665+0000",
"target": {
"typeURI": "service/compute/node",
# optional Endpoints to describe compute node,
"addresses": [
{
"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6",
"name": "admin"
},
{
"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6",
"name": "private"
},
{
"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6",
"name": "public"
}
],
"id": "openstack:06747855d62547d4bfd707f75b8a1c54",
"name": "nova"
},
"observer": {
"id": "target" # shortform to show Observer Resource is the same as Target,
},
# tags use to query events on,
"tags": [
"correlation_id?value=openstack:56cdde6f-6b4e-48a4-94e6-defb40522fb2"
],
"eventType": "activity",
"initiator": {
"typeURI": "data/security/account/user",
"name": "admin",
# optional Credential to describe resource,
"credential": {
"token": "MIIQzgYJKoZIhvcNAQcCoIIQvzCCELsC xxxxxxxx zqvD9OPWZm7VQpYNK2EvrZi-mTvb5A==",
"identity_status": "Confirmed"
},
# optional Host to describe resource,
"host": {
"agent": "python-novaclient",
"address": "9.26.26.250"
},
"project_id": "openstack:e7e2bcc9c0df4f3eabcd412ae62503f6",
"id": "openstack:68a3f50705a54f799ce94380fc02ed8a"
},
# optional Reason for activity event,
"reason": {
"reasonCode": "200",
"reasonType": "HTTP"
},
# list of Resources which edited event,
"reporterchain": [
{
"reporterTime": "2014-02-27T19:29:31.043902+0000",
"role": "modifier",
"reporter": {
"id": "target"
}
}
],
"action": "authenticate/logon",
"outcome": "success",
"id": "openstack:0a196053-95de-48f8-9890-4527b25b5007",
# Event model is extensible so additional attributes may be added to describe model,
"requestPath": "/v2/e7e2bcc9c0df4f3eabcd412ae62503f6/os-certificates"
}
2. Periodic monitoring resource status
@ -145,30 +179,40 @@ measurement 80% MEASUREMENT component is required and t
reason N/A REASON component is not required for "monitor" type events.
================= ====================== ==========================================================================================
Event serialisation::
Event serialisation:
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"eventTime": "2014-02-27T19:29:30.855665+0000",
"target": {
"typeURI": "service/compute/cpu",
"id": "openstack:06747855d62547d4bfd707f75b8a1c54",
"name": "instance"},
"observer": {"id": "initiator"},
"eventType": "monitor",
"initiator": {
"typeURI": "service/oss/monitoring",
"name": "ceilometer-pollster",
"id": "openstack:68a3f50705a54f799ce94380fc02ed8a"},
"measurement": [{
"result": "80",
"metric": {"metricId": "openstack:<metric_id>",
"unit": "%",
"name": "CPU utilisation metric"}
}]
"action": "monitor",
"outcome": "success",
"id": "openstack:0a196053-95de-48f8-9890-4527b25b5007"}
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"eventTime": "2014-02-27T19:29:30.855665+0000",
"target": {
"typeURI": "service/compute/cpu",
"id": "openstack:06747855d62547d4bfd707f75b8a1c54",
"name": "instance"
},
"observer": {
"id": "initiator"
},
"eventType": "monitor",
"initiator": {
"typeURI": "service/oss/monitoring",
"name": "ceilometer-pollster",
"id": "openstack:68a3f50705a54f799ce94380fc02ed8a"
},
"measurement": [
{
"result": "80",
"metric": {
"metricId": "openstack:<metric_id>",
"unit": "%",
"name": "CPU utilisation metric"
}
}
]"action": "monitor",
"outcome": "success",
"id": "openstack:0a196053-95de-48f8-9890-4527b25b5007"
}
.. note::

32
doc/source/specification/attachments.rst
View File

@ -20,9 +20,9 @@
============
An attachment is a container for data or "content" that may follow any
structure – from an atomic type to a complex hierarchy. However, it is
desirable for processing and interoperability that the type – or
structure – of the content be identified by a simple value. To this end the
structure - from an atomic type to a complex hierarchy. However, it is
desirable for processing and interoperability that the type - or
structure - of the content be identified by a simple value. To this end the
attachment also contains a "content type", i.e., a URI that identifies the
kind of content.
@ -40,19 +40,19 @@ contentType xs:string Yes An optional name that can be used to provide an i
Serialisation
=============
json::
.. code-block:: javascript
{
...,
"attachments": [
{
"content": "xs:any",
"contentType": "xs:anyURI"
},
{
"content": "xs:any",
"contentType": "xs:anyURI"
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"attachments": [
{
"content": "xs:any",
"contentType": "xs:anyURI"
},
{
"content": "xs:any",
"contentType": "xs:anyURI"
}
]
}
]
}

31
doc/source/specification/credentials.rst
View File

@ -21,7 +21,7 @@
This type provides a means to describe various credentials along with any
information about the authority that is responsible for maintaining them.
This is intended to be associated with a CADF Resource’s identity and reflects
This is intended to be associated with a CADF Resource's identity and reflects
any authorizations or identity assertions the resource may use to gain access
to other resources.
@ -37,20 +37,19 @@ assertions cadf:Map No Optional list of additional assertions or attribut
Serialisation
=============
json::
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"action": "authenticate",
...,
"initiator": {
"id": "joe.user@tenant1.com",
"typeURI": "data/security/account/user",
...,
"credential": {
"type": "https://mycloud.com/v2/token",
"token": "myuuid:1ef0-abdf-xxxx-xxxx"
}
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"action": "authenticate",
...,
"initiator": {
"id": "joe.user@example.com",
"typeURI": "data/security/account/user",
...,
"credential": {
"type": "https://mycloud.com/v2/token",
"token": "myuuid:1ef0-abdf-xxxx-xxxx"
}
}
}
}

32
doc/source/specification/endpoints.rst
View File

@ -33,21 +33,21 @@ port xs:string No An optional property to provide the port value separ
Serialisation
=============
json::
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"target": {
"id": "myscheme://mydomain/resource/id/0001",
"name": "server_0001",
"addresses": [{
"name": "public",
"url": "http://mydomain/mypath/server-0001/"
},
...
],
...
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"target": {
"id": "myscheme://mydomain/resource/id/0001",
"name": "server_0001",
"addresses": [
{
"name": "public",
"url": "http://mydomain/mypath/server-0001/"
},
...
],
...
}
}
}

106
doc/source/specification/events.rst
View File

@ -20,7 +20,7 @@
=======
The CADF Event Model applies semantics to the activities, resources,
information, and changes within a cloud provider’s infrastructure and models
information, and changes within a cloud provider's infrastructure and models
these using the concept of an event.
============= =================== ========= =============================================================================================================================================================
@ -50,47 +50,65 @@ reporterchain cadf:Reporterstep[] No Array of Reporterstep typed data tha
Serialisation
=============
json::
.. code-block:: javascript
{
'typeURI': 'http://schemas.dmtf.org/cloud/audit/1.0/event',
'id': 'openstack:a80dc5ee-be83-48ad-ad5e-6577f2217637‘,
'eventType': 'activity',
'action': 'read',
'outcome': 'success',
'reason': {'reasonCode': '200', 'reasonType': 'HTTP'},
'eventTime': '2014-01-17T23:23:38.109989+0000',
'initiator': {
'id': 'openstack:95f12d248a234a969f456cd2c794f29a'
'typeURI': 'service/security/account/user',
'name': ‘admin',
'project_id': 'openstack:e55b158759854ea6a7852aa76632c6c1',
'credential': {
'token': ‘MIIQBgYJKoZIhvcNAQcCoIIP9z xxxxxx KoZIhvcIP9z=‘,
'identity_status': 'Confirmed'},
'host': {
'agent': 'python-novaclient',
'address': '9.26.27.109'},
},
'target': {
'id': 'openstack:0f126160203748a5b4923f2eb6e3b7db',
'typeURI': ‘service/compute/servers',
'name': 'nova‘
'addresses': [
{'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1',
'name': 'admin'},
{'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1',
'name': 'private'},
{'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1',
'name': 'public'}
],
},
'observer': { 'id': 'target'},
'reporterchain': [
{'reporterTime': '2014-01-17T23:23:38.154152+0000',
'role': 'modifier',
'reporter': {'id': 'target'}}
],
'requestPath': '/v2/56600971-90f3-4370-807f-ab79339381a9/servers',
'tags': ['correlation_id?value=openstack:bcac04dc-e0be-4110-862c-347088a7836a']
}
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"id": "openstack:a80dc5ee-be83-48ad-ad5e-6577f2217637",
"eventType": "activity",
"action": "read",
"outcome": "success",
"reason": {
"reasonCode": "200",
"reasonType": "HTTP"
},
"eventTime": "2014-01-17T23:23:38.109989+0000",
"initiator": {
"id": "openstack:95f12d248a234a969f456cd2c794f29a""typeURI": "service/security/account/user",
"name": "admin",
"project_id": "openstack:e55b158759854ea6a7852aa76632c6c1",
"credential": {
"token": "MIIQBgYJKoZIhvcNAQcCoIIP9z xxxxxx KoZIhvcIP9z=",
"identity_status": "Confirmed"
},
"host": {
"agent": "python-novaclient",
"address": "9.26.27.109"
}
},
"target": {
"id": "openstack:0f126160203748a5b4923f2eb6e3b7db",
"typeURI": "service/compute/servers",
"name": "nova",
"addresses": [
{
"url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1",
"name": "admin"
},
{
"url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1",
"name": "private"
},
{
"url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1",
"name": "public"
}
]
},
"observer": {
"id": "target"
},
"reporterchain": [
{
"reporterTime": "2014-01-17T23:23:38.154152+0000",
"role": "modifier",
"reporter": {
"id": "target"
}
}
],
"requestPath": "/v2/56600971-90f3-4370-807f-ab79339381a9/servers",
"tags": [
"correlation_id?value=openstack:bcac04dc-e0be-4110-862c-347088a7836a"
]
}

28
doc/source/specification/geolocations.rst
View File

@ -19,7 +19,7 @@
Geolocations
=============
Geolocation information, which reveals a resource’s physical location, is
Geolocation information, which reveals a resource's physical location, is
obtained by using tracking technologies such as global positioning system
(GPS) devices, or IP geolocation by using databases that map IP addresses to
geographic locations. Geolocation information is widely used in
@ -59,7 +59,7 @@ Usage Requirements
::
Example: ‘latitude’, ‘longitude’ and ‘region’ are all supplied as
Example: 'latitude', 'longitude' and 'region' are all supplied as
properties describing the same geolocation, the 'latitude' and
'longitude' properties' coordinate values should resolve to the
same geographic location as described by the 'region'
@ -72,17 +72,17 @@ Usage Requirements
Serialisation
=============
json::
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"target": {
...,
"geolocation": {
"latitude": "+372207.90",
"longitude": "-1220210.20",
"elevation": "10"
}
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"target": {
...,
"geolocation": {
"latitude": "+372207.90",
"longitude": "-1220210.20",
"elevation": "10"
}
}
}
}

15
doc/source/specification/hosts.rst
View File

@ -43,12 +43,11 @@ platform xs:string No The optional platform of the host RESOURCE
Serialisation
=============
json::
{
"id": "myuuid:1234-5678-90abc-defg-0000",
"address": "10.0.2.15",
"agent": "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:18.0)",
"platform": "Linux version 3.5.0-23-generic (gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) ) #35~precise1-Ubuntu SMP Fri Jan 25 17:15:33 UTC 2013"
}
.. code-block:: javascript
{
"id": "myuuid:1234-5678-90abc-defg-0000",
"address": "10.0.2.15",
"agent": "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:18.0)",
"platform": "Linux version 3.5.0-23-generic (gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) ) #35~precise1-Ubuntu SMP Fri Jan 25 17:15:33 UTC 2013"
}

44
doc/source/specification/measurements.rst
View File

@ -51,27 +51,29 @@ annotations cadf:map No User-defined metric information.
Serialisation
=============
json::
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/log",
...,
"metrics": [
{
"metricId": "myuuid://metric.org/1234",
"unit": "GB",
"name": "Storage Capacity in Gigabytes"
}],
...,
"events": [
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"measurements": [
{
"result": "10",
"metricId": "myuuid://metric.org/1234"
}],
...
}]
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/log",
...,
"metrics": [
{
"metricId": "myuuid://metric.org/1234",
"unit": "GB",
"name": "Storage Capacity in Gigabytes"
}
],
...,
"events": [
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"measurements": [
{
"result": "10",
"metricId": "myuuid://metric.org/1234"
}
]
}
]
}

24
doc/source/specification/reasons.rst
View File

@ -34,16 +34,16 @@ policyId xs:string No An optional identifier that indicates which policy
Serialisation
=============
json::
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"reason": {
"reasonType": "http://www.iana.org/assignments/http-status-codes/http-status-codes.xml",
"reasonCode": "408",
"policyType": "http://schemas.xmlsoap.org/ws/2002/12/policy",
"policyId": "http://10.0.3.4/firewall-ruleset/rule0012"
},
...
}
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"reason": {
"reasonType": "http://www.iana.org/assignments/http-status-codes/http-status-codes.xml",
"reasonCode": "408",
"policyType": "http://schemas.xmlsoap.org/ws/2002/12/policy",
"policyId": "http://10.0.3.4/firewall-ruleset/rule0012"
},
...
}

29
doc/source/specification/reportersteps.rst
View File

@ -41,20 +41,19 @@ attachments cadf:Attachment[] No An optional array of additional data co
Serialisation
=============
json::
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"reporterchain": [
{
"role": "modifier",
"reporterTime": "2012-03-22T13:00:00-04:00",
"reporter": {
"id": "myscheme://mydomain/resource/monitor/id/0002"
}
},
...
]
}
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"reporterchain": [
{
"role": "modifier",
"reporterTime": "2012-03-22T13:00:00-04:00",
"reporter": {
"id": "myscheme://mydomain/resource/monitor/id/0002"
}
},
...
]
}

32
doc/source/specification/resources.rst
View File

@ -43,22 +43,20 @@ attachments cadf:Attachment[] No An optional array of extended or domai
Serialisation
=============
json::
.. code-block:: javascript
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"target": {
"id": "myscheme://mydomain/resource/id/0001",
"typeURI": "service/compute",
"name": "server_0001",
...,
"geolocation": {
"city": "Austin",
"state": "TX",
"regionICANN": "US"
}
{
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
...,
"target": {
"id": "myscheme://mydomain/resource/id/0001",
"typeURI": "service/compute",
"name": "server_0001",
...,
"geolocation": {
"city": "Austin",
"state": "TX",
"regionICANN": "US"
}
}
}
}