add more buildkit docs #1493

tonistiigi · 2018-11-01T17:17:38Z

@tiborvass @AkihiroSuda @andrewhsu @thaJeztah

~~wip: the links to buildkit repo need moby/buildkit#710~~ merged

Feel free to carry or change directly on lot of changes.

Signed-off-by: Tonis Tiigi tonistiigi@gmail.com

codecov-io · 2018-11-01T17:23:56Z

Codecov Report

Merging #1493 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1493   +/-   ##
=======================================
  Coverage   55.23%   55.23%           
=======================================
  Files         289      289           
  Lines       19374    19374           
=======================================
  Hits        10702    10702           
  Misses       7977     7977           
  Partials      695      695

andrewhsu · 2018-11-01T22:22:52Z

docs/reference/builder.md

@@ -226,8 +248,61 @@ following lines are all treated identically:

 The following parser directive is supported:


The following parser directives are supported:

andrewhsu · 2018-11-01T22:25:32Z

cc @ahh-docker

andrewhsu

LGTM

AkihiroSuda · 2018-11-02T04:31:28Z

docs/reference/builder.md

+
+## BuildKit
+
+Starting from version 18.09, Docker supports a new backend for executing your


s/18.09/18.06/ ?

I think it is too complicated to explain the need to enable experimental for 18.06. If you want to just use BuildKit the recommendation is to upgrade to at least 18.09.

thaJeztah

Overall looks god; left some comments inline

also ping @ahh-docker PTAL

thaJeztah · 2018-11-06T15:51:25Z

docs/reference/builder.md

