Commit 898ea4be authored by Steve Azzopardi's avatar Steve Azzopardi

Move Docker socket binding next to TLS/nonTLS alts

`Use Docker socket binding` is an alternative to [TLS
enabled](https://gitlab.com/gitlab-org/gitlab/-/blob/05ce22b8869cd308bcd259537eefd03ecf5f8f0e/doc/ci/docker/using_docker_build.md#L147)
and [TLS
disabled](https://gitlab.com/gitlab-org/gitlab/-/blob/05ce22b8869cd308bcd259537eefd03ecf5f8f0e/doc/ci/docker/using_docker_build.md#L244).
There is `Enable registry mirror for docker:dind service` in between
them which is unrelated.
parent 43ddc964
......@@ -363,6 +363,90 @@ build:
- docker run my-docker-image /script/to/run/tests
```
#### Use Docker socket binding
The third approach is to bind-mount `/var/run/docker.sock` into the
container so that Docker is available in the context of that image.
NOTE: **Note:**
If you bind the Docker socket [when using GitLab Runner 11.11 or
newer](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261),
you can no longer use `docker:19.03.12-dind` as a service because volume bindings
are done to the services as well, making these incompatible.
In order to do that, follow the steps:
1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/).
1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`:
```shell
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor docker \
--description "My Docker Runner" \
--docker-image "docker:19.03.12" \
--docker-volumes /var/run/docker.sock:/var/run/docker.sock
```
The above command registers a new runner to use the special
`docker:19.03.12` image which is provided by Docker. **Notice that it's using
the Docker daemon of the runner itself, and any containers spawned by Docker
commands are siblings of the runner rather than children of the runner.**
This may have complications and limitations that are unsuitable for your workflow.
The above command creates a `config.toml` entry similar to this:
```toml
[[runners]]
url = "https://gitlab.com/"
token = REGISTRATION_TOKEN
executor = "docker"
[runners.docker]
tls_verify = false
image = "docker:19.03.12"
privileged = false
disable_cache = false
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
[runners.cache]
Insecure = false
```
1. You can now use `docker` in the build script (note that you don't need to
include the `docker:19.03.12-dind` service as when using the Docker in Docker
executor):
```yaml
image: docker:19.03.12
before_script:
- docker info
build:
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
While the above method avoids using Docker in privileged mode, you should be
aware of the following implications:
- By sharing the Docker daemon, you are effectively disabling all
the security mechanisms of containers and exposing your host to privilege
escalation which can lead to container breakout. For example, if a project
ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner
containers.
- Concurrent jobs may not work; if your tests
create containers with specific names, they may conflict with each other.
- Sharing files and directories from the source repository into containers may not
work as expected since volume mounting is done in the context of the host
machine, not the build container. For example:
```shell
docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests
```
#### Enable registry mirror for `docker:dind` service
When the Docker daemon starts inside of the service container, it uses
......@@ -505,90 +589,6 @@ The configuration is picked up by the `dind` service.
sub_path = "daemon.json"
```
#### Use Docker socket binding
The third approach is to bind-mount `/var/run/docker.sock` into the
container so that Docker is available in the context of that image.
NOTE: **Note:**
If you bind the Docker socket [when using GitLab Runner 11.11 or
newer](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261),
you can no longer use `docker:19.03.12-dind` as a service because volume bindings
are done to the services as well, making these incompatible.
In order to do that, follow the steps:
1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/).
1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`:
```shell
sudo gitlab-runner register -n \
--url https://gitlab.com/ \
--registration-token REGISTRATION_TOKEN \
--executor docker \
--description "My Docker Runner" \
--docker-image "docker:19.03.12" \
--docker-volumes /var/run/docker.sock:/var/run/docker.sock
```
The above command registers a new runner to use the special
`docker:19.03.12` image which is provided by Docker. **Notice that it's using
the Docker daemon of the runner itself, and any containers spawned by Docker
commands are siblings of the runner rather than children of the runner.**
This may have complications and limitations that are unsuitable for your workflow.
The above command creates a `config.toml` entry similar to this:
```toml
[[runners]]
url = "https://gitlab.com/"
token = REGISTRATION_TOKEN
executor = "docker"
[runners.docker]
tls_verify = false
image = "docker:19.03.12"
privileged = false
disable_cache = false
volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
[runners.cache]
Insecure = false
```
1. You can now use `docker` in the build script (note that you don't need to
include the `docker:19.03.12-dind` service as when using the Docker in Docker
executor):
```yaml
image: docker:19.03.12
before_script:
- docker info
build:
stage: build
script:
- docker build -t my-docker-image .
- docker run my-docker-image /script/to/run/tests
```
While the above method avoids using Docker in privileged mode, you should be
aware of the following implications:
- By sharing the Docker daemon, you are effectively disabling all
the security mechanisms of containers and exposing your host to privilege
escalation which can lead to container breakout. For example, if a project
ran `docker rm -f $(docker ps -a -q)` it would remove the GitLab Runner
containers.
- Concurrent jobs may not work; if your tests
create containers with specific names, they may conflict with each other.
- Sharing files and directories from the source repository into containers may not
work as expected since volume mounting is done in the context of the host
machine, not the build container. For example:
```shell
docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests
```
## Making Docker-in-Docker builds faster with Docker layer caching
When using Docker-in-Docker, Docker downloads all layers of your image every
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment