Merge pull request #32735 from bhavin192/patch-1

Add note about host-dir in VOLUME
(cherry picked from commit f2fff9d913)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/builder.md

@@ -1281,18 +1281,28 @@ This Dockerfile results in an image that causes `docker run`, to
 create a new mount point at `/myvol` and copy the  `greeting` file
 into the newly created volume.
 
-> **Note**:
-> When using Windows-based containers, the destination of a volume inside the
-> container must be one of: a non-existing or empty directory; or a drive other
-> than C:.
+### Notes about specifying volumes
 
-> **Note**:
-> If any build steps change the data within the volume after it has been
-> declared, those changes will be discarded.
+Keep the following things in mind about volumes in the `Dockerfile`.
 
-> **Note**:
-> The list is parsed as a JSON array, which means that
-> you must use double-quotes (") around words not single-quotes (').
+- **Volumes on Windows-based containers**: When using Windows-based containers,
+  the destination of a volume inside the container must be one of:
+  
+  - a non-existing or empty directory
+  - a drive other than `C:`
+
+- **Changing the volume from within the Dockerfile**: If any build steps change the
+  data within the volume after it has been declared, those changes will be discarded.
+
+- **JSON formatting**: The list is parsed as a JSON array.
+  You must enclose words with double quotes (`"`)rather than single quotes (`'`).
+
+- **The host directory is declared at container run-time**: The host directory
+  (the mountpoint) is, by its nature, host-dependent. This is to preserve image
+  portability. since a given host directory can't be guaranteed to be available
+  on all hosts.For this reason, you can't mount a host directory from
+  within the Dockerfile. The `VOLUME` instruction does not support specifying a `host-dir`
+  parameter.  You must specify the mountpoint when you create or run the container.
 
 ## USER