+## BuildKit
+
+Starting from version 18.09, Docker supports a new backend for executing your
+builds that is provided by [moby/buildkit](https://github.com/moby/buildkit)


provided by -> provided by the

thaJeztah · 2018-11-06T15:55:00Z

docs/reference/builder.md

+* Incrementally transfer only the changed files in your build context between builds
+* Detect and skip transferring unused files in your build context
+* Use external Dockerfile implementations with many new features
+* Avoid leaking dangling images and containers to the rest of the API


"leaking dangling images" makes it sound like it's a bug, but it's a limitation of the old builder. Perhaps something like; "Use a dedicated, configurable build cache, omitting the use of intermediate images as a caching mechanism".

thaJeztah · 2018-11-06T15:56:25Z

docs/reference/builder.md

+* Detect and skip transferring unused files in your build context
+* Use external Dockerfile implementations with many new features
+* Avoid leaking dangling images and containers to the rest of the API
+* Prioritize your build cache for automatic pruning


Not sure I understand the "Prioritize". Is this the configurable garbage collection?

That is gc and prune --keep-storage that removes unused based on priority.

thaJeztah · 2018-11-06T15:57:18Z

docs/reference/builder.md

+* Avoid leaking dangling images and containers to the rest of the API
+* Prioritize your build cache for automatic pruning
+
+To use the BuildKit backend in 18.09, you need to set an environment variable 


I'd remove the in 18.09 here; we generally try to avoid calling out which version something was introduced in (as the reference documentation is already versioned), and we already mention this in the introduction.

thaJeztah · 2018-11-06T15:59:49Z

docs/reference/builder.md

+* Prioritize your build cache for automatic pruning
+
+To use the BuildKit backend in 18.09, you need to set an environment variable 
+`DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`.


I think this is now also configurable in the CLI configuration file? (if so, we should have a link to that configuration somewhere). Could be in a new section "configure the Docker CLI to use the BuildKit builder" (e.g.)

Wondering which one we consider the "preferred" mechanism, and/or if we should call out (dis)advantages of both ways to configure.

(I'm ok with addressing that in a follow-up)

Some of it was covered by #1314

thaJeztah · 2018-11-06T16:04:21Z

docs/reference/builder.md

+external implementations of builders that are distributed as Docker images and 
+execute inside a container sandbox environment.
+
+Using a custom Dockerfile implementation allows you to:


"Using a" could be removed here;

Custom Dockerfile implementations allow you to:

Also, could you add a blank line between this line and the bullet-list?

thaJeztah · 2018-11-06T16:10:17Z

docs/reference/builder.md

+
+Here is the complete list of the different build `ARG` variables:
+
+* TARGETPLATFORM - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`.


Can you put the arg's in backticks? TARGETPLATFORM, TARGETOS (and so on)

thaJeztah · 2018-11-06T16:11:21Z

docs/reference/builder.md

+resulting image (target platform). The target platform can be specified with
+the `--platform` flag on `docker build`.
+
+Here is the complete list of the different build `ARG` variables:


Perhaps; "The following ARG variables are set automatically:"

thaJeztah · 2018-11-06T16:12:02Z

docs/reference/builder.md

+
+For example:
+
+```


Can you add Dockerfile code hint?

```Dockerfile

thaJeztah · 2018-11-06T16:13:42Z

docs/reference/builder.md

@@ -1931,6 +2038,14 @@ required such as `zsh`, `csh`, `tcsh` and others.

 The `SHELL` feature was added in Docker 1.12.

+## Experimental features


Probably needs a mention in the experimental docs; https://github.com/docker/cli/blob/master/experimental/README.md (ok for a follow-up)

This is not the same experimental. Changed to external to avoid confusion.

ahh-docker · 2018-11-06T19:41:00Z

@tonistiigi please add me as a reviewer. Thanks!

tonistiigi · 2018-11-08T21:37:27Z

@thaJeztah updated

tonistiigi · 2018-11-13T21:06:20Z

@thaJeztah ping. can we merge this as 18.09 is out.

vdemeester

LGTM 🐯

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Tibor Vass <tibor@docker.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

thaJeztah

LGTM

squashed the commits, and fixed one typo

tonistiigi requested review from thaJeztah and vdemeester as code owners November 1, 2018 17:17

GordonTheTurtle added the status/0-triage label Nov 1, 2018

tonistiigi force-pushed the buildkit-docs-update branch from f0f9375 to 0794a26 Compare November 1, 2018 17:29

andrewhsu reviewed Nov 1, 2018

View reviewed changes

andrewhsu approved these changes Nov 1, 2018

View reviewed changes

AkihiroSuda reviewed Nov 2, 2018

View reviewed changes

AkihiroSuda approved these changes Nov 3, 2018

View reviewed changes

thaJeztah added kind/docs status/3-docs-review area/builder and removed status/0-triage labels Nov 6, 2018

thaJeztah requested changes Nov 6, 2018

View reviewed changes

tonistiigi requested a review from ahh-docker November 6, 2018 19:41

vdemeester approved these changes Nov 14, 2018

View reviewed changes

buildkit reference docs

83aeb21

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Tibor Vass <tibor@docker.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

thaJeztah force-pushed the buildkit-docs-update branch from 4e922d5 to 83aeb21 Compare November 21, 2018 15:42

thaJeztah approved these changes Nov 21, 2018

View reviewed changes

thaJeztah merged commit e1d28fa into docker:master Nov 21, 2018

GordonTheTurtle added this to the 19.03.0 milestone Nov 21, 2018

thaJeztah mentioned this pull request Nov 21, 2018

[18.09 backport] builder documentation updates #1531

Merged

thaJeztah added the process/cherry-picked label Mar 18, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add more buildkit docs #1493

add more buildkit docs #1493

tonistiigi commented Nov 1, 2018 •

edited

Loading

codecov-io commented Nov 1, 2018 •

edited

Loading

andrewhsu Nov 1, 2018

andrewhsu commented Nov 1, 2018

andrewhsu left a comment

AkihiroSuda Nov 2, 2018

tonistiigi Nov 2, 2018

thaJeztah left a comment

thaJeztah Nov 6, 2018

thaJeztah Nov 6, 2018

thaJeztah Nov 6, 2018

tonistiigi Nov 6, 2018

thaJeztah Nov 6, 2018

thaJeztah Nov 6, 2018

tonistiigi Nov 6, 2018

thaJeztah Nov 6, 2018

thaJeztah Nov 6, 2018

thaJeztah Nov 6, 2018

thaJeztah Nov 6, 2018

thaJeztah Nov 6, 2018

tonistiigi Nov 6, 2018

ahh-docker commented Nov 6, 2018

tonistiigi commented Nov 8, 2018

tonistiigi commented Nov 13, 2018

vdemeester left a comment

thaJeztah left a comment

		@@ -226,8 +248,61 @@ following lines are all treated identically:

		The following parser directive is supported:


		## BuildKit

		Starting from version 18.09, Docker supports a new backend for executing your


		Here is the complete list of the different build `ARG` variables:

		* TARGETPLATFORM - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`.

		@@ -1931,6 +2038,14 @@ required such as `zsh`, `csh`, `tcsh` and others.

		The `SHELL` feature was added in Docker 1.12.

		## Experimental features


		For example:

		```

add more buildkit docs #1493

add more buildkit docs #1493

Conversation

tonistiigi commented Nov 1, 2018 • edited Loading

codecov-io commented Nov 1, 2018 • edited Loading

Codecov Report

Choose a reason for hiding this comment

andrewhsu commented Nov 1, 2018

andrewhsu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thaJeztah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahh-docker commented Nov 6, 2018

tonistiigi commented Nov 8, 2018

tonistiigi commented Nov 13, 2018

vdemeester left a comment

Choose a reason for hiding this comment

thaJeztah left a comment

Choose a reason for hiding this comment

tonistiigi commented Nov 1, 2018 •

edited

Loading

codecov-io commented Nov 1, 2018 •

edited

Loading