Merge pull request #24319 from dvdksn/build-fix-bakectx-labels

Fix: clarify bake dockerfile+context relationship, improve docs on managing labels

Author: dvdksn

content/manuals/build/bake/targets.md

@@ -54,6 +54,18 @@ $ docker buildx bake
 The properties you can set for a target closely resemble the CLI flags for
 `docker build`, with a few additional properties that are specific to Bake.
 
+The `dockerfile` property specifies the path to the Dockerfile for a target.
+If you also set a `context`, the `dockerfile` path resolves relative to that
+context.
+
+```hcl {title=docker-bake.hcl}
+target "default" {
+  context = "app"
+  # resolves to app/src/www/Dockerfile
+  dockerfile = "src/www/Dockerfile"
+}
+```
+
 For all the properties you can set for a target, see the [Bake reference](/build/bake/reference#target).
 
 ## Grouping targets
@@ -112,7 +124,7 @@ Supported patterns:
 > Always wrap wildcard patterns in quotes. Without quotes, your shell will expand the
 > wildcard to match files in the current directory, which usually causes errors.
 
-Examples: 
+Examples:
 
 ```console
 # Match all targets starting with 'foo-'
@@ -129,7 +141,7 @@ $ docker buildx bake "[fb]oo-bar"
 
 # Matches: mtx-a-b-d, mtx-a-b-e, mtx-a-b-f
 $ docker buildx bake "mtx-a-b-*"
-``` 
+```
 
 You can also combine multiple patterns:
 

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)