Proper Usage of Docker Build Arguments in RUN echo Commands

Problem Background and Phenomenon Analysis

During Docker container builds, developers often need to pass build-time parameters through the ARG instruction and utilize these parameters in RUN commands. A typical use case involves dynamically modifying configuration file content during the build process. However, many developers encounter issues where variables are not properly resolved, resulting in literal variable names appearing in target files instead of their actual values.

Core Problem Diagnosis

According to the problem description, the user defined an ARG key_name parameter in the Dockerfile and attempted to use this parameter in a subsequent RUN echo command. The build command passed the parameter value via --build-arg key_name=GC, but ultimately in the generated ssh_config file, the variable $key_name was not replaced with the actual value GC, remaining in its literal form.

Through thorough analysis, this issue primarily involves two key technical aspects:

Placement of ARG Instructions

The ARG instruction in a Dockerfile must be placed after the FROM instruction. According to Docker official documentation, when ARG is defined before FROM, its scope is limited to the FROM instruction itself and does not propagate to other instructions in the build stage. This design supports the requirement for different parameters in different stages of multi-stage builds.

The correct Dockerfile structure should be:

FROM base_image
ARG key_name
RUN echo ...

Impact of Quotes on Variable Expansion

In shell environments, single quotes (') and double quotes (") have fundamental differences in variable expansion. All characters within single quotes are treated as literals, with no variable expansion or command substitution occurring. Variables within double quotes are normally expanded.

The original problematic code:

RUN echo 'Host geoserver\n\
User user\n\
HostName 38.191.191.111\n\
IdentityFile /root/$key_name' >> /etc/ssh/ssh_config

Since single quotes were used, $key_name was not expanded. The solution is to use double quotes instead:

RUN echo "Host geoserver\n\
User user\n\
HostName 38.191.191.111\n\
IdentityFile /root/$key_name" >> /etc/ssh/ssh_config

Extended Case Analysis

Referencing the ENTRYPOINT script execution case, we can further understand the mechanisms of environment variables and parameter passing in Docker. When using shell form for ENTRYPOINT, environment variable expansion does occur, but CMD parameters may not be correctly passed to the script.

When using:

ENTRYPOINT ["/bin/bash", "-c", "$SCRIPT_PATH"]
CMD ["argument"]

In this form, argument is not passed to the script because the string after -c is treated as a complete command. This further illustrates the importance of understanding command execution context in Docker environments.

Best Practice Recommendations

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

1. ARG Placement Standards: Ensure ARG instructions are placed after FROM and before instructions that require the parameter
2. Quote Selection Strategy: Use double quotes in scenarios requiring variable expansion, and single quotes when maintaining literals is necessary
3. Variable Reference Format: Using ${variable} format improves code readability and avoids ambiguity
4. Testing Validation: After build completion, verify configuration file content correctness by entering the container via docker run

Technical Principles Deep Dive

The variable expansion mechanism during Docker builds is based on the underlying shell environment. When Docker executes RUN instructions, it essentially starts a shell process within the container to execute the specified commands. Therefore, all shell syntax rules and variable expansion mechanisms apply.

Environment variables and build parameter passing follow specific scope rules:

• Variables defined by ARG are only valid during the build stage
• Variables defined by ENV are valid in both build and runtime stages
• Build parameters can be passed externally via --build-arg

Conclusion

Proper usage of Docker build parameters requires deep understanding of shell variable expansion mechanisms and Dockerfile instruction execution order. By placing ARG instructions in correct positions and selecting appropriate quote types, variables can be properly expanded in RUN echo commands. These best practices apply not only to SSH configuration file modifications but also to other scenarios requiring dynamic configuration file generation during builds.