Skip to content

Commit 5e0e34f

Browse files
thaJeztahthaJeztah
committed
api: swagger: use separate definition for Image.Config
The Image.Config field currently reuses the ContainerConfig definition, matching the Go implementation, which also uses that type. However, the ContainerConfig type contains various fields that are not part of the image config, and would never be set. The Image.Config is used as template / default values for containers started from the image, but will only use the fields that are part of the [Docker image spec]. This patch updates the swagger files used in the documentation to use a separate `ImageConfig` definition for the Image.Config field. The new definition is a copy of the existing `ContainerConfig` type, but with updated descriptions for fields, and with an example response that omits the fields that should not be used. The following fields are currently included in the `Config` field of the API response, but are not part of the underlying image's config: - `Hostname` - `Domainname` - `AttachStdin` - `AttachStdout` - `AttachStderr` - `Tty` - `OpenStdin` - `StdinOnce` - `Image` - `NetworkDisabled` (already omitted unless set) - `MacAddress` (already omitted unless set) - `StopTimeout` (already omitted unless set) [Docker image spec]: https://github.com/moby/docker-image-spec/blob/v1.3.1/specs-go/v1/image.go#L19-L32 Signed-off-by: Sebastiaan van Stijn <[email protected]>
1 parent a24e3f2 commit 5e0e34f

1 file changed

Lines changed: 272 additions & 1 deletion

File tree

‎api/swagger.yaml‎

Lines changed: 272 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1356,6 +1356,277 @@ definitions:
13561356
type: "string"
13571357
example: ["/bin/sh", "-c"]
13581358

1359+
ImageConfig:
1360+
description: |
1361+
Configuration of the image. These fields are used as defaults
1362+
when starting a container from the image.
1363+
type: "object"
1364+
properties:
1365+
Hostname:
1366+
description: |
1367+
The hostname to use for the container, as a valid RFC 1123 hostname.
1368+
1369+
<p><br /></p>
1370+
1371+
> **Note**: this field is always empty and must not be used.
1372+
type: "string"
1373+
example: ""
1374+
Domainname:
1375+
description: |
1376+
The domain name to use for the container.
1377+
1378+
<p><br /></p>
1379+
1380+
> **Note**: this field is always empty and must not be used.
1381+
type: "string"
1382+
example: ""
1383+
User:
1384+
description: "The user that commands are run as inside the container."
1385+
type: "string"
1386+
example: "web:web"
1387+
AttachStdin:
1388+
description: |
1389+
Whether to attach to `stdin`.
1390+
1391+
<p><br /></p>
1392+
1393+
> **Note**: this field is always false and must not be used.
1394+
type: "boolean"
1395+
default: false
1396+
example: false
1397+
AttachStdout:
1398+
description: |
1399+
Whether to attach to `stdout`.
1400+
1401+
<p><br /></p>
1402+
1403+
> **Note**: this field is always false and must not be used.
1404+
type: "boolean"
1405+
default: false
1406+
example: false
1407+
AttachStderr:
1408+
description: |
1409+
Whether to attach to `stderr`.
1410+
1411+
<p><br /></p>
1412+
1413+
> **Note**: this field is always false and must not be used.
1414+
type: "boolean"
1415+
default: false
1416+
example: false
1417+
ExposedPorts:
1418+
description: |
1419+
An object mapping ports to an empty object in the form:
1420+
1421+
`{"<port>/<tcp|udp|sctp>": {}}`
1422+
type: "object"
1423+
x-nullable: true
1424+
additionalProperties:
1425+
type: "object"
1426+
enum:
1427+
- {}
1428+
default: {}
1429+
example: {
1430+
"80/tcp": {},
1431+
"443/tcp": {}
1432+
}
1433+
Tty:
1434+
description: |
1435+
Attach standard streams to a TTY, including `stdin` if it is not closed.
1436+
1437+
<p><br /></p>
1438+
1439+
> **Note**: this field is always false and must not be used.
1440+
type: "boolean"
1441+
default: false
1442+
example: false
1443+
OpenStdin:
1444+
description: |
1445+
Open `stdin`
1446+
1447+
<p><br /></p>
1448+
1449+
> **Note**: this field is always false and must not be used.
1450+
type: "boolean"
1451+
default: false
1452+
example: false
1453+
StdinOnce:
1454+
description: |
1455+
Close `stdin` after one attached client disconnects.
1456+
1457+
<p><br /></p>
1458+
1459+
> **Note**: this field is always false and must not be used.
1460+
type: "boolean"
1461+
default: false
1462+
example: false
1463+
Env:
1464+
description: |
1465+
A list of environment variables to set inside the container in the
1466+
form `["VAR=value", ...]`. A variable without `=` is removed from the
1467+
environment, rather than to have an empty value.
1468+
type: "array"
1469+
items:
1470+
type: "string"
1471+
example:
1472+
- "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
1473+
Cmd:
1474+
description: |
1475+
Command to run specified as a string or an array of strings.
1476+
type: "array"
1477+
items:
1478+
type: "string"
1479+
example: ["/bin/sh"]
1480+
Healthcheck:
1481+
$ref: "#/definitions/HealthConfig"
1482+
ArgsEscaped:
1483+
description: "Command is already escaped (Windows only)"
1484+
type: "boolean"
1485+
default: false
1486+
example: false
1487+
x-nullable: true
1488+
Image:
1489+
description: |
1490+
The name (or reference) of the image to use when creating the container,
1491+
or which was used when the container was created.
1492+
1493+
<p><br /></p>
1494+
1495+
> **Note**: this field is always empty and must not be used.
1496+
type: "string"
1497+
default: ""
1498+
example: ""
1499+
Volumes:
1500+
description: |
1501+
An object mapping mount point paths inside the container to empty
1502+
objects.
1503+
type: "object"
1504+
additionalProperties:
1505+
type: "object"
1506+
enum:
1507+
- {}
1508+
default: {}
1509+
example:
1510+
"/app/data": {}
1511+
"/app/config": {}
1512+
WorkingDir:
1513+
description: "The working directory for commands to run in."
1514+
type: "string"
1515+
example: "/public/"
1516+
Entrypoint:
1517+
description: |
1518+
The entry point for the container as a string or an array of strings.
1519+
1520+
If the array consists of exactly one empty string (`[""]`) then the
1521+
entry point is reset to system default (i.e., the entry point used by
1522+
docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`).
1523+
type: "array"
1524+
items:
1525+
type: "string"
1526+
example: []
1527+
NetworkDisabled:
1528+
description: |
1529+
Disable networking for the container.
1530+
1531+
<p><br /></p>
1532+
1533+
> **Note**: this field is always omitted and must not be used.
1534+
type: "boolean"
1535+
default: false
1536+
example: false
1537+
x-nullable: true
1538+
MacAddress:
1539+
description: |
1540+
MAC address of the container.
1541+
1542+
<p><br /></p>
1543+
1544+
> **Deprecated**: this field is deprecated in API v1.44 and up. It is always omitted.
1545+
type: "string"
1546+
default: ""
1547+
example: ""
1548+
x-nullable: true
1549+
OnBuild:
1550+
description: |
1551+
`ONBUILD` metadata that were defined in the image's `Dockerfile`.
1552+
type: "array"
1553+
x-nullable: true
1554+
items:
1555+
type: "string"
1556+
example: []
1557+
Labels:
1558+
description: "User-defined key/value metadata."
1559+
type: "object"
1560+
additionalProperties:
1561+
type: "string"
1562+
example:
1563+
com.example.some-label: "some-value"
1564+
com.example.some-other-label: "some-other-value"
1565+
StopSignal:
1566+
description: |
1567+
Signal to stop a container as a string or unsigned integer.
1568+
type: "string"
1569+
example: "SIGTERM"
1570+
x-nullable: true
1571+
StopTimeout:
1572+
description: |
1573+
Timeout to stop a container in seconds.
1574+
1575+
<p><br /></p>
1576+
1577+
> **Note**: this field is always omitted and must not be used.
1578+
type: "integer"
1579+
default: 10
1580+
x-nullable: true
1581+
Shell:
1582+
description: |
1583+
Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.
1584+
type: "array"
1585+
x-nullable: true
1586+
items:
1587+
type: "string"
1588+
example: ["/bin/sh", "-c"]
1589+
# FIXME(thaJeztah): temporarily using a full example to remove some "omitempty" fields. Remove once the fields are removed.
1590+
example:
1591+
"Hostname": ""
1592+
"Domainname": ""
1593+
"User": "web:web"
1594+
"AttachStdin": false
1595+
"AttachStdout": false
1596+
"AttachStderr": false
1597+
"ExposedPorts": {
1598+
"80/tcp": {},
1599+
"443/tcp": {}
1600+
}
1601+
"Tty": false
1602+
"OpenStdin": false
1603+
"StdinOnce": false
1604+
"Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]
1605+
"Cmd": ["/bin/sh"]
1606+
"Healthcheck": {
1607+
"Test": ["string"],
1608+
"Interval": 0,
1609+
"Timeout": 0,
1610+
"Retries": 0,
1611+
"StartPeriod": 0,
1612+
"StartInterval": 0
1613+
}
1614+
"ArgsEscaped": true
1615+
"Image": ""
1616+
"Volumes": {
1617+
"/app/data": {},
1618+
"/app/config": {}
1619+
}
1620+
"WorkingDir": "/public/"
1621+
"Entrypoint": []
1622+
"OnBuild": []
1623+
"Labels": {
1624+
"com.example.some-label": "some-value",
1625+
"com.example.some-other-label": "some-other-value"
1626+
}
1627+
"StopSignal": "SIGTERM"
1628+
"Shell": ["/bin/sh", "-c"]
1629+
13591630
NetworkingConfig:
13601631
description: |
13611632
NetworkingConfig represents the container's networking configuration for
@@ -1767,7 +2038,7 @@ definitions:
17672038
x-nullable: false
17682039
example: ""
17692040
Config:
1770-
$ref: "#/definitions/ContainerConfig"
2041+
$ref: "#/definitions/ImageConfig"
17712042
Architecture:
17722043
description: |
17732044
Hardware CPU architecture that the image runs on.

0 commit comments

Comments
 (0)