Docker Bake - Overriding variables via ENV advice is ambiguous

[polarathene]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

This is rather misleading information, in that the default assigned value $HOME is plain-text and has no relevance to using the environment variable as a default? (which is only applicable to the variable name matching):

### Use environment variable as default

You can set a Bake variable to use the value of an environment variable as a default value:

```hcl
variable "HOME" {
  default = "$HOME"
}
```

The description doesn't explicitly state default will be replaced via the HOME ENV, but instead implies the assigned $HOME will allow using the HOME ENV within the default value assignment (regardless of whatever the variable name is).

Such implied functionality while desired, does not work. The overlap in the variable name and the referenced ENV in default only adds to the ambiguity.

---

A related doc entry on the bake variables page describes interpolation, so one might try ${HOME} instead, but this will fail with:

Invalid expression; variable cycle not allowed for HOME

And if addressing that by changing the variable name itself to something else:

Unknown variable; There is no variable named "HOME".

Using the environment variables with bake config is only via the name of a variable declared. Which is only briefly mentioned at the end of the variables page under "Additional resources", which then links to this separate overrides page for actual functionality.

---

The ENV override is implicit which thus requires caution to not declare a variable name that would conflict in an environment running docker bake, since there is no option to opt-out of that functionality.

As such I'm slightly inclined to consider this a bug with the implementation rather than the docs (which may describe the intended behaviour?). It makes more sense that the usage of undeclared variables would be supported (at least via the ENV interpolation syntax like within compose.yaml) when a fallback environment variable exists, more than it does to fail on that scenario but implicitly override variables with ENV with no opt-out support? (EDIT: The overrides page makes it clear overriding by variable name is intentional)

My intent was to use the multiple ENV within a list or object/map variable type, which in the current scenario would require declaring empty vars to match those ENV anyway which seems unnecessary.

Location

https://docs.docker.com/build/bake/reference/#use-environment-variable-as-default

Suggestion

Assuming this isn't a bug in docker bake, then docs should instead be revised to:

### Use environment variable as default

When an environment variable exists that matches a Bake variable it will override the default value:

```hcl
variable "HOME" {
  default = "$HOME"
}
```

However that might as well link to the dedicated overrides page that documents the supported behaviour.