docker inspect format extracting single label values

[uecasm]

Description

I'm not sure if this is just an omission from the docs or if this is an actual bug in the CLI, but:

I want to be able to docker inspect an image to extract the values of specific labels on the image. This is from a script that can't parse JSON directly, but that's what the --format argument is for, right?

But what is the correct syntax for that? One of the following seemed most correct out of the options I could think of:

Steps to reproduce the issue:

docker inspect --format='{{.Config.Labels."org.label-schema.name"}}' $IMAGE_ID

docker inspect --format='{{.Config.Labels["org.label-schema.name"]}}' $IMAGE_ID

docker inspect --format='{{index .Config.Labels "org.label-schema.name"}}' $IMAGE_ID

Describe the results you received:

Template parsing error: template: :1: bad character U+002D '-'

Template parsing error: template: :1: bad character U+005B '['

Template parsing error: template: :1: unclosed action

Describe the results you expected:

build

The value of the label with that name should be printed.

Additional information you deem important (e.g. issue happens only occasionally):

$ docker inspect --format='{{json .Config.Labels}}' $IMAGE_ID
'map[build_id:8 org.label-schema.build-date:2020-08-14T05:42:00Z org.label-schema.description:Build Environment org.label-schema.name:build org.label-schema.schema-version:1.0 org.label-schema.vcs-ref:f1c5a320b23ec7361f6148a95c6683a9cab16d99 org.label-schema.version:4.0]'

(Which might also be a bug, since this is not JSON output...)

Output of docker version:

Client: Docker Engine - Community
 Version:           19.03.12
 API version:       1.40
 Go version:        go1.13.10
 Git commit:        48a66213fe
 Built:             Mon Jun 22 15:43:18 2020
 OS/Arch:           windows/amd64
 Experimental:      false

Server: Docker Engine - Community
 Engine:
  Version:          19.03.12
  API version:      1.40 (minimum version 1.12)
  Go version:       go1.13.10
  Git commit:       48a66213fe
  Built:            Mon Jun 22 15:49:27 2020
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v1.2.13
  GitCommit:        7ad184331fa3e55e52b890ea95e65ba581ae3429
 runc:
  Version:          1.0.0-rc10
  GitCommit:        dc9208a3303feef5b3839f4323d9beb36df0a9dd
 docker-init:
  Version:          0.18.0
  GitCommit:        fec3683

Output of docker info:

Client:
 Debug Mode: false

Server:
 Containers: 4
  Running: 1
  Paused: 0
  Stopped: 3
 Images: 52
 Server Version: 19.03.12
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 7ad184331fa3e55e52b890ea95e65ba581ae3429
 runc version: dc9208a3303feef5b3839f4323d9beb36df0a9dd
 init version: fec3683
 Security Options:
  seccomp
   Profile: default
 Kernel Version: 4.19.104-microsoft-standard
 Operating System: Docker Desktop
 OSType: linux
 Architecture: x86_64
 CPUs: 20
 Total Memory: 24.81GiB
 Name: docker-desktop
 ID: 3U3Y:XEWF:AGDX:7TZ2:XVJG:SUCD:R2XE:WOK7:XGZO:C3DN:A5PG:K4GS
 Docker Root Dir: /var/lib/docker
 Debug Mode: true
  File Descriptors: 77
  Goroutines: 105
  System Time: 2020-08-21T03:21:10.0077369Z
  EventsListeners: 3
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
 Live Restore Enabled: false
 Product License: Community Engine

WARNING: bridge-nf-call-iptables is disabled
WARNING: bridge-nf-call-ip6tables is disabled

Additional environment details (AWS, VirtualBox, physical, etc.):

Physical

[uecasm]

Ok, some progress. The valid syntax appears to depend which shell I'm using.

This works in a Posix shell:

docker inspect --format='{{index .Config.Labels "org.label-schema.name"}}' $IMAGE_ID

This works in a Windows shell:

docker inspect --format="{{index .Config.Labels \"org.label-schema.name\"}}" %IMAGE_ID%

