Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve docs about ARG in FROM #333

Merged
merged 2 commits into from
Jul 15, 2017
Merged

Improve docs about ARG in FROM #333

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2880030
Clarify docs about ARG in FROM
dnephin Jul 13, 2017
ad5d035
More about ARG and build stages.
dnephin Jul 13, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 38 additions & 15 deletions docs/reference/builder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -530,15 +530,16 @@ FROM extras:${CODE_VERSION}
CMD /code/run-extras
```

To use the default value of an `ARG` declared before the first `FROM` use an
`ARG` instruction without a value:
An `ARG` declared before a `FROM` is outside of a build stage, so it
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe better to mention that every stage has individual args, then it is better to understand that "arg-in-from" is not an exception but just follows the rule.

How about this example:

ARG VERSION=latest
FROM busybox:$VERSION
ARG VERSION
RUN echo $VERSION > image_version

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe something like "An ARG instructions is only relevant for the next FROM instruction that comes after it in the Dockerfile, and then using this example to illustrate that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe something like "An ARG instructions is only relevant for the next FROM instruction that comes after it in the Dockerfile,

That's not exactly correct. There are two cases:

  • any ARG before the first FROM can be used in any FROM line
  • any ARG within a build stage (after a FROM) can be used in that build stage

I can add more details to the ARG reference section as well (this stuff is under FROM) , but I think this line needs to be updated as well something along the lines of what I have.

can't be used in any instruction after a `FROM`. To use the default value of
an `ARG` declared before the first `FROM` use an `ARG` instruction without
a value inside of a build stage:

```Dockerfile
ARG SETTINGS=default

FROM busybox
ARG SETTINGS

ARG VERSION=latest
FROM busybox:$VERSION
ARG VERSION
RUN echo $VERSION > image_version
```

## RUN
Expand Down Expand Up @@ -1364,8 +1365,8 @@ defined in the Dockerfile, the build outputs a warning.
[Warning] One or more build-args [foo] were not consumed.
```

The Dockerfile author can define a single variable by specifying `ARG` once or many
variables by specifying `ARG` more than once. For example, a valid Dockerfile:
A Dockerfile may include one or more `ARG` instructions. For example,
the following is a valid Dockerfile:

```
FROM busybox
Expand All @@ -1374,7 +1375,13 @@ ARG buildno
...
```

A Dockerfile author may optionally specify a default value for an `ARG` instruction:
> **Warning:** It is not recommended to use build-time variables for
> passing secrets like github keys, user credentials etc. Build-time variable
> values are visible to any user of the image with the `docker history` command.

### Default values

An `ARG` instruction can optionally include a default value:

```
FROM busybox
Expand All @@ -1383,8 +1390,10 @@ ARG buildno=1
...
```

If an `ARG` value has a default and if there is no value passed at build-time, the
builder uses the default.
If an `ARG` instruction has a default value and if there is no value passed
at build-time, the builder uses the default.

### Scope

An `ARG` variable definition comes into effect from the line on which it is
defined in the `Dockerfile` not from the argument's use on the command-line or
Expand All @@ -1408,9 +1417,21 @@ subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is
defined and the `what_user` value was passed on the command line. Prior to its definition by an
`ARG` instruction, any use of a variable results in an empty string.

> **Warning:** It is not recommended to use build-time variables for
> passing secrets like github keys, user credentials etc. Build-time variable
> values are visible to any user of the image with the `docker history` command.
An `ARG` instruction goes out of scope at the end of the build
stage where it was defined. To use an arg in multiple stages, each stage must
include the `ARG` instruction.

```
FROM busybox
ARG SETTINGS
RUN ./run/setup $SETTINGS

FROM busybox
ARG SETTINGS
RUN ./run/other $SETTINGS
```

### Using ARG variables

You can use an `ARG` or an `ENV` instruction to specify variables that are
available to the `RUN` instruction. Environment variables defined using the
Expand Down Expand Up @@ -1459,6 +1480,8 @@ from the command line and persist them in the final image by leveraging the
`ENV` instruction. Variable expansion is only supported for [a limited set of
Dockerfile instructions.](#environment-replacement)

### Predefined ARGs

Docker has a set of predefined `ARG` variables that you can use without a
corresponding `ARG` instruction in the Dockerfile.

Expand Down