Architectural Paradigms for Containerized Image Construction in GitLab CI/CD

The intersection of containerization and Continuous Integration/Continuous Deployment (CI/CD) represents a fundamental pillar of modern DevOps engineering. Within the GitLab ecosystem, the requirement to build, test, and push Docker images introduces a complex layer of abstraction: the challenge of executing container-based workflows within an environment that is itself encapsulated by a container. By default, GitLab CI/CD pipelines execute jobs within isolated Docker containers, creating a nesting problem where a containerized process must somehow orchestrate its own containerization. This architectural friction necessitates a deep understanding of various execution strategies, ranging from the traditional Docker-in-Docker (DinD) approach to the more modern, daemonless Podman implementation and the socket passthrough method. Successfully navigating these choices dictates the security posture, resource efficiency, and operational complexity of the entire software delivery lifecycle.

The Core Challenge of Nested Containerization

In a standard GitLab CI environment, the GitLab Runner acts as the orchestrator, spawning a container to execute the specific instructions defined in the .gitlab-ci.yml configuration file. This creates a fundamental impedance mismatch when the job instructions themselves include commands like docker build or docker push. Because the job is running inside a container, it lacks direct access to the host's Docker daemon, which is the engine responsible for the heavy lifting of image construction and container lifecycle management.

The Docker Command Line Interface (CLI) is essentially a client that communicates with a backend entity known as dockerd. The CLI does not perform the actual construction of layers or the management of file systems; it sends instructions via an API to the dockerd daemon, which performs the actual work of running containers or building images. When a job runs in a standard GitLab Runner container, the dockerd process is absent from the job's local environment, leading to common connection failures such as Cannot connect to the Docker daemon at tcp://docker:2375.

To overcome this, engineers must choose between providing a local daemon within the job, exposing the host's daemon to the job, or utilizing a daemonless alternative.

Docker-in-Docker (DinD) Methodology

Docker-in-Docker (DinD) is a classic technique used to solve the nesting problem by running a completely independent Docker daemon inside the container where the CI job is executing. This approach provides high isolation, as the inner daemon operates within its own environment, separate from the host's Docker engine.

To implement DinD, GitLab CI allows the use of "services." A service is a secondary container that runs alongside the main job container. By configuring the job to run the docker:dind image as a service, the GitLab Runner starts a container that hosts the dockerd daemon. The job container then communicates with this service container over the network.

Implementing DinD via GitLab CI Configuration

To establish a successful DinD workflow, the .gitlab-ci.yml file must be explicitly configured to define the service, provide a hostname for communication, and set the necessary environment variables to bridge the gap between the CLI and the service daemon.

The following configuration demonstrates the standard implementation:

yaml dind-build: services: - name: docker:dind alias: dockerdaemon variables: DOCKER_HOST: tcp://dockerdaemon:2375/ script: - docker build -t my-application:latest . - docker push my-application:latest

In this configuration, several critical components are at play:

• The services block initiates the docker:dind container.
• The alias attribute assigns the hostname dockerdaemon to the service container, allowing the job container to resolve its location via DNS.
• The DOCKER_HOST environment variable tells the Docker CLI to redirect all API calls to the tcp://dockerdaemon:2375/ endpoint instead of attempting to find a local Unix socket.

Security Implications of Privileged Mode

A significant drawback of the DinD approach is the requirement for "privileged mode." For a Docker daemon to run inside a container, that container must be granted elevated permissions by the host operating system. This is achieved by setting privileged = true in the GitLab Runner's config.toml.

Using privileged mode effectively breaks the isolation boundary between the container and the host. If a malicious actor manages to compromise a job running in a privileged DinD container, they potentially gain significant control over the host machine. Consequently, while DinD is highly functional, it introduces a substantial security risk that must be managed through strict access controls and network segmentation.

Socket Passthrough and Bind-Mounts

An alternative to running a full daemon inside a container is the socket passthrough method. This technique involves mounting the host's Docker Unix socket (/var/run/docker.sock) directly into the job container. This allows the containerized job to communicate with the Docker daemon running on the host machine.

The Socket Passthrough Architecture

By using a socket passthrough, the job container essentially "borrows" the host's engine to perform its tasks. This eliminates the need for a separate docker:dind service and avoids the overhead of running a nested daemon.

A common configuration for a GitLab Runner using this method involves the following config.toml settings:

toml [[runners]] name = "docker-socket" url = "https://<your gitlab server>" token = "<your runner token>" executor = "docker" [runners.docker] image = "docker:edge-git" privileged = false volumes = ["/builds:/builds", "/cache", "/var/run/docker.sock:/var/run/docker.sock"]

In this specific setup:

• The privileged = false setting is crucial, as it demonstrates that socket passthrough can be performed without granting full host privileges, offering a more secure alternative to DinD.
• The volumes array contains the critical instruction "/var/run/docker.sock:/var/run/docker.sock". This bind-mount maps the host's Docker socket to the same path inside the container.
• The volume "/builds:/builds" is often used to ensure that the build directory remains accessible and consistent between the host and the container.

Integration Testing with Bind-Mounts

The ability to use bind-mounts extends beyond just Docker operations; it is also highly effective for integration testing. If an application is designed to store its persistent data in a specific directory, such as /app/data, testers can mount a directory from the Git repository into that path within the container.

