Skip to content

Commit a6d3d1c

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

1 file changed

Lines changed: 314 additions & 0 deletions

File tree

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

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

0 commit comments

Comments
 (0)