GitLab Runner Docker vs Kubernetes executor

The Docker executor gives each job a clean build environment by running it inside a container, but every container is started on a runner host that you manage. GitLab's executor documentation says the Docker executor requires Docker on that host and accepts Podman as an alternative runtime. The runner process on the host picks up jobs from GitLab and launches containers from images, so the host is where your build capacity, container runtime and network access all live. Confirm with GitLab Runner's documentation which Docker or Podman versions your runner release supports before you standardize on one.

Your team owns the runner host operating system, the patch cadence for Docker or Podman, the disk and memory headroom that concurrent containers consume, and the cache and image storage on each host. Patching is a recurring task: a kernel or container runtime update may require draining jobs from the host first. Scale works by adding hosts and registering more runners, so capacity planning becomes a question of how many hosts you run and how they are sized. Build a runbook for host replacement and decide whether hosts are long-lived or rebuilt from images, since long-lived hosts accumulate state that can leak between jobs.

This is the simpler choice when you run a small number of runners, your jobs need no more than a few hosts, and your team has no Kubernetes operations skills. You avoid operating a cluster and its control plane, and a single host can be debugged directly with standard container tools. It stops being simpler once you need elastic scaling across many runners, uniform host images across several sites, or the isolation and autoscaling patterns covered in the Kubernetes section below.

Both executors give each build a clean environment, but the boundary around that build is different. With the Docker executor, each job runs in a container on a runner host, so the shared surface is the host kernel, the Docker daemon and anything else that host carries. With the Kubernetes executor, each job runs in a pod inside a cluster shared with other workloads, so the boundary depends on namespaces, RBAC, network policy and Pod Security Standards. Decide first which boundary your risk model accepts, then confirm the controls that enforce it. Ask your runner and cluster owners which namespaces, service accounts and node pools the runner will use, and whether privileged containers or host mounts are allowed in the job's namespace.

Secrets need the most care on the Kubernetes side. Kubernetes stores Secrets unencrypted in etcd by default, so a platform team has to confirm that encryption at rest is enabled for the cluster before any CI credential is placed there. Access to Secrets should be limited with least-privilege RBAC, and list and watch permissions on Secrets should be restricted because they expose values to anyone who holds them. Some teams prefer an external store through the Secrets Store CSI Driver. On the Docker executor, the equivalent question is where variables and registry credentials live on the runner host, who can read the runner configuration file and whether the host's file permissions and backups protect those values. Write both answers into your review checklist.

Debugging differs most after a failure. A Docker executor job can often be reproduced on the runner host itself, by re-running the same image with the same variables and inspecting leftover state, although that state should not be trusted to persist. A Kubernetes executor pod is removed after the job finishes, so there is no host to log into and no pod to inspect unless the job's output and the cluster's event and container logs were kept. Plan log retention in the cluster's logging stack before go-live, and confirm with your platform team how long pod logs and Kubernetes events survive, who can read them and whether job logs are stored in GitLab with the retention you need. Without that plan, a failed deployment in a pod-per-job setup may leave nothing to examine.

The main cost of either executor is the infrastructure underneath it, not the GitLab license. With the Docker executor, you pay for the runner host capacity, Docker or Podman on that host, and the storage used for caches. With the Kubernetes executor, you pay for cluster capacity that runs job pods, and you also carry the cluster itself: control plane nodes, etcd backups and upgrades. Those recurring costs rise with concurrent jobs, job length and how much cache you keep. Confirm with your own platform team how many nodes and how much storage your peak concurrency needs before you compare any quote.

GitLab licensing is a separate line item. GitLab Free, Premium and Ultimate are all available for self-managed installations, and the tier you already hold does not change which executor you can use. Current tier prices are on the GitLab pricing page, where Premium is listed per user per month billed annually and Ultimate is custom priced. Also account for people: the Kubernetes route usually needs staff who can run the cluster, while the Docker route needs staff who can patch and rebuild runner hosts. Ask any implementation partner for a written scope that separates these one-time build work from recurring support, upgrades and testing.

Switching later costs more than the pipeline files suggest. A .gitlab-ci.yml job often moves between executors with little change, but the surrounding configuration does not. Runner tags, the config.toml executor settings, cache locations, and per-concurrency build volumes for clone reuse all have to be rebuilt, and the host or cluster beneath them has to be provisioned again. Before you choose, decide whether clone reuse matters to your jobs, and write down which runner tags your pipelines depend on. A partner can estimate the rebuild effort only from a written scope that lists those tags, volumes and infrastructure.