Dockerfile optimization recommendation - Container Registry

Container Registry provides the Dockerfile optimization recommendation feature for image building tasks on Container Registry Enterprise Edition instances. This feature helps you identify potential issues in Dockerfiles to improve the quality of container images. This feature does not affect image building. You can view optimization recommendation results in building logs without the need to perform operations. This topic describes how to identify potential issues in Dockerfiles based on the results of Dockerfile optimization recommendation to improve the quality of container images and meet the requirements of enterprise-level applications.

Background information

When you use the image building service provided by Container Registry Enterprise Edition, Container Registry can automatically optimize and recommend Dockerfiles before Container Registry builds images. Container Registry uses the Dockerfile optimization recommendation feature to analyze Dockerfiles based on syntax rules and best practice rules and then provide analysis results. For more information about syntax rules, see Dockerfile reference.

Analysis results are divided into the following levels of issues:

Error: The Dockerfile contains syntax errors or building parameters that are not supported by Container Registry. Error-level issues can cause errors in image buildings. You must fix Error-level issues.
Warning: The Dockerfile contains potential issues. Warning-level issues can cause unexpected image building results or redundant data in images.

Format of analysis results

Syntax detection results

[Error] <Error message> at line <line number>: <Specific instruction content>
[Warning] <Warning message> at line <line number>: <Specific instruction content>
[Error] [Rule <Rule id>] <Error message> at line <line number>: <Specific instruction content>
[Warning] [Rule <Rule id>] <Warning message> at line <line number>: <Specific instruction content>

Example 1

The Dockerfile contains syntax errors.

# The FROM instruction uses a base image of an unsupported architecture and does not specify the names of the stages in multi-stage building.
FROM --platform=windows alpine as
# The RUN instruction uses unsupported running parameters.
RUN --security=insecure cat /proc/self/status | grep CapEff
# No destination path is specified in the ADD instruction.
ADD https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz
# The COPY instruction does not support copying of remote files.
COPY https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz linux-0.01.tag.gz
# The source file path that is specified in the COPY/ADD instruction does not exist in the building path.
COPY <Path that does not exist> /somedir/
# The name of the instruction is invalid.
CPY /foo /bar

The following code provides the syntax detection results of the preceding Dockerfile.

[parse stage begin.]
[Error] Unsupported target architecture at line 2: windows.
[Error] Lack of stage name at line 2.
[Error] Unsupported security mode at line 4: insecure.
[Error] Lack of dest at line 6.
[Error] COPY does not support remote links. Please use the ADD instruction at line 8: https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz.
[Error] Source path is not exist at line 10: <Path that does not exist>.
[Error] Unknown instruction at line 12: CPY.
[Warning] No tag specified at line 2: from ["--platform=windows"] "alpine" "as".
[parse successfully, takes 0s.]

Example 2

The Dockerfile does not conform to best practice rules.

# No image tag is specified.
FROM alpine AS a
# The cache of the software package is not cleared after the software is installed.
RUN apk add gcc
# No image tag is specified. An existing stage name is used.
from ubuntu as a
# The cache of the software package is not cleared after the software is installed. No --no-install-recommends instruction is used to prevent unnecessary software packages from being downloaded.
RUN apt-get install -y gcc

The following code provides the syntax detection results of the preceding Dockerfile.

[parse stage begin.]
[Warning] [Rule1003]When installing software with apt-get, it is recommended to include the --no-install-recommends parameter at line 8: RUN apt-get install -y gcc .
[Warning] No tag specified at line 2: FROM alpine AS a .
[Warning] No tag specified at line 6: from ubuntu as a .
[Warning] [Rule1001]Using a base image with a specific tag instead of the latest image.
[Error] Duplicate stage names with line 2: a at line 6: from ubuntu as a .
[Error] [Rule1014]Do not use duplicate stage names.
[parse successfully, takes 0s.]

Detection rules

Best practice rules

Rule number	Issue level	Building rule	Recommended settings
R1001	Warning	Images that have the Latest tag cannot be used as base images.	Specify an image of a specific tag as your base image.
R1002	Warning	The `apt-get update, apt-get upgrade`, and `apt-get install` instructions must be used in the same instruction.	Combine the `apt-get update, apt-get upgrade` and `apt-get install` instructions into the same RUN instruction.
R1003	Warning	A `--no-install-recommends` instruction must be added to prevent unnecessary packages from being downloaded when you run an `apt-get` instruction to download software.	Add the `--no-install-recommends` instruction to the `apt-get install` instruction.
R1004	Warning	The cache of the software package must be cleared to reduce the size of the image after the software package is downloaded.	Append the `apt-get clean` and `rm -rf /var/lib/apt/lists/` instructions to the `apt-get` instruction. Append the `rm -rf /var/cache/apk/` instruction to the `apk` instruction. Add the `--no-cache` parameter to the `apk add` instruction. Append the `yum clean` instruction to the `yum` instruction.
R1005	Warning	Multi-stage building can be used in processing compilation commands to reduce the size of images.	Compile instructions such as make and go build in separate stages, and copy the compilation results to application images. Example: `FROM alpine:3.17 as complie COPY <source code> code/ RUN make FROM alpine:3.17 COPY --from=compile /code/bin bin/`
R1006	Warning	If you use the WORKDIR instruction to specify the working directory, the system may use an unexpected path when you use a relative path in the instruction.	Use an absolute path instead of a relative path.
R1007	Error	If you run instructions, such as Kill and Shutdown, during the building process, security and stability issues may occur.	Remove relevant instructions.
R1008	Warning	If you use the Root user for image building, security issues in container runtime may occur.	Do not use the Root user for image building.
R1009	Warning	If you use a CD instruction in image building to specify the working directory, the working directory does not take effect in container runtime.	Use a WORKDIR instruction instead of a CD instruction.
R1010	Error	Sudo instructions in image building are invalid.	Remove sudo instructions.
R1011	Error	When you use EXPOSE instructions to expose ports, the port number must be in the range of 0 to 65535, and the protocol must be TCP or UDP.	Use valid EXPOSE parameters, such as 8080, 8081/tcp, and 8082/udp.
R1012	Error	If you use a COPY instruction to copy multiple source files, the format of the destination path must be a directory.	Make sure that the format of the destination path is a directory.
R1013	Error	When you use a COPY instruction to copy files from another building stage, the name of the other building stage must be valid.	Make sure that the name of the other stage that you enter is the name of a stage that you defined.
R1014	Error	If you use a multi-stage building, the names of the stages must be different from each other.	Use a unique name for each stage.
R1015	Error	The first instruction in a Dockerfile must be a FROM or ARG instruction.	Make sure that the first instruction is a FROM or ARG instruction.
R1016	Warning	If you use multiple CMD instructions in image building, only the last CMD instruction takes effect.	Make sure that the last CMD instruction is the instruction that you want to use.
R1017	Warning	If you use multiple ENTRYPOINT instructions in image building, only the last ENTRYPOINT instruction takes effect.	Make sure that the last ENTRYPOINT instruction is the instruction that you want to use.
R1018	Error	If you use an ADD instruction to copy multiple source files, the format of the destination path must be a directory.	Make sure that the format of the destination path is a directory.
R1019	Warning	After you decompress software package, you can delete the compressed package to reduce the size of the image.	Combine the instructions that are used to download package, decompress package, and delete package into the same RUN instruction.