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.
At a glance
- Last reviewed
- Versions referenced
actions/checkout@v7docker/login-action@v4docker/setup-buildx-action@v4docker/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 runningdocker buildwith the default builder. Rundocker/setup-buildx-actionwith the remote driver before the build, or pass--builderexplicitly. - BuildKit pod crashes at startup: the seccomp or AppArmor profile is blocking user namespaces. Confirm both are
Unconfinedand that--oci-worker-no-process-sandboxis set. Checkkubectl 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.fsGroupin 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.