Skip to content

Commit 378fb8e

Browse files
aleksandrychevaleksandrychev
committed
Added Container information API documentation
Signed-off-by: Ihor Aleksandrychiev <ihor.aleksandrychiev@northern.tech>
1 parent d28466b commit 378fb8e

1 file changed

Lines changed: 332 additions & 0 deletions

File tree

‎content/api/enterprise-api-ref/containers-api.markdown‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
---
2+
layout: default
3+
title: Container information API
4+
---
5+
6+
Containers API provides access to container inventory data collected from
7+
hosts, including running containers, container images, and container volumes.
8+
It also exposes a per-host summary endpoint with aggregated counts.
9+
10+
## List containers
11+
12+
**URI:** https://hub.cfengine.com/api/inventory/containers
13+
14+
**Method:** GET
15+
16+
**Parameters:**
17+
18+
- **hostkey** _(string)_
19+
Filter by host key (exact match).
20+
- **owner** _(string)_
21+
Filter by owner (exact match).
22+
- **name** _(string)_
23+
Filter by container name (case-insensitive substring match).
24+
- **image** _(string)_
25+
Filter by image (case-insensitive substring match).
26+
- **state** _(string)_
27+
Filter by container state (case-insensitive substring match).
28+
- **engine** _(string)_
29+
Filter by container engine (exact match, e.g. `docker`, `podman`).
30+
- **container_port** _(integer or array of integers)_
31+
Filter by published container ports. Allowed range: 0–65535. May be
32+
repeated to match any of several ports.
33+
- **host_port** _(integer or array of integers)_
34+
Filter by host ports the container is published on. Allowed range:
35+
0–65535. May be repeated to match any of several ports.
36+
- **host_ip** _(string or array of strings)_
37+
Filter by the host IP a port is bound to (e.g. `0.0.0.0`). May be repeated.
38+
- **protocol** _(string or array of strings)_
39+
Filter by port protocol. Allowed values: `tcp`, `udp`, `sctp`
40+
(case-insensitive). May be repeated.
41+
- **page** _(integer, default: 1)_
42+
Page number for pagination.
43+
- **per_page** _(integer, default: 20)_
44+
Number of items per page. Allowed range: 1–100.
45+
- **sort** _(string, default: "started_at")_
46+
Column to sort by. Allowed values:
47+
- hostkey
48+
- owner
49+
- id
50+
- name
51+
- image
52+
- state
53+
- engine
54+
- started_at
55+
- collected_at
56+
- **order** _(string, default: "desc")_
57+
Sort direction. Allowed values:
58+
- asc
59+
- desc
60+
61+
**Example request (curl):**
62+
63+
```console
64+
curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/containers
65+
```
66+
67+
To filter by ports, repeat a parameter using the `[]` array syntax:
68+
69+
```console
70+
curl --user <username>:<password> -X GET \
71+
"https://hub.cfengine.com/api/inventory/containers?host_port[]=8080&host_port[]=443&protocol[]=tcp"
72+
```
73+
74+
**Successful response example:**
75+
76+
```
77+
HTTP 200 OK
78+
{
79+
"data": [
80+
{
81+
"hostkey": "SHA=abc123...",
82+
"owner": "root",
83+
"id": "9f1c7e2b4a55",
84+
"name": "web",
85+
"image": "nginx:1.27",
86+
"image_id": "sha256:7d3f...",
87+
"command": "nginx -g 'daemon off;'",
88+
"state": "running",
89+
"ports": [
90+
{
91+
"container_port": 80,
92+
"host_ip": "0.0.0.0",
93+
"host_port": 8080,
94+
"protocol": "tcp"
95+
}
96+
],
97+
"engine": "docker",
98+
"started_at": "2026-05-20 12:30:00",
99+
"collected_at": "2026-05-26 09:00:00",
100+
"details": null
101+
}
102+
],
103+
"meta": {
104+
"count": 1,
105+
"page": 1,
106+
"timestamp": 1748246400,
107+
"total": 1
108+
}
109+
}
110+
```
111+
112+
**Responses:**
113+
114+
| HTTP response code | Description |
115+
| ------------------------- | --------------------- |
116+
| 200 OK | Containers returned |
117+
| 400 Bad Request | Validation error |
118+
| 401 Unauthorized | Authorization missing |
119+
| 500 Internal server error | Internal server error |
120+
121+
## List container images
122+
123+
**URI:** https://hub.cfengine.com/api/inventory/container-images
124+
125+
**Method:** GET
126+
127+
**Parameters:**
128+
129+
- **hostkey** _(string)_
130+
Filter by host key (exact match).
131+
- **owner** _(string)_
132+
Filter by owner (exact match).
133+
- **repository** _(string)_
134+
Filter by image repository (case-insensitive substring match).
135+
- **tag** _(string)_
136+
Filter by image tag (case-insensitive substring match).
137+
- **page** _(integer, default: 1)_
138+
Page number for pagination.
139+
- **per_page** _(integer, default: 20)_
140+
Number of items per page. Allowed range: 1–100.
141+
- **sort** _(string, default: "created_at")_
142+
Column to sort by. Allowed values:
143+
- hostkey
144+
- owner
145+
- id
146+
- repository
147+
- tag
148+
- size_bytes
149+
- created_at
150+
- collected_at
151+
- **order** _(string, default: "desc")_
152+
Sort direction. Allowed values:
153+
- asc
154+
- desc
155+
156+
**Example request (curl):**
157+
158+
```console
159+
curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/container-images
160+
```
161+
162+
**Successful response example:**
163+
164+
```
165+
HTTP 200 OK
166+
{
167+
"data": [
168+
{
169+
"hostkey": "SHA=abc123...",
170+
"owner": "root",
171+
"id": "sha256:7d3f...",
172+
"repository": "nginx",
173+
"tag": "1.27",
174+
"size_bytes": 142000000,
175+
"created_at": "2026-05-01 10:00:00",
176+
"collected_at": "2026-05-26 09:00:00"
177+
}
178+
],
179+
"meta": {
180+
"count": 1,
181+
"page": 1,
182+
"timestamp": 1748246400,
183+
"total": 1
184+
}
185+
}
186+
```
187+
188+
**Responses:**
189+
190+
| HTTP response code | Description |
191+
| ------------------------- | ------------------------- |
192+
| 200 OK | Container images returned |
193+
| 400 Bad Request | Validation error |
194+
| 401 Unauthorized | Authorization missing |
195+
| 500 Internal server error | Internal server error |
196+
197+
## List container volumes
198+
199+
**URI:** https://hub.cfengine.com/api/inventory/container-volumes
200+
201+
**Method:** GET
202+
203+
**Parameters:**
204+
205+
- **hostkey** _(string)_
206+
Filter by host key (exact match).
207+
- **owner** _(string)_
208+
Filter by owner (exact match).
209+
- **volume_name** _(string)_
210+
Filter by volume name (case-insensitive substring match).
211+
- **driver** _(string)_
212+
Filter by volume driver (case-insensitive substring match).
213+
- **page** _(integer, default: 1)_
214+
Page number for pagination.
215+
- **per_page** _(integer, default: 20)_
216+
Number of items per page. Allowed range: 1–100.
217+
- **sort** _(string, default: "created_at")_
218+
Column to sort by. Allowed values:
219+
- hostkey
220+
- owner
221+
- name
222+
- driver
223+
- size_bytes
224+
- created_at
225+
- collected_at
226+
- **order** _(string, default: "desc")_
227+
Sort direction. Allowed values:
228+
- asc
229+
- desc
230+
231+
**Example request (curl):**
232+
233+
```console
234+
curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/container-volumes
235+
```
236+
237+
**Successful response example:**
238+
239+
```
240+
HTTP 200 OK
241+
{
242+
"data": [
243+
{
244+
"hostkey": "SHA=abc123...",
245+
"owner": "root",
246+
"name": "web-data",
247+
"driver": "local",
248+
"size_bytes": 5242880,
249+
"created_at": "2026-05-15 08:00:00",
250+
"collected_at": "2026-05-26 09:00:00"
251+
}
252+
],
253+
"meta": {
254+
"count": 1,
255+
"page": 1,
256+
"timestamp": 1748246400,
257+
"total": 1
258+
}
259+
}
260+
```
261+
262+
**Responses:**
263+
264+
| HTTP response code | Description |
265+
| ------------------------- | -------------------------- |
266+
| 200 OK | Container volumes returned |
267+
| 400 Bad Request | Validation error |
268+
| 401 Unauthorized | Authorization missing |
269+
| 500 Internal server error | Internal server error |
270+
271+
## Get containers summary for a host
272+
273+
Returns aggregated container, image, and volume counts for a single host,
274+
along with the list of distinct container engines detected on it.
275+
276+
**URI:** https://hub.cfengine.com/api/inventory/containers/summary/:hostkey
277+
278+
**Method:** GET
279+
280+
**Path parameters:**
281+
282+
- **hostkey** _(string)_
283+
Host key to compute the summary for. The caller must have access to the
284+
host.
285+
286+
**Example request (curl):**
287+
288+
```console
289+
curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/containers/summary/SHA=abc123
290+
```
291+
292+
**Successful response example:**
293+
294+
```
295+
HTTP 200 OK
296+
{
297+
"hostkey": "SHA=abc123...",
298+
"containers": {
299+
"running": 3,
300+
"total": 5
301+
},
302+
"images": {
303+
"named": 8,
304+
"total": 12
305+
},
306+
"volumes": {
307+
"count": 4,
308+
"total_size_bytes": 20971520
309+
},
310+
"engines": [
311+
"docker",
312+
"podman"
313+
]
314+
}
315+
```
316+
317+
**Responses:**
318+
319+
| HTTP response code | Description |
320+
| ------------------------- | ---------------------------------- |
321+
| 200 OK | Summary returned |
322+
| 400 Bad Request | Invalid host key or host not found |
323+
| 401 Unauthorized | Authorization missing |
324+
| 403 Forbidden | Caller has no access to the host |
325+
| 500 Internal server error | Internal server error |
326+
327+
## Permissions
328+
329+
All Containers API endpoints are gated by the same RBAC permission used for
330+
the [Query API](/api/enterprise-api-ref/query/) (`query.post`). The
331+
`/inventory/containers/summary/:hostkey` endpoint additionally requires the
332+
caller to have access to the requested host.

0 commit comments

Comments
 (0)