docker / docker/docs

Add example to docker image inspect documentation

Open
#16,316 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/api area/engine lifecycle/frozen
Dominant language
Markdown
Stars
4.7k
Forks
8.5k
Avg merge
2d 18h
Merged PRs (30d)
108

Description

The docker image inspect command shows a lot useful information on a Docker image. However, I am missing an explained example on what all the entries shown in the response actually mean. The current documentation makes no statement about this. I could also not find a single reference outside Docker docs. Some information can be inferred from the OCI Image Specification, others from the Docker run reference. But not all entries are explained sufficiently.

I created this issue as generalization of issue #16315

As an example, pull the latest nginx image and execute docker image inspect nginx, you will get this output:

[
    {
        "Id": "sha256:ac8efec875ce36b619cb41f91d9db579487b9d45ed29393dc957a745b1e0024f",
        "RepoTags": [
            "nginx:1.23.2",
            "nginx:latest"
        ],
        "RepoDigests": [
            "nginx@sha256:ab589a3c466e347b1c0573be23356676df90cd7ce2dbf6ec332a5f0a8b5e59db"
        ],
        "Parent": "",
        "Comment": "",
        "Created": "2022-12-06T04:46:58.320356931Z",
        "Container": "3171a476b89e47a3d602688a3d1ada78b93cc52caf218265481d9c91ca5ebcdf",
        "ContainerConfig": {
            "Hostname": "3171a476b89e",
            "Domainname": "",
            "User": "",
            "AttachStdin": false,
            "AttachStdout": false,
            "AttachStderr": false,
            "ExposedPorts": {
                "80/tcp": {}
            },
            "Tty": false,
            "OpenStdin": false,
            "StdinOnce": false,
            "Env": [
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                "NGINX_VERSION=1.23.2",
                "NJS_VERSION=0.7.7",
                "PKG_RELEASE=1~bullseye"
            ],
            "Cmd": [
                "/bin/sh",
                "-c",
                "#(nop) ",
                "CMD [\"nginx\" \"-g\" \"daemon off;\"]"
            ],
            "Image": "sha256:19d855ece39b9e1bf1a9126ed89c7931f8505a2f4e5893f3c72d9b8b310b671f",
            "Volumes": null,
            "WorkingDir": "",
            "Entrypoint": [
                "/docker-entrypoint.sh"
            ],
            "OnBuild": null,
            "Labels": {
                "maintainer": "NGINX Docker Maintainers <docker-maint@nginx.com>"
            },
            "StopSignal": "SIGQUIT"
        },
        "DockerVersion": "20.10.12",
        "Author": "",
        "Config": {
            "Hostname": "",
            "Domainname": "",
            "User": "",
            "AttachStdin": false,
            "AttachStdout": false,
            "AttachStderr": false,
            "ExposedPorts": {
                "80/tcp": {}
            },
            "Tty": false,
            "OpenStdin": false,
            "StdinOnce": false,
            "Env": [
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                "NGINX_VERSION=1.23.2",
                "NJS_VERSION=0.7.7",
                "PKG_RELEASE=1~bullseye"
            ],
            "Cmd": [
                "nginx",
                "-g",
                "daemon off;"
            ],
            "Image": "sha256:19d855ece39b9e1bf1a9126ed89c7931f8505a2f4e5893f3c72d9b8b310b671f",
            "Volumes": null,
            "WorkingDir": "",
            "Entrypoint": [
                "/docker-entrypoint.sh"
            ],
            "OnBuild": null,
            "Labels": {
                "maintainer": "NGINX Docker Maintainers <docker-maint@nginx.com>"
            },
            "StopSignal": "SIGQUIT"
        },
        "Architecture": "amd64",
        "Os": "linux",
        "Size": 141767578,
        "VirtualSize": 141767578,
        "GraphDriver": {
            "Data": {
                "LowerDir": "/var/lib/docker/overlay2/872573049e3bf097fad7dee192afe78bb2c42524eb429602ae088c453652d4b2/diff:/var/lib/docker/overlay2/b08669580851d90170f32fe614a7f1c0ce1e0045eff1c2318ab55fdc5a05c34f/diff:/var/lib/docker/overlay2/47cac3f836efd18d9110de151f0a2badeb74e804313b932a18b68a03a4faf549/diff:/var/lib/docker/overlay2/63900275913ee385755ebf0115d152dc0192c49b5c5f5a910ae2c6d0f4a35803/diff:/var/lib/docker/overlay2/42a97c895a2607143d490cc67fab2c203c5b424ec98d7644c87052abf0710b32/diff",
                "MergedDir": "/var/lib/docker/overlay2/ac6162282cab60993f833557a2ec9ae20842015ec30c5c79ad95ae99dd5dcdf1/merged",
                "UpperDir": "/var/lib/docker/overlay2/ac6162282cab60993f833557a2ec9ae20842015ec30c5c79ad95ae99dd5dcdf1/diff",
                "WorkDir": "/var/lib/docker/overlay2/ac6162282cab60993f833557a2ec9ae20842015ec30c5c79ad95ae99dd5dcdf1/work"
            },
            "Name": "overlay2"
        },
        "RootFS": {
            "Type": "layers",
            "Layers": [
                "sha256:b5ebffba54d3e3f7fd80435fcdc34c4a96fdb2ecab0f0a298fe08f74c2f69d29",
                "sha256:2842e5d66803d5141f310218e017d24983fa8c05936c12471ba8f87451720035",
                "sha256:f88642d922a1d9af61581afab6afa968e139763f003c047ae0a7bd3b40f00392",
                "sha256:6906edffc609cbf0ddcde6528af25a4b6c187c219af4e484363bb392849a89a2",
                "sha256:aa3739f310f5e93f7519ce69e7248fd3bba426b9e7ad730d623bda63b45e8802",
                "sha256:7b72d5d921cb3acfc32df62534c75e4dbe7a14c98297c6657ae82b78ce608669"
            ]
        },
        "Metadata": {
            "LastTagTime": "0001-01-01T00:00:00Z"
        }
    }
]

Here, as an example, it is unclear to me what exactly StdInOnce means. Others are obviously self-explaining, however, I would suggest that an exemplary interpretation on what these entries mean, would help a lot.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the current docker image inspect documentation and run docker image inspect nginx to review the example output. Compare each field with the OCI Image Specification and Docker run reference, especially entries such as StdInOnce. Done means the documentation includes an explained example that defines the output entries sufficiently for users to interpret them.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.