build-docker-image: Add flag to use BuildKit

It seems like BuildKit is the next generation, but not likely to be
enabled by default soon (https://github.com/moby/moby/issues/40379).
Add a flag so people who want to use its features can easily opt-in.

Change-Id: I862819959c77a557199f64b4d42109bc7915959c

roles/build-docker-image/common.rst

@@ -80,6 +80,14 @@ using this role.
 
         repository: "^myorgname/{{ zuul.project.short_name }}.*"
 
+  .. zuul:rolevar:: docker_use_buildkit
+     :type: bool
+     :default: false
+
+     Use `BuildKit
+     <https://docs.docker.com/develop/develop-images/build_enhancements/>`__
+     when creating images.
+
 .. zuul:rolevar:: docker_images
    :type: list
 

roles/build-docker-image/defaults/main.yaml

@@ -1,3 +1,4 @@
 zuul_work_dir: "{{ zuul.project.src_dir }}"
 docker_dockerfile: "Dockerfile"
 docker_registry: ''
+docker_use_buildkit: false

roles/build-docker-image/tasks/build.yaml

@@ -28,6 +28,8 @@
     --label "org.zuul-ci.change_url={{ zuul.change_url }}"
   args:
     chdir: "{{ zuul_work_dir }}/{{ zj_image.context }}"
+  environment:
+    DOCKER_BUILDKIT: '{{ "1" if docker_use_buildkit else "0" }}'
 
 - name: Cleanup sibling source directory
   include_tasks: clean-siblings.yaml