Build Docker Images on Kubernetes Runners Without Privileged Mode

Build Docker images in GitHub Actions on Kubernetes runners without privileged: true, using a rootless remote BuildKit daemon or Kaniko.

Published

At a glance

Last reviewed
Versions referenced
actions/checkout@v7 docker/login-action@v4 docker/setup-buildx-action@v4 docker/build-push-action@v7
Reading time
4 min read

Code samples are not run in a live repository. See our editorial standards.

On this page

Run BuildKit as a separate rootless Deployment in the cluster and point the runner at it with the Buildx remote driver. The runner pod then needs no privileged: true, no Docker daemon and no /var/run/docker.sock. Kaniko is the alternative when you cannot run a long-lived builder.

Docker-in-Docker mode in Actions Runner Controller (ARC) needs a privileged sidecar, and Kubernetes container mode does not give you a Docker daemon for docker build. Both gaps are why you need an external builder.

Option 1: Remote rootless BuildKit

Deploy the BuildKit daemon

Create the buildkit namespace, then apply this manifest. The rootless image runs as UID 1000. It needs the Unconfined seccomp and AppArmor profiles so it can create user namespaces, but the container is not privileged.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: buildkitd
  namespace: buildkit
spec:
  replicas: 1
  selector:
    matchLabels:
      app: buildkitd
  template:
    metadata:
      labels:
        app: buildkitd
    spec:
      containers:
        - name: buildkitd
          image: moby/buildkit:v0.19.0-rootless
          args:
            - --addr
            - unix:///run/user/1000/buildkit/buildkitd.sock
            - --addr
            - tcp://0.0.0.0:1234
            - --oci-worker-no-process-sandbox
          securityContext:
            runAsUser: 1000
            runAsGroup: 1000
            seccompProfile:
              type: Unconfined
            appArmorProfile:
              type: Unconfined
          ports:
            - containerPort: 1234
              name: buildkitd
---
apiVersion: v1
kind: Service
metadata:
  name: buildkitd
  namespace: buildkit
spec:
  selector:
    app: buildkitd
  ports:
    - port: 1234
      targetPort: 1234
      name: buildkitd

--oci-worker-no-process-sandbox is required for rootless mode inside a container without a dedicated PID namespace. The appArmorProfile field needs Kubernetes 1.30 or later. On older clusters, use the container.apparmor.security.beta.kubernetes.io/buildkitd: unconfined annotation instead.

This TCP endpoint has no authentication. Anyone who can reach the Service can run builds and read your cache. Restrict ingress with a NetworkPolicy that admits only the runner namespace, or enable mTLS on the daemon and use the cacert, cert and key options of the remote driver.

Add the Docker CLI and Buildx to the runner image

docker/build-push-action calls docker buildx, so the runner image needs the Docker CLI and the Buildx plugin. It does not need dockerd.

FROM ghcr.io/actions/actions-runner:latest

USER root

RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates docker.io \
 && rm -rf /var/lib/apt/lists/* \
 && mkdir -p /usr/local/lib/docker/cli-plugins \
 && curl -fsSL -o /usr/local/lib/docker/cli-plugins/docker-buildx \
    https://github.com/docker/buildx/releases/download/v0.21.1/buildx-v0.21.1.linux-amd64 \
 && chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx

USER runner

Installing docker.io also installs the daemon binaries, but nothing starts them. If you prefer a smaller image, install only the Docker CLI package from Docker’s apt repository. Keep the runner binary in /home/runner/ and launched by /home/runner/run.sh, as ARC requires.

Use the remote driver in the workflow

name: Build and push with remote BuildKit

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: [self-hosted, linux]
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v7

      - uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/setup-buildx-action@v4
        with:
          driver: remote
          endpoint: tcp://buildkitd.buildkit.svc.cluster.local:1234

      - uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest

For an ARC runner scale set, replace the runs-on value with the name of your scale set (the Helm installation name) as a single label. The runner uploads the build context over gRPC and the daemon does all layer work.

To verify, open the Set up Docker Buildx step log and confirm the builder uses the remote driver and your endpoint. Then check that the build step completes and the tag appears under the repository’s Packages. If the endpoint is unreachable, the setup step fails. Check the Service name, the namespace, and any NetworkPolicy first.

Option 2: Kaniko

Kaniko builds in userspace without a daemon, so it needs no privileged mode. It does typically run as root (UID 0) inside its own container. That is not the same as privileged: true, but it means the job cannot run as the non-root runner user.

The Kaniko project under GoogleContainerTools was archived in 2025. Check the maintenance status of the fork you use before adopting it.

Copy the executor into a custom runner image:

FROM gcr.io/kaniko-project/executor:v1.23.2 AS kaniko

FROM ghcr.io/actions/actions-runner:latest
COPY --from=kaniko /kaniko /kaniko

Then run it from a workflow step. Write the registry credentials to a directory and point DOCKER_CONFIG at it:

name: Build with Kaniko

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: [self-hosted, linux]
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v7

      - name: Write registry credentials
        env:
          REGISTRY_USER: ${{ github.actor }}
          REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          mkdir -p "$RUNNER_TEMP/docker"
          AUTH=$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_TOKEN" | base64 -w0)
          printf '{"auths":{"ghcr.io":{"auth":"%s"}}}' "$AUTH" > "$RUNNER_TEMP/docker/config.json"

      - name: Build and push
        env:
          DOCKER_CONFIG: ${{ runner.temp }}/docker
        run: |
          /kaniko/executor \
            --context="dir://${GITHUB_WORKSPACE}" \
            --dockerfile="${GITHUB_WORKSPACE}/Dockerfile" \
            --destination="ghcr.io/${GITHUB_REPOSITORY}:latest"

As above, set runs-on to the name of the scale set that uses the Kaniko runner image. Secrets go through env: rather than being interpolated into the script, so they cannot alter the shell command. Kaniko extracts base image layers into its own root filesystem. Run it only in an ephemeral pod, never on a shared host.

To verify, confirm the build step exits successfully and the image tag appears in the repository’s Packages.

Caching trade-offs

Runner pods are ephemeral, so any cache stored in the pod disappears with it.

Approach Where cache lives Consequence
Remote BuildKit Daemon’s local store Persists while the daemon pod and its volume live. Mount a PVC to survive pod restarts.
Buildx with registry cache Registry Works with any builder. Adds push and pull time every run.
Kaniko Registry via --cache=true and --cache-repo Needs a dedicated cache repository. Each cached layer is a registry round trip.

For Buildx with the remote driver, you can add cache-from: type=registry,ref=ghcr.io/OWNER/REPO:buildcache and cache-to: type=registry,ref=ghcr.io/OWNER/REPO:buildcache,mode=max to build-push-action. Replace OWNER/REPO with your repository. mode=max exports intermediate stages of multi-stage builds. Without it only the final image layers are cached. For a related walkthrough, see GitHub Actions Docker Build and Push with Layer Caching.

A cached RUN apt-get update or RUN curl layer is reused until an earlier layer or a build argument changes. Pass a build argument that changes when you want a fresh fetch.

Troubleshooting

  • Job fails on /var/run/docker.sock: the step is running docker build with the default builder. Run docker/setup-buildx-action with the remote driver before the build, or pass --builder explicitly.
  • BuildKit pod crashes at startup: the seccomp or AppArmor profile is blocking user namespaces. Confirm both are Unconfined and that --oci-worker-no-process-sandbox is set. Check kubectl logs -n buildkit deploy/buildkitd.
  • Permission denied on mounted volumes: the runner runs as a non-root user and the volume has different ownership. Set securityContext.fsGroup in the runner pod template, or fix ownership in an init container.
  • A build needs extra Linux capabilities: GitHub Actions supports only Docker’s default capabilities, and you cannot add or remove them. Do the privileged work in the BuildKit pod, not the runner.

Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.