github.com/containerd/nerdctl@v1.7.7/docs/build.md (about)

     1  # Setting up `nerdctl build` with BuildKit
     2  
     3  `nerdctl build` (and `nerdctl compose build`) relies on [BuildKit](https://github.com/moby/buildkit).
     4  To use it, you need to set up BuildKit.
     5  
     6  BuildKit has 2 types of backends.
     7  
     8  - **containerd worker**: BuildKit relies on containerd to manage containers and images, etc. containerd needs to be up-and-running on the host.
     9  - **OCI worker**: BuildKit manages containers and images, etc. containerd isn't needed. This worker relies on runc for container execution.
    10  
    11  You need to set up BuildKit with either of the above workers.
    12  
    13  Note that OCI worker cannot access base images (`FROM` images in Dockerfiles) managed by containerd.
    14  Thus you cannot let `nerdctl build` use containerd-managed images as the base image.
    15  They include images previously built using `nerdctl build`.
    16  
    17  For example, the following build `bar` fails with OCI worker because it tries to use the previously built and containerd-managed image `foo`.
    18  
    19  ```console
    20  $ mkdir -p /tmp/ctx && cat <<EOF > /tmp/ctx/Dockerfile
    21  FROM ghcr.io/stargz-containers/ubuntu:20.04-org
    22  RUN echo hello
    23  EOF
    24  $ nerdctl build -t foo /tmp/ctx
    25  $ cat <<EOF > /tmp/ctx/Dockerfile
    26  FROM foo
    27  RUN echo bar
    28  EOF
    29  $ nerdctl build -t bar /tmp/ctx
    30  ```
    31  
    32  This limitation can be avoided using containerd worker as mentioned later.
    33  
    34  ## Setting up BuildKit with containerd worker
    35  
    36  ### Rootless
    37  
    38  | :zap: Requirement | nerdctl >= 0.18, BuildKit >= 0.10 |
    39  |-------------------|-----------------------------------|
    40  
    41  ```
    42  $ CONTAINERD_NAMESPACE=default containerd-rootless-setuptool.sh install-buildkit-containerd
    43  ```
    44  
    45  `containerd-rootless-setuptool.sh` is aware of `CONTAINERD_NAMESPACE` and `CONTAINERD_SNAPSHOTTER` envvars.
    46  It installs buildkitd to the specified containerd namespace.
    47  This allows BuildKit using containerd-managed images in that namespace as the base image.
    48  Note that BuildKit can't use images in other namespaces as of now.
    49  
    50  If `CONTAINERD_NAMESPACE` envvar is not specified, this script configures buildkitd to use "buildkit" namespace (not "default" namespace).
    51  
    52  You can install an additional buildkitd process in a different namespace by executing this script with specifying the namespace with `CONTAINERD_NAMESPACE`.
    53  
    54  BuildKit will expose the socket at `$XDG_RUNTIME_DIR/buildkit-$CONTAINERD_NAMESPACE/buildkitd.sock` if `CONTAINERD_NAMESPACE` is specified.
    55  If `CONTAINERD_NAMESPACE` is not specified, that location will be `$XDG_RUNTIME_DIR/buildkit/buildkitd.sock`.
    56  
    57  ### Rootful
    58  
    59  ```
    60  $ sudo systemctl enable --now buildkit
    61  ```
    62  
    63  Then add the following configuration to `/etc/buildkit/buildkitd.toml` to enable containerd worker.
    64  
    65  ```toml
    66  [worker.oci]
    67    enabled = false
    68  
    69  [worker.containerd]
    70    enabled = true
    71    # namespace should be "k8s.io" for Kubernetes (including Rancher Desktop)
    72    namespace = "default"
    73  ```
    74  
    75  ## Setting up BuildKit with OCI worker
    76  
    77  ### Rootless
    78  
    79  ```
    80  $ containerd-rootless-setuptool.sh install-buildkit
    81  ```
    82  
    83  As mentioned in the above, BuildKit with this configuration cannot use images managed by containerd.
    84  They include images previously built with `nerdctl build`.
    85  
    86  BuildKit will expose the socket at `$XDG_RUNTIME_DIR/buildkit/buildkitd.sock`.
    87  
    88  ### rootful
    89  
    90  ```
    91  $ sudo systemctl enable --now buildkit
    92  ```
    93  
    94  ## Which BuildKit socket will nerdctl use?
    95  
    96  You can specify BuildKit address for `nerdctl build` using `--buildkit-host` flag or `BUILDKIT_HOST` envvar.
    97  When BuildKit address isn't specified, nerdctl tries some default BuildKit addresses the following order and uses the first available one.
    98  
    99  - `<runtime directory>/buildkit-<current namespace>/buildkitd.sock`
   100  - `<runtime directory>/buildkit-default/buildkitd.sock`
   101  - `<runtime directory>/buildkit/buildkitd.sock`
   102  
   103  For example, if you run rootless nerdctl with `test` containerd namespace, it tries to use `$XDG_RUNTIME_DIR/buildkit-test/buildkitd.sock` by default then try to fall back to `$XDG_RUNTIME_DIR/buildkit-default/buildkitd.sock` and `$XDG_RUNTIME_DIR/buildkit/buildkitd.sock`