Merge pull request #277173 from alfpark/alpark/batch

Clarify Batch Docker entrypoint, cmd, workdir effects

Author: prmerger-automator[bot]

articles/batch/batch-docker-container-workloads.md

@@ -2,7 +2,7 @@
 title: Container workloads on Azure Batch
 description: Learn how to run and scale apps from container images on Azure Batch. Create a pool of compute nodes that support running container tasks.
 ms.topic: how-to
-ms.date: 05/31/2024
+ms.date: 06/04/2024
 ms.devlang: csharp
 ms.custom: devx-track-csharp, linux-related-content
 ---
@@ -50,7 +50,7 @@ Keep in mind the following limitations:
 - For Windows container workloads, you should choose a multicore VM size for your pool.
 
 > [!IMPORTANT]
-> Docker, by default, will create a network bridge with a subnet specification of `172.17.0.0/16`. If you are specifying a
+> Docker, by default, creates a network bridge with a subnet specification of `172.17.0.0/16`. If you are specifying a
 > [virtual network](batch-virtual-network.md) for your pool, ensure that there are no conflicting IP ranges.
 
 ## Supported VM images
@@ -393,15 +393,41 @@ When you run a container task, Batch automatically uses the [docker create](http
 
 As with non-container Batch tasks, you set a command line for a container task. Because Batch automatically creates the container, the command line only specifies the command or commands that run in the container.
 
-If the container image for a Batch task is configured with an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#exec-form-entrypoint-example) script, you can set your command line to either use the default ENTRYPOINT or override it:
-
-- To use the default ENTRYPOINT of the container image, set the task command line to the empty string `""`.
-
-- To override the default ENTRYPOINT, add the `--entrypoint` argument for example: `--entrypoint "/bin/sh - python"`
-
-- If the image doesn't have an ENTRYPOINT, set a command line appropriate for the container, for example, `/app/myapp` or `/bin/sh -c python myscript.py`
-
-Optional [ContainerRunOptions](/dotnet/api/microsoft.azure.batch.taskcontainersettings.containerrunoptions) are other arguments you provide to the `docker create` command that Batch uses to create and run the container. For example, to set a working directory for the container, set the `--workdir <directory>` option. See the [docker create](https://docs.docker.com/engine/reference/commandline/create/) reference for more options.
+The following are the default behaviors Batch applies to Docker container tasks:
+
+- Batch will run the container with the specified task commandline as the [CMD](https://docs.docker.com/reference/dockerfile/#cmd).
+- Batch won't interfere with the specified [ENTRYPOINT](https://docs.docker.com/reference/dockerfile/#entrypoint) of the container image.
+- Batch will override the [WORKDIR](https://docs.docker.com/reference/dockerfile/#workdir) with the [Batch task working directory](batch-compute-node-environment-variables.md).
+
+Ensure that you review the Docker documentation between ENTRYPOINT and CMD so you understand the
+interaction effects that can arise when container images have a specified ENTRYPOINT and you also
+specify a task commandline.
+
+If you would like to override the container image ENTRYPOINT, you can specify the `--entrypoint <args>`
+argument as a containerRunOption. Refer to the optional [ContainerRunOptions](/dotnet/api/microsoft.azure.batch.taskcontainersettings.containerrunoptions)
+for arguments that you can provide to the `docker create` command that Batch uses to create and run the
+container. For example, to set a working directory for the container, set the `--workdir <directory>`
+option.
+
+The following are some examples of container image and Batch container options or task command lines
+and their effect:
+
+- Container image ENTRYPOINT isn't specified, and Batch task commandline is "/bin/sh -c python myscript.py".
+  - Batch creates the container with the Batch task commandline as specified and runs it in the Batch
+    task working directory. This may result in failure if "myscript.py" isn't in the Batch task working
+    directory.
+  - If the task commandline was specified as "/bin/sh -c python /path/to/script/myscript.py", then this task may
+    work correctly even with the working directory set as the Batch task working directory if all dependencies
+    for the script are satisfied.
+- Container image ENTRYPOINT is specified as "./myscript.sh", and Batch task commandline is empty.
+  - Batch creates the container relying on the ENTRYPOINT and runs it in the Batch task working directory. This
+    task may result in failure if the container image WORKDIR isn't the same as the Batch task working
+    directory, which is dependent upon various factors such as the operating system, job ID, task ID, etc.
+  - If "--workdir /path/to/script" was specified as a containerRunOption, then this task may work correctly if
+    all dependencies for the script are satisfied.
+- Container image ENTRYPOINT isn't specified, Batch task commandline is "./myscript.sh", and WORKDIR is overridden in ContainerRunOptions as "--workdir /path/to/script".
+  - Batch creates the container with the working directory to "/path/to/script" and execute the
+    commandline "./myscript.sh", which is successful as the script is found in the specified working directory.
 
 ### Container task working directory
 
@@ -419,6 +445,9 @@ For a Batch container task:
 
 These mappings allow you to work with container tasks in much the same way as non-container tasks. For example, install applications using application packages, access resource files from Azure Storage, use task environment settings, and persist task output files after the container stops.
 
+Regardless of how the WORKDIR is set for a container image, both `stdout.txt` and `stderr.txt`
+are captured into the `AZ_BATCH_TASK_DIR`.
+
 ### Troubleshoot container tasks
 
 If your container task doesn't run as expected, you might need to get information about the WORKDIR or ENTRYPOINT configuration of the container image. To see the configuration, run the [docker image inspect](https://docs.docker.com/engine/reference/commandline/image_inspect/) command.