Example testing workflow in .gitlab-ci.yml:

yaml image: docker:20.10.16 variables: DOCKER_REGISTRY: my-docker-registry.com DOCKER_REGISTRY_USER: gitlab DOCKER_IMAGE: ${DOCKER_REGISTRY}/my-app before_script: - docker login -u ${DOCKER_REGISTRY_USER} -p ${CI_BUILD_TOKEN} ${DOCKER_REGISTRY} build_and_test: script: - docker build -t ${DOCKER_IMAGE} -f Dockerfile . - docker run --rm -v$(pwd)/test/int-00:/app/data ${DOCKER_IMAGE} npm test - docker push ${DOCKER_IMAGE}

In this workflow, the command docker run --rm -v$(pwd)/test/int-00:/app/data ${DOCKER_IMAGE} npm test performs several functions:

• --rm: Removes the container immediately after the test completes to keep the environment clean.
• -v$(pwd)/test/int-00:/app/data: Uses a bind-mount to inject test data from the current working directory into the application's expected data path.
• npm test: Executes the test suite within the newly built container using the injected data.

The Podman Alternative: A Daemonless Evolution

As the industry moves toward more secure and efficient container orchestration, Podman has emerged as a formidable alternative to Docker. Podman is a reimplementation of the Docker CLI that operates on a fundamentally different architecture. Unlike Docker, Podman does not require a background daemon (dockerd) to function. Instead, the Podman CLI performs the container operations directly.

Advantages of Podman in GitLab CI

The daemonless nature of Podman provides several immediate benefits for GitLab CI/CD pipelines:

• Security: Since there is no central daemon, there is no need for privileged mode, significantly reducing the attack surface.
• Simplicity: There is no need to manage DOCKER_HOST variables or complex service configurations to communicate with a remote daemon.
• Compatibility: Podman is designed to be a drop-in replacement for Docker, supporting nearly identical command-line arguments.

Implementing Podman Workflows

Because Podman's CLI is so similar to Docker's, migrating a pipeline from Docker to Podman is often as simple as changing the image name and replacing the docker command with podman.

The standard Podman implementation in .gitlab-ci.yml is highly streamlined:

```yaml
stages:
- build

podman-build:
stage: build
image:
name: quay.io/podman/stable
script:
- podman login -u "$CIREGISTRYUSER" -p "$CIREGISTRYPASSWORD" "$CIREGISTRY"
- podman build -t "$CIREGISTRYIMAGE:podman" .
- podman push "$CIREGISTRY_IMAGE:podman"
```

For teams that are not ready to fully abandon their existing docker scripts, Podman offers a clever bridge via symbolic links. By using an image that contains both tools, one can alias the docker command to call podman directly:

```yaml
stages:
- build

podman-build:
stage: build
image:
name: quay.io/podman/stable
script:
- ln -s /usr/bin/podman /usr/bin/docker
- docker login -u "$CIREGISTRYUSER" -p "$CIREGISTRYPASSWORD" "$CIREGISTRY"
- docker build -t "$CIREGISTRYIMAGE:podman" .
- docker push "$CIREGISTRY_IMAGE:podman"
```

In this second example, the ln -s /usr/bin/podman /usr/bin/docker command creates a symbolic link, allowing the subsequent docker commands to be executed by the Podman engine.

Comparative Analysis of Execution Methods

To select the optimal strategy, one must evaluate the trade-offs between isolation, security, and ease of implementation. The following table provides a technical comparison of the primary methods available for GitLab CI.

Technical Breakdown of Executor Types

The choice of executor dictates how the GitLab Runner interacts with the underlying hardware and software.

• Docker Executor: Spawns a new container for every job. This is the most common and provides the best balance of isolation and reproducibility.
• Shell Executor: Executes commands directly on the host machine's shell. This is the fastest method as it avoids container overhead, but it offers almost no isolation. The gitlab-runner user must be granted specific permissions to run Docker commands on the host, which can lead to security vulnerabilities if not managed carefully.

Summary of Configuration Options

The following table summarizes the various GitLab offerings and their compatibility with container-based CI/CD workflows.

Conclusion

The evolution of containerized CI/CD within GitLab reflects a broader industry shift toward increased security and decreased architectural complexity. While the Docker-in-Docker (DinD) method remains a reliable standard for providing highly isolated environments, its reliance on privileged mode presents a significant security challenge that modern DevOps practices increasingly seek to avoid. Socket passthrough offers a middle ground, leveraging host resources for efficiency, but it requires careful management of the Docker socket.

Podman represents the most significant advancement in this space, offering a daemonless architecture that aligns perfectly with the principle of least privilege. By removing the need for a central daemon, Podman simplifies the .gitlab-ci.yml configuration and enhances the security of the entire pipeline. Ultimately, the selection of a containerization strategy—whether it be the nested daemon of DinD, the socket passthrough, or the daemonless Podman—must be a deliberate decision based on the specific security requirements, resource constraints, and operational maturity of the organization's infrastructure.

Sources

1. PythonSpeed: Building Docker images on GitLab CI
2. GitLab Documentation: Use Docker to build Docker images
3. Hiebl: Setting up Docker in Docker (dind/socket) with GitLab Runners
4. OneUptime: Docker GitLab CI Runner