Debian Codegraph @

buildkit/frontend/dockerfile/linter/docs/JSONArgsRecommended.md

raw
1 ## Output
2
3 ```text
4 JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
5 ```
6
7 ## Description
8
9 `ENTRYPOINT` and `CMD` instructions both support two different syntaxes for
10 arguments:
11
12 - Shell form: `CMD my-cmd start`
13 - Exec form: `CMD ["my-cmd", "start"]`
14
15 When you use shell form, the executable runs as a child process to a shell,
16 which doesn't pass signals. This means that the program running in the
17 container can't detect OS signals like `SIGTERM` and `SIGKILL` and respond to
18 them correctly.
19
20 ## Examples
21
22 ❌ Bad: the `ENTRYPOINT` command doesn't receive OS signals.
23
24 ```dockerfile
25 FROM alpine
26 ENTRYPOINT my-program start
27 # entrypoint becomes: /bin/sh -c my-program start
28 ```
29
30 To make sure the executable can receive OS signals, use the exec form for `CMD`
31 and `ENTRYPOINT`, which lets you run the executable as the main process (`PID
32 1`) in the container, avoiding a shell parent process.
33
34 ✅ Good: the `ENTRYPOINT` receives OS signals.
35
36 ```dockerfile
37 FROM alpine
38 ENTRYPOINT ["my-program", "start"]
39 # entrypoint becomes: my-program start
40 ```
41
42 Note that running programs as PID 1 means the program now has the special
43 responsibilities and behaviors associated with PID 1 in Linux, such as reaping
44 child processes.
45
46 ### Workarounds
47
48 There might still be cases when you want to run your containers under a shell.
49 When using exec form, shell features such as variable expansion, piping (`|`)
50 and command chaining (`&&`, `||`, `;`), are not available. To use such
51 features, you need to use shell form.
52
53 Here are some ways you can achieve that. Note that this still means that
54 executables run as child-processes of a shell.
55
56 #### Create a wrapper script
57
58 You can create an entrypoint script that wraps your startup commands, and
59 execute that script with a JSON-formatted `ENTRYPOINT` command.
60
61 ✅ Good: the `ENTRYPOINT` uses JSON format.
62
63 ```dockerfile
64 FROM alpine
65 RUN apk add bash
66 COPY --chmod=755 <<EOT /entrypoint.sh
67 #!/usr/bin/env bash
68 set -e
69 my-background-process &
70 my-program start
71 EOT
72 ENTRYPOINT ["/entrypoint.sh"]
73 ```
74
75 #### Explicitly specify the shell
76
77 You can use the [`SHELL`](https://docs.docker.com/reference/dockerfile/#shell)
78 Dockerfile instruction to explicitly specify a shell to use. This will suppress
79 the warning since setting the `SHELL` instruction indicates that using shell
80 form is a conscious decision.
81
82 ✅ Good: shell is explicitly defined.
83
84 ```dockerfile
85 FROM alpine
86 RUN apk add bash
87 SHELL ["/bin/bash", "-c"]
88 ENTRYPOINT echo "hello world"
89 ```