8.8 Kubernetes Container Startup Command

Kubernetes Container Startup Command is the manifest-level mechanism, through the command and args fields, by which an author overrides or supplies the process a container actually executes, mapping onto and interacting with a container image's own built-in entrypoint and default command in ways that determine exactly what runs when the container starts.

Mapping to Image-Defined Defaults

Relationship to Entrypoint and Cmd

Every container image defines its own default entrypoint and command, baked in at build time; a Pod's command field, when specified, overrides the image's entrypoint entirely, and args, when specified, overrides the image's default command, while omitting either field lets the image's own corresponding default take effect unmodified.

Common Override Combinations

Specifying only args while leaving command unset is a common pattern for images with a well-defined entrypoint binary that simply needs different arguments passed to it, while specifying both command and args together fully replaces the image's built-in startup behavior, useful when running a general-purpose base image for a purpose its default entrypoint was never designed for.

Exec Form Versus Shell Interpretation

No Shell Processing by Default

Both command and args are specified as a list of discrete string elements, each passed directly to the underlying execve system call without any shell interpreting or expanding them, meaning shell features like variable expansion, pipes, or globbing do not work unless a shell is explicitly invoked as part of the command itself.

Explicitly Invoking a Shell

To use shell features, a manifest author explicitly includes a shell invocation, such as command: ["/bin/sh", "-c"] paired with args: ["echo $HOME && do-something"], making the shell responsible for interpreting the string that follows, a deliberate pattern rather than something Kubernetes provides automatically.

Environment Variable Reference Syntax

The $(VAR_NAME) Expansion Pattern

Within command and args values, Kubernetes supports its own limited variable substitution syntax, $(VAR_NAME), which is expanded against the container's own defined environment variables before the process is launched, distinct from and independent of any shell-level variable expansion that would require an actual shell invocation.

Escaping to Prevent Expansion

A literal $(VAR_NAME)-looking string that should not be expanded can be escaped by doubling the dollar sign, $$(VAR_NAME), preventing Kubernetes' own substitution logic from treating it as a variable reference, a detail worth knowing when a command genuinely needs to include parenthesized text resembling this syntax.

Common Authoring Patterns

Wrapper Scripts as an Alternative to Complex Inline Commands

Rather than constructing an increasingly complex shell-invoking command and args combination directly within the manifest, many authors instead bake a wrapper script into the image itself and reference it simply as the entrypoint, keeping the manifest clean while moving complex startup logic into a properly tested, version-controlled script.

Debugging With an Overridden Command

Temporarily overriding a container's command to something like ["sleep", "infinity"] is a common debugging technique, keeping the container running indefinitely without executing its normal application logic, allowing an operator to kubectl exec into it and investigate the environment manually.

Interaction With Container Restart Behavior

Command Failure and restartPolicy

If the process launched by command and args exits, whether successfully or with an error, the Pod's restartPolicy governs what happens next, meaning the choice of startup command directly determines what "the container exiting" even means for a given workload, an especially important consideration for containers whose command is a short-lived task rather than a long-running server process.

Precedence and Validation

No Merge Between Image and Manifest Values

Kubernetes does not attempt to merge an image's built-in entrypoint or command with manifest-specified command or args; if command is set, it replaces the image entrypoint entirely rather than being appended to or combined with it, an all-or-nothing override behavior manifest authors need to account for when an image's built-in entrypoint performs setup steps the author still needs preserved.