From b89d6a0bf8c255c98d00236bd32d45cfd1a028f8 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 23 Oct 2024 16:35:52 +0200 Subject: [PATCH] docs: update undefined var check reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> Signed-off-by: Tonis Tiigi --- .../dockerfile/docs/rules/undefined-var.md | 35 +++++++++++++------ .../dockerfile/linter/docs/UndefinedVar.md | 35 +++++++++++++------ 2 files changed, 50 insertions(+), 20 deletions(-) diff --git a/frontend/dockerfile/docs/rules/undefined-var.md b/frontend/dockerfile/docs/rules/undefined-var.md index 037e16bd239f..b68820764508 100644 --- a/frontend/dockerfile/docs/rules/undefined-var.md +++ b/frontend/dockerfile/docs/rules/undefined-var.md @@ -13,24 +13,25 @@ Usage of undefined variable '$foo' ## Description -Before you reference an environment variable or a build argument in a `RUN` -instruction, you should ensure that the variable is declared in the Dockerfile, -using the `ARG` or `ENV` instructions. +This check ensures that environment variables and build arguments are correctly +declared before being used. While undeclared variables might not cause an +immediate build failure, they can lead to unexpected behavior or errors later +in the build process. -Attempting to access an environment variable without explicitly declaring it -doesn't necessarily result in a build error, but it may yield an unexpected -result or an error later on in the build process. +This check does not evaluate undefined variables for `RUN`, `CMD`, and +`ENTRYPOINT` instructions where you use the [shell form](https://docs.docker.com/reference/dockerfile/#shell-form). +That's because when you use shell form, variables are resolved by the command +shell. -This check also attempts to detect if you're accessing a variable with a typo. -For example, given the following Dockerfile: +It also detects common mistakes like typos in variable names. For example, in +the following Dockerfile: ```dockerfile FROM alpine ENV PATH=$PAHT:/app/bin ``` -The check detects that `$PAHT` is undefined, and that it's probably a -misspelling of `PATH`. +The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`: ```text Usage of undefined variable '$PAHT' (did you mean $PATH?) @@ -53,3 +54,17 @@ ARG foo COPY $foo . ``` +❌ Bad: `$foo` is undefined. + +```dockerfile +FROM alpine AS base +ARG VERSION=$foo +``` + +✅ Good: the base image defines `$PYTHON_VERSION` + +```dockerfile +FROM python AS base +ARG VERSION=$PYTHON_VERSION +``` + diff --git a/frontend/dockerfile/linter/docs/UndefinedVar.md b/frontend/dockerfile/linter/docs/UndefinedVar.md index a2ee68559df5..32c005b2b00d 100644 --- a/frontend/dockerfile/linter/docs/UndefinedVar.md +++ b/frontend/dockerfile/linter/docs/UndefinedVar.md @@ -6,24 +6,25 @@ Usage of undefined variable '$foo' ## Description -Before you reference an environment variable or a build argument in a `RUN` -instruction, you should ensure that the variable is declared in the Dockerfile, -using the `ARG` or `ENV` instructions. +This check ensures that environment variables and build arguments are correctly +declared before being used. While undeclared variables might not cause an +immediate build failure, they can lead to unexpected behavior or errors later +in the build process. -Attempting to access an environment variable without explicitly declaring it -doesn't necessarily result in a build error, but it may yield an unexpected -result or an error later on in the build process. +This check does not evaluate undefined variables for `RUN`, `CMD`, and +`ENTRYPOINT` instructions where you use the [shell form](https://docs.docker.com/reference/dockerfile/#shell-form). +That's because when you use shell form, variables are resolved by the command +shell. -This check also attempts to detect if you're accessing a variable with a typo. -For example, given the following Dockerfile: +It also detects common mistakes like typos in variable names. For example, in +the following Dockerfile: ```dockerfile FROM alpine ENV PATH=$PAHT:/app/bin ``` -The check detects that `$PAHT` is undefined, and that it's probably a -misspelling of `PATH`. +The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`: ```text Usage of undefined variable '$PAHT' (did you mean $PATH?) @@ -45,3 +46,17 @@ FROM alpine AS base ARG foo COPY $foo . ``` + +❌ Bad: `$foo` is undefined. + +```dockerfile +FROM alpine AS base +ARG VERSION=$foo +``` + +✅ Good: the base image defines `$PYTHON_VERSION` + +```dockerfile +FROM python AS base +ARG VERSION=$PYTHON_VERSION +```