So, probably the first part of this is just a doc issue. Can this be added to https://docs.docker.com/engine/reference/commandline/inspect/ ?
(Related: why does https://docs.docker.com/engine/reference/commandline/image_inspect/ not mention anything about the parameter syntax?)

The non-JSON json output seems to have been a side effect of the quoting issue as well (the output was generated in a Windows shell, so it needed the double quotes but didn't have them), although then I'm confused that it worked as well as it did.

[thaJeztah]

Hmm. yes, I suspect the single-quotes could be an issue on PowerShell (at least, I recall another ticket where someone mentioned that).

Trying your original example; building an image with the same labels as your example;

docker build -t foo:latest -<<'EOF'
FROM busybox
LABEL build_id="8"
LABEL org.label-schema.build-date="2020-08-14T05:42:00Z"
LABEL org.label-schema.description="Build Environment"
LABEL org.label-schema.name="build"
LABEL org.label-schema.schema-version="1.0"
LABEL org.label-schema.vcs-ref="f1c5a320b23ec7361f6148a95c6683a9cab16d99"
LABEL org.label-schema.version="4.0"
EOF

Trying docker inspect:

docker image inspect --format='{{index .Config.Labels "org.label-schema.name"}}' foo:latest
# build

So, probably the first part of this is just a doc issue. Can this be added to https://docs.docker.com/engine/reference/commandline/inspect/ ?

Hm, right, so I suspect single quotes were used in the examples to (among others) prevent the $'s being interpolated by the shell (https://docs.docker.com/engine/reference/commandline/inspect/#list-all-port-bindings), so it's a bit unfortunate that it's causing issues on PowerShell.

The source for that page is located in https://github.com/docker/cli/blob/master/docs/reference/commandline/inspect.md.

To prevent repeating that information for every command that has a --format flag, perhaps we should have a note added to https://docs.docker.com/config/formatting/, and link to that page 🤔 (source for that page is in https://github.com/docker/docker.github.io/blob/master/config/formatting.md)

Related: why does https://docs.docker.com/engine/reference/commandline/image_inspect/ not mention anything about the parameter syntax?

Good question; I think the docker <object> inspect commands were all added at once (as alternative to the global docker inspect command), and I guess nobody got round to adding proper examples to those pages 😞.

[maximillianfx]

To prevent repeating that information for every command that has a --format flag, perhaps we should have a note added to https://docs.docker.com/config/formatting/, and link to that page

Hey 😄 . Your point looks simple and good to facilitate this question @thaJeztah , can I make this change to contribute?

[thaJeztah]

can I make this change to contribute?

@maximillianfx yes, feel free to work on improvements! The "central" page about formatting is in the documentation repository, so I guess that one should be updated first;

https://github.com/docker/docker.github.io/blob/master/config/formatting.md

And then we can include a link to that page in the reference documentation for each command that has a --format flag. It would probably be good to keep some examples for each command, and then link to the "formatting" page for more in-depth information about the syntax etc.

[maximillianfx]

Ok, I'll be working on this fix during this week. Thanks!

[maximillianfx]

@thaJeztah can you see if this little change can do the job? If this first approach is okay, I'll could search into the docs by the --format flag in the commands and add a reference to the formatting page.

[ronaldpetty]

Not 100% sure if this is related, but feels so. I named a network with a hyphen and also can't retrieve with typical syntax.

docker container inspect nodea -f '{{.NetworkSettings.Networks.db-net.IPAddress}}'
Template parsing error: template: :1: bad character U+002D '-'

[thaJeztah]

@ronaldpetty .NetworkSettings.Networks is a "map"; try using the index function;

docker network create db-net
docker run -d --name foo --network=db-net nginx:alpine


docker container inspect foo -f '{{index .NetworkSettings.Networks "db-net" "IPAddress"}}'
172.19.0.2

[ronaldpetty]

Thanks @thaJeztah I didn't think that through, appreciate it.