diff --git a/content/manuals/engine/manage-resources/labels.md b/content/manuals/engine/manage-resources/labels.md index b6f3f560b8..87aa01f2c9 100644 --- a/content/manuals/engine/manage-resources/labels.md +++ b/content/manuals/engine/manage-resources/labels.md @@ -70,47 +70,122 @@ you build this functionality into third-party tooling. ## Manage labels on objects Each type of object with support for labels has mechanisms for adding and -managing them and using them as they relate to that type of object. These links -provide a good place to start learning about how you can use labels in your -Docker deployments. +managing them and using them as they relate to that type of object. -Labels on images, containers, local daemons, volumes, and networks are static for -the lifetime of the object. To change these labels you must recreate the object. -Labels on Swarm nodes and services can be updated dynamically. +Labels on images, containers, local daemons, volumes, and networks are static +for the lifetime of the object. To change these labels you must recreate the +object. Labels on Swarm nodes and services can be updated dynamically. -- Images and containers +### Images - - [Adding labels to images](/reference/dockerfile.md#label) - - [Overriding a container's labels at runtime](/reference/cli/docker/container/run/#label) - - [Inspecting labels on images or containers](/reference/cli/docker/inspect/) - - [Filtering images by label](/reference/cli/docker/image/ls/#filter) - - [Filtering containers by label](/reference/cli/docker/container/ls/#filter) +Add labels to images using the [`LABEL` instruction](/reference/dockerfile.md#label) in a Dockerfile: -- Local Docker daemons +```dockerfile +LABEL com.example.version="1.0" +LABEL com.example.description="Web application" +``` - - [Adding labels to a Docker daemon at runtime](/reference/cli/dockerd.md) - - [Inspecting a Docker daemon's labels](/reference/cli/docker/system/info/) +You can also set labels at build time with the `--label` flag, without needing +a `LABEL` instruction in the Dockerfile: -- Volumes +```console +$ docker build --label "com.example.version=1.0" -t myapp . +``` - - [Adding labels to volumes](/reference/cli/docker/volume/create/) - - [Inspecting a volume's labels](/reference/cli/docker/volume/inspect/) - - [Filtering volumes by label](/reference/cli/docker/volume/ls/#filter) +Inspect labels on an image using `docker inspect`: -- Networks +```console +$ docker inspect --format='{{json .Config.Labels}}' myapp +``` - - [Adding labels to a network](/reference/cli/docker/network/create/) - - [Inspecting a network's labels](/reference/cli/docker/network/inspect/) - - [Filtering networks by label](/reference/cli/docker/network/ls/#filter) +Filter images by label with [`docker image ls --filter`](/reference/cli/docker/image/ls/#filter): -- Swarm nodes +```console +$ docker image ls --filter "label=com.example.version" +``` - - [Adding or updating a Swarm node's labels](/reference/cli/docker/node/update/#label-add) - - [Inspecting a Swarm node's labels](/reference/cli/docker/node/inspect/) - - [Filtering Swarm nodes by label](/reference/cli/docker/node/ls/#filter) +### Containers -- Swarm services - - [Adding labels when creating a Swarm service](/reference/cli/docker/service/create/#label) - - [Updating a Swarm service's labels](/reference/cli/docker/service/update/) - - [Inspecting a Swarm service's labels](/reference/cli/docker/service/inspect/) - - [Filtering Swarm services by label](/reference/cli/docker/service/ls/#filter) +Override or add labels when starting a container with +[`docker run --label`](/reference/cli/docker/container/run/#label): + +```console +$ docker run --label "com.example.env=prod" myapp +``` + +Inspect labels on a container: + +```console +$ docker inspect --format='{{json .Config.Labels}}' mycontainer +``` + +Filter containers by label with [`docker container ls --filter`](/reference/cli/docker/container/ls/#filter): + +```console +$ docker container ls --filter "label=com.example.env=prod" +``` + +### Local Docker daemons + +Add labels to the Docker daemon by passing `--label` flags when starting +`dockerd`, or by setting `"labels"` in the +[daemon configuration file](/reference/cli/dockerd.md#daemon-configuration-file): + +```json +{ + "labels": ["com.example.environment=production"] +} +``` + +View daemon labels with `docker system info`. + +### Volumes + +Add labels when [creating a volume](/reference/cli/docker/volume/create/): + +```console +$ docker volume create --label "com.example.purpose=database" myvolume +``` + +Inspect volume labels: + +```console +$ docker volume inspect myvolume --format='{{json .Labels}}' +``` + +Filter volumes by label with [`docker volume ls --filter`](/reference/cli/docker/volume/ls/#filter): + +```console +$ docker volume ls --filter "label=com.example.purpose" +``` + +### Networks + +Add labels when [creating a network](/reference/cli/docker/network/create/): + +```console +$ docker network create --label "com.example.purpose=frontend" mynetwork +``` + +Inspect network labels: + +```console +$ docker network inspect mynetwork --format='{{json .Labels}}' +``` + +Filter networks by label with [`docker network ls --filter`](/reference/cli/docker/network/ls/#filter): + +```console +$ docker network ls --filter "label=com.example.purpose" +``` + +### Swarm nodes + +- [Adding or updating a Swarm node's labels](/reference/cli/docker/node/update/#label-add) +- [Filtering Swarm nodes by label](/reference/cli/docker/node/ls/#filter) + +### Swarm services + +- [Adding labels when creating a Swarm service](/reference/cli/docker/service/create/#label) +- [Updating a Swarm service's labels](/reference/cli/docker/service/update/) +- [Filtering Swarm services by label](/reference/cli/docker/service/ls/#filter)