Kubernetes Container Startup Command

Kubernetes Container Startup Command is the specific interaction between a container's command and args fields and the image's own built-in ENTRYPOINT and CMD, determining exactly what executable and arguments the container's process actually runs with, a resolution governed by a small but precise set of override rules that frequently confuses authors moving between plain container tooling conventions and Kubernetes' own field naming.

The Resolution Rules

command Overrides ENTRYPOINT, args Overrides CMD

Kubernetes' command field, when specified, entirely replaces the image's built-in ENTRYPOINT, and its args field, when specified, entirely replaces the image's built-in CMD; when either Kubernetes field is left unset, the corresponding image-level default is used instead, meaning the two pairs (command/ENTRYPOINT and args/CMD) are independently overridable rather than all-or-nothing.

Four Possible Combinations

Leaving both command and args unset runs the image exactly as built (ENTRYPOINT plus CMD, unmodified); setting only args replaces just the default arguments while keeping the image's own entrypoint binary; setting only command replaces the entrypoint entirely, and, notably, discards the image's CMD as well unless args is also explicitly supplied; setting both fully specifies the resulting process invocation independent of anything the image itself declares.

The Naming Mismatch With Plain Container Tooling

Kubernetes' command field corresponds to what plain container image tooling calls ENTRYPOINT, and Kubernetes' args corresponds to what that same tooling calls CMD — an inversion of naming intuition that trips up authors expecting command to mean the same thing as the ordinary CMD override flag they may be more familiar with from direct container runtime usage.

Why Command Overrides Discard CMD

No Implicit Argument Carry-Over

When command is set without a corresponding args, Kubernetes does not attempt to carry forward the image's original CMD as default arguments to the new entrypoint, since the two are considered independently paired concepts (ENTRYPOINT with CMD, command with args) rather than the new command inheriting the old image's argument defaults; an author replacing the entrypoint who still wants the image's original default arguments must explicitly restate them in args.

Shell Form Versus Exec Form

No Shell Interpretation by Default

Both command and args are specified as a list of discrete string elements (exec form), executed directly without passing through a shell, meaning shell features such as variable expansion, pipes, or globbing do not work unless the author explicitly invokes a shell as the command itself, such as ["/bin/sh", "-c", "echo $FOO"], where the shell interpretation happens only because a shell binary was deliberately specified as the entrypoint.

Implications for Environment Variable References

Because there is no implicit shell interpretation, referencing an environment variable directly within a bare command or args string (without invoking a shell) does not expand that variable the way it would in a typical shell script, a common source of confusion for authors expecting variable substitution to happen automatically within these fields.

Variable Reference Syntax Within command and args

Kubernetes-Native Variable Expansion

Separately from shell-level expansion, Kubernetes itself supports a limited $(VAR_NAME) substitution syntax within command and args values, resolving references to environment variables already defined for that container (including ones sourced from ConfigMaps or Secrets), evaluated by the kubelet before the container process is even started, independent of whether the eventual process itself involves a shell at all.

Escaping to Prevent Substitution

A literal $(...) sequence not intended for substitution must be escaped as $$(...), since the kubelet's substitution logic otherwise attempts to resolve it as a variable reference, which can produce a confusing empty-string result if the intended literal text happens to coincidentally match the variable reference syntax.