Best Practices for Passing Command-Line Arguments to ENTRYPOINT in Docker

Docker ENTRYPOINT and Argument Passing Mechanism

In Docker containerized deployments, properly configuring entry points and passing arguments is crucial for achieving application flexibility. This article will analyze through a specific case study how to pass command-line arguments to ENTRYPOINT.

Problem Scenario Analysis

Consider the following typical scenario: a developer needs to run a Java application deployed via JAR files that may receive runtime parameters. The original Dockerfile configuration is as follows:

FROM openjdk
ADD . /dir
WORKDIR /dir
COPY ./test-1.0.1.jar /dir/test-1.0.1.jar
ENTRYPOINT java -jar /dir/test-1.0.1.jar

In the shell script, attempting to pass arguments via docker run:

#! /bin/bash -l
export AWS_ACCESS_KEY_ID=$(aws configure get aws_access_key_id)
export AWS_SECRET_ACCESS_KEY=$(aws configure get aws_secret_access_key)
$value=7
docker run -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -i -t testjava $value

There is a critical issue here: when ENTRYPOINT uses the shell form (such as ENTRYPOINT java -jar /dir/test-1.0.1.jar), arguments passed via docker run cannot be correctly appended to the command.

Solution: Using Exec Form ENTRYPOINT

Docker provides two forms of ENTRYPOINT: shell form and exec form. To correctly receive arguments, the exec form must be used:

ENTRYPOINT ["java", "-jar", "/dir/test-1.0.1.jar"]

With this configuration, when executing docker run -it testjava $value, Docker will append $value as an argument after the ENTRYPOINT command, equivalent to executing:

java -jar /dir/test-1.0.1.jar $value

The core mechanism here is that exec form ENTRYPOINT runs directly as an executable file without going through a shell interpreter. Therefore, arguments passed by docker run become part of the ENTRYPOINT command's parameter list directly.

Collaborative Use of ENTRYPOINT and CMD

Another common pattern is combining ENTRYPOINT and CMD instructions. This design allows providing default parameters for ENTRYPOINT while maintaining flexibility:

FROM openjdk
ADD . /dir
WORKDIR /dir
COPY ./test-1.0.1.jar /dir/test-1.0.1.jar
ENTRYPOINT ["java", "-jar"]
CMD ["/dir/test-1.0.1.jar"]

With this configuration:

• When executing docker run testjava, the actual command run is java -jar /dir/test-1.0.1.jar
• When executing docker run testjava /dir/blahblah.jar, the default value of CMD is overridden, and the actual command run is java -jar /dir/blahblah.jar

This pattern is particularly suitable for scenarios where certain parameters (such as configuration file paths or JAR file names) need to be changed frequently.

Supplementary Notes on Environment Variable Passing

In the original problem, the developer correctly used the -e option to pass environment variables:

docker run -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -i -t testjava $value

Environment variable passing and command-line argument passing are two different mechanisms. Environment variables are accessed through the system environment inside the container, while command-line arguments are passed directly to the ENTRYPOINT command. Both can be used simultaneously without conflict.

Best Practices Summary

Based on the above analysis, we summarize the following best practices:

1. Prefer exec form ENTRYPOINT: Ensure correct reception of arguments passed by docker run.
2. Reasonably design the division between ENTRYPOINT and CMD: Place the unchanging command parts in ENTRYPOINT and potentially variable parameters in CMD.
3. Pay attention to argument passing semantics: Understand the different purposes and mechanisms of environment variables versus command-line arguments.
4. Test argument passing effects: Use docker run --entrypoint or enter the container to verify that arguments are correctly passed.

By properly configuring ENTRYPOINT, developers can build Docker images that maintain core functionality stability while possessing high configurability, thereby improving the deployment flexibility and maintainability of containerized applications.