Skip to content

Commit

Permalink
Merge pull request #3128 from aleksandrychev/ENT-9959
Browse files Browse the repository at this point in the history 
Adjusted Inventory and Group API hostFilter documention
  • Loading branch information
@nickanderson
nickanderson authored Apr 4, 2024
2 parents 959b982 + be7510c commit 01519aa
Show file tree
Hide file tree
Showing 3 changed files with 280 additions and 121 deletions.
79 changes: 78 additions & 1 deletion api/enterprise-api-ref/inventory.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,18 @@ Inventory API allows to access inventory reports and attributes dictionary.
Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter.
* **hostContextInclude** *(array)*
Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. Optional parameter.
* **hostFilter** *(json object)* Optional parameter.
* **includes** *(json object)* Optional parameter.
Object that specifies hosts to be included.
* **includeAdditionally** *(boolean)* Default: `false`
Defines if hosts will be added to the results returned by inventory filters or class filters.
* **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings
Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask`
* **excludes** *(json object)* Optional parameter.
Object that specifies hosts to be excluded.
* **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings
Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask`
```
curl -k --user <username>:<password> \
Expand Down Expand Up @@ -178,6 +189,72 @@ curl -k --user <username>:<password> \
}
```
**Example Request Body with includeAdditionally set to true:**
```
{
"sort": "Host name",
"filter": {
"OS": {
"matches": "non-existing OS"
}
},
"hostFilter": {
"includes": {
"includeAdditionally": true,
"entries": {
"hostname": [
"ubuntu-bionic"
]
}
}
},
"select": [
"Host name",
"OS"
]
}
```
**Example response:**
As you can see, despite the OS filter should return zero hosts, we had one additionally included by the host in the Host filter.
```
{
"data": [
{
"header": [
{
"columnName": "Host name",
"columnType": "STRING"
},
{
"columnName": "OS",
"columnType": "STRING"
}
],
"queryTimeMs": 21,
"rowCount": 1,
"rows": [
[
"ubuntu-bionic",
"Ubuntu 18"
]
]
}
],
"meta": {
"count": 1,
"page": 1,
"timestamp": 1712141765,
"total": 1
}
}
```
## List of inventory attributes
**URI:** https://hub.cfengine.com/api/inventory/attributes-dictionary
Expand Down
182 changes: 117 additions & 65 deletions api/enterprise-api-ref/personal-groups.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,46 +27,62 @@ The personal groups API enables creating host groups based on host filters (the
* **hostContextExclude** *(array)* Optional parameter.
Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one
of the specified contexts set will be excluded from the results.
* **hostsFilter** *(json object)* Optional parameter.
* **includes** *(json object)* Optional parameter.
Object that specifies hosts to be included.
* **includeAdditionally** *(boolean)* Default: `false`
Defines if hosts will be included additionally on top of the inventory filters or class filters.
* **type** (string)
Now the only supported type is `hostkey`.
* **data** *(array)*
An array of hosts keys.
* **excludes** *(json object)* Optional parameter.
Object that specifies hosts to be excluded.
* **type** (string)
Now the only supported type is `hostkey`.
* **data** *(array)*
An array of hosts keys.

```json
{
"filter": {
"filter":{
"Attribute name": {
"operator":"value2"
}
},
"hostsFilter": {
"includes": {
"type": "hostkey",
"data": ["SHA=first1"]
* **hostFilter** *(json object)* Optional parameter.
* **includes** *(json object)* Optional parameter.
Object that specifies hosts to be included.
* **includeAdditionally** *(boolean)* Default: `false`
Defines if hosts will be added to the results returned by inventory filters or class filters.
* **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings
Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask`
* **excludes** *(json object)* Optional parameter.
Object that specifies hosts to be excluded.
* **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings
Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask`

```json
{
"filter": {
"filter":{
"Attribute name": {
"operator":"value2"
}
},
"excludes": {
"type": "hostkey",
"data": ["SHA=first2"]
}
},
"hostContextExclude": ["class_value"],
"hostContextInclude": ["class_value"]
"hostFilter": {
"includes": {
"includeAdditionally": false,
"entries": {
"ip": [
"192.168.56.5"
],
"hostkey": [],
"hostname": [
"ubuntu-bionic"
],
"mac": [
"08:00:27:0b:a4:99",
"08:00:27:dd:e1:59",
"02:9f:d3:59:7e:90"
],
"ip_mask": [
"10.0.2.16/16"
]
}
},
"excludes": {
"entries":{
"ip": [],
"hostkey": [],
"hostname": [],
"mac": [],
"ip_mask": []
}
}
},
"hostContextExclude": ["class_value"],
"hostContextInclude": ["class_value"]
}
}
}
```

```

**Operators:**

Expand Down Expand Up @@ -104,14 +120,37 @@ curl -k --user <username>:<password> \
"matches": "86"
}
},
"hostsFilter": {
"includes": {
"type": "hostkey",
"data": [
"SHA=first1"
]
"hostFilter": {
"includes": {
"includeAdditionally": false,
"entries": {
"ip": [
"192.168.56.5"
],
"hostkey": [],
"hostname": [
"ubuntu-bionic"
],
"mac": [
"08:00:27:0b:a4:99",
"08:00:27:dd:e1:59",
"02:9f:d3:59:7e:90"
],
"ip_mask": [
"10.0.2.16/16"
]
}
},
},
"excludes": {
"entries":{
"ip": [],
"hostkey": [],
"hostname": [],
"mac": [],
"ip_mask": []
}
}
},
"hostContextInclude": [
"aix"
]
Expand Down Expand Up @@ -150,21 +189,17 @@ curl -k --user <username>:<password> \
* **hostContextExclude** *(array)* Optional parameter.
Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one
of the specified contexts set will be excluded from the results.
* **hostsFilter** *(json object)* Optional parameter.
* **includes** *(json object)* Optional parameter.
Object that specifies hosts to be included.
* **includeAdditionally** *(boolean)* Default: `false`
Defines if hosts will be included additionally on top of the inventory filters or class filters.
* **type** (string)
Now the only supported type is `hostkey`.
* **data** *(array)*
An array of hosts keys.
* **excludes** *(json object)* Optional parameter.
Object that specifies hosts to be excluded.
* **type** (string)
Now the only supported type is `hostkey`.
* **data** *(array)*
An array of hosts keys.
* **hostFilter** *(json object)* Optional parameter.
* **includes** *(json object)* Optional parameter.
Object that specifies hosts to be included.
* **includeAdditionally** *(boolean)* Default: `false`
Defines if hosts will be added to the results returned by inventory filters or class filters.
* **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings
Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask`
* **excludes** *(json object)* Optional parameter.
Object that specifies hosts to be excluded.
* **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings
Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask`

```json
{
Expand All @@ -174,14 +209,31 @@ curl -k --user <username>:<password> \
"operator":"value2"
}
},
"hostsFilter": {
"hostFilter": {
"includes": {
"type": "hostkey",
"data": ["SHA=first1"]
"includeAdditionally": false,
"ip": [
"192.168.56.5"
],
"hostkey": [],
"hostname": [
"ubuntu-bionic"
],
"mac": [
"08:00:27:0b:a4:99",
"08:00:27:dd:e1:59",
"02:9f:d3:59:7e:90"
],
"ip_mask": [
"10.0.2.16/16"
]
},
"excludes": {
"type": "hostkey",
"data": ["SHA=first2"]
"ip": [],
"hostkey": [],
"hostname": [],
"mac": [],
"ip_mask": []
}
},
"hostContextExclude": ["class_value"],
Expand Down
Loading

0 comments on commit 01519aa

Please sign in to comment.