using_docker_images.md 31,3 КБ
Newer Older
Evan Read's avatar
Evan Read включено в состав коммита
1
---
GitLab Bot's avatar
GitLab Bot включено в состав коммита
2
3
4
stage: Verify
group: Runner
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
Evan Read's avatar
Evan Read включено в состав коммита
5
6
7
type: concepts, howto
---

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
8
# Using Docker images
Douwe Maan's avatar
Douwe Maan включено в состав коммита
9

GitLab Bot's avatar
GitLab Bot включено в состав коммита
10
GitLab CI/CD in conjunction with [GitLab Runner](../runners/README.md) can use
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
11
[Docker Engine](https://www.docker.com/) to test and build any application.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
12

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
13
14
Docker is an open-source project that allows you to use predefined images to
run applications in independent "containers" that are run within a single Linux
GitLab Bot's avatar
GitLab Bot включено в состав коммита
15
instance. [Docker Hub](https://hub.docker.com/) has a rich database of pre-built images that can be
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
16
used to test and build your applications.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
17

GitLab Bot's avatar
GitLab Bot включено в состав коммита
18
When used with GitLab CI/CD, Docker runs each job in a separate and isolated
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
19
20
container using the predefined image that is set up in
[`.gitlab-ci.yml`](../yaml/README.md).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
21
22
23
24

This makes it easier to have a simple and reproducible build environment that
can also run on your workstation. The added benefit is that you can test all
the commands that we will explore later from your shell, rather than having to
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
25
test them on a dedicated CI server.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
26

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
27
## Register Docker Runner
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
28

GitLab Bot's avatar
GitLab Bot включено в состав коммита
29
To use GitLab Runner with Docker you need to [register a new Runner](https://docs.gitlab.com/runner/register/)
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
30
31
to use the `docker` executor.

GitLab Bot's avatar
GitLab Bot включено в состав коммита
32
33
34
35
36
37
38
39
40
41
42
43
44
45
An example can be seen below. First we set up a temporary template to supply the services:

```shell
cat > /tmp/test-config.template.toml << EOF
[[runners]]
[runners.docker]
[[runners.docker.services]]
name = "postgres:latest"
[[runners.docker.services]]
name = "mysql:latest"
EOF
```

Then we register the runner using the template that was just created:
Douwe Maan's avatar
Douwe Maan включено в состав коммита
46

GitLab Bot's avatar
GitLab Bot включено в состав коммита
47
```shell
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
48
49
sudo gitlab-runner register \
  --url "https://gitlab.example.com/" \
Douwe Maan's avatar
Douwe Maan включено в состав коммита
50
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
GitLab Bot's avatar
GitLab Bot включено в состав коммита
51
  --description "docker-ruby:2.6" \
Douwe Maan's avatar
Douwe Maan включено в состав коммита
52
  --executor "docker" \
GitLab Bot's avatar
GitLab Bot включено в состав коммита
53
54
  --template-config /tmp/test-config.template.toml \
  --docker-image ruby:2.6
Douwe Maan's avatar
Douwe Maan включено в состав коммита
55
56
```

GitLab Bot's avatar
GitLab Bot включено в состав коммита
57
The registered runner will use the `ruby:2.6` Docker image and will run two
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
58
59
60
services, `postgres:latest` and `mysql:latest`, both of which will be
accessible during the build process.

Wilfred Hughes's avatar
Wilfred Hughes включено в состав коммита
61
## What is an image
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
62

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
63
64
The `image` keyword is the name of the Docker image the Docker executor
will run to perform the CI tasks.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
65

GitLab Bot's avatar
GitLab Bot включено в состав коммита
66
By default, the executor will only pull images from [Docker Hub](https://hub.docker.com/),
Evan Read's avatar
Evan Read включено в состав коммита
67
however this can be configured in the `gitlab-runner/config.toml` by setting
GitLab Bot's avatar
GitLab Bot включено в состав коммита
68
the [Docker pull policy](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work) to allow using local images.
Adam Boseley's avatar
Adam Boseley включено в состав коммита
69

Evan Read's avatar
Evan Read включено в состав коммита
70
For more information about images and Docker Hub, please read
GitLab Bot's avatar
GitLab Bot включено в состав коммита
71
the [Docker Fundamentals](https://docs.docker.com/engine/understanding-docker/) documentation.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
72

Wilfred Hughes's avatar
Wilfred Hughes включено в состав коммита
73
## What is a service
Douwe Maan's avatar
Douwe Maan включено в состав коммита
74

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
75
76
The `services` keyword defines just another Docker image that is run during
your job and is linked to the Docker image that the `image` keyword defines.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
77
This allows you to access the service image during build time.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
78

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
79
The service image can run any application, but the most common use case is to
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
80
run a database container, e.g., `mysql`. It's easier and faster to use an
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
81
82
existing image and run it as an additional container than install `mysql` every
time the project is built.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
83

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
84
85
You are not limited to have only database services. You can add as many
services you need to `.gitlab-ci.yml` or manually modify `config.toml`.
GitLab Bot's avatar
GitLab Bot включено в состав коммита
86
Any image found at [Docker Hub](https://hub.docker.com/) or your private Container Registry can be
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
87
88
used as a service.

Florian Klink's avatar
Florian Klink включено в состав коммита
89
90
91
Services inherit the same DNS servers, search domains, and additional hosts as
the CI container itself.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
92
93
You can see some widely used services examples in the relevant documentation of
[CI services examples](../services/README.md).
Douwe Maan's avatar
Douwe Maan включено в состав коммита
94

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
95
### How services are linked to the job
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
96
97

To better understand how the container linking works, read
GitLab Bot's avatar
GitLab Bot включено в состав коммита
98
[Linking containers together](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
99
100

To summarize, if you add `mysql` as service to your application, the image will
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
101
then be used to create a container that is linked to the job container.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
102
103
104

The service container for MySQL will be accessible under the hostname `mysql`.
So, in order to access your database service you have to connect to the host
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
105
106
107
named `mysql` instead of a socket or `localhost`. Read more in [accessing the
services](#accessing-the-services).

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
108
### How the health check of services works
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
109
110

Services are designed to provide additional functionality which is **network accessible**.
Philippe Lafoucrière's avatar
Philippe Lafoucrière включено в состав коммита
111
It may be a database like MySQL, or Redis, and even `docker:stable-dind` which
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
112
113
allows you to use Docker in Docker. It can be practically anything that is
required for the CI/CD job to proceed and is accessed by network.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
114

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
115
To make sure this works, the Runner:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
116

Evan Read's avatar
Evan Read включено в состав коммита
117
118
1. Checks which ports are exposed from the container by default.
1. Starts a special container that waits for these ports to be accessible.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
119

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
120
121
122
When the second stage of the check fails, either because there is no opened port in the
service, or the service was not started properly before the timeout and the port is not
responding, it prints the warning: `*** WARNING: Service XYZ probably didn't start properly`.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
123

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
124
125
In most cases it will affect the job, but there may be situations when the job
will still succeed even if that warning was printed. For example:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
126

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
127
- The service was started a little after the warning was raised, and the job is
Evan Read's avatar
Evan Read включено в состав коммита
128
  not using the linked service from the beginning. In that case, when the
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
129
130
131
132
133
134
  job needed to access the service, it may have been already there waiting for
  connections.
- The service container is not providing any networking service, but it's doing
  something with the job's directory (all services have the job directory mounted
  as a volume under `/builds`). In that case, the service will do its job, and
  since the job is not trying to connect to it, it won't fail.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
135
136
137
138

### What services are not for

As it was mentioned before, this feature is designed to provide **network accessible**
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
139
services. A database is the simplest example of such a service.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
140

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
141
142
143
NOTE: **Note:**
The services feature is not designed to, and will not add any software from the
defined `services` image(s) to the job's container.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
144

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
145
146
147
For example, if you have the following `services` defined in your job, the `php`,
`node` or `go` commands will **not** be available for your script, and thus
the job will fail:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
148
149
150
151
152
153
154
155
156
157
158
159
160
161

```yaml
job:
  services:
  - php:7
  - node:latest
  - golang:1.10
  image: alpine:3.7
  script:
  - php -v
  - node -v
  - go version
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
162
163
If you need to have `php`, `node` and `go` available for your script, you should
either:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
164

Evan Read's avatar
Evan Read включено в состав коммита
165
166
167
- Choose an existing Docker image that contains all required tools.
- Create your own Docker image, which will have all the required tools included
  and use that in your job.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
168

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
169
170
171
172
### Accessing the services

Let's say that you need a Wordpress instance to test some API integration with
your application.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
173

GitLab Bot's avatar
GitLab Bot включено в состав коммита
174
You can then use for example the [tutum/wordpress](https://hub.docker.com/r/tutum/wordpress/) image in your
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
175
`.gitlab-ci.yml`:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
176

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
177
178
179
180
```yaml
services:
- tutum/wordpress:latest
```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
181

Johan Brandhorst's avatar
Johan Brandhorst включено в состав коммита
182
If you don't [specify a service alias](#available-settings-for-services),
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
183
184
when the job is run, `tutum/wordpress` will be started and you will have
access to it from your build container under two hostnames to choose from:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
185

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
186
187
- `tutum-wordpress`
- `tutum__wordpress`
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
188

Evan Read's avatar
Evan Read включено в состав коммита
189
NOTE: **Note:**
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
190
191
192
193
194
195
Hostnames with underscores are not RFC valid and may cause problems in 3rd party
applications.

The default aliases for the service's hostname are created from its image name
following these rules:

Evan Read's avatar
Evan Read включено в состав коммита
196
- Everything after the colon (`:`) is stripped.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
197
- Slash (`/`) is replaced with double underscores (`__`) and the primary alias
Evan Read's avatar
Evan Read включено в состав коммита
198
  is created.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
199
- Slash (`/`) is replaced with a single dash (`-`) and the secondary alias is
Evan Read's avatar
Evan Read включено в состав коммита
200
  created (requires GitLab Runner v1.1.0 or higher).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
201
202

To override the default behavior, you can
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
203
[specify a service alias](#available-settings-for-services).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
204
205

## Define `image` and `services` from `.gitlab-ci.yml`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
206
207

You can simply define an image that will be used for all jobs and a list of
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
208
services that you want to use during build time:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
209
210

```yaml
Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
211
default:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
212
  image: ruby:2.6
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
213

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
214
  services:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
215
    - postgres:11.7
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
216

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
217
218
  before_script:
    - bundle install
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
219

Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
220
221
222
223
224
test:
  script:
  - bundle exec rake spec
```

GitLab Bot's avatar
GitLab Bot включено в состав коммита
225
226
227
228
229
230
The image name must be in one of the following formats:

- `image: <image-name>` (Same as using `<image-name>` with the `latest` tag)
- `image: <image-name>:<tag>`
- `image: <image-name>@<digest>`

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
231
232
233
It is also possible to define different images and services per job:

```yaml
Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
234
235
236
default:
  before_script:
    - bundle install
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
237

GitLab Bot's avatar
GitLab Bot включено в состав коммита
238
239
test:2.6:
  image: ruby:2.6
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
240
  services:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
241
  - postgres:11.7
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
242
243
244
  script:
  - bundle exec rake spec

GitLab Bot's avatar
GitLab Bot включено в состав коммита
245
246
test:2.7:
  image: ruby:2.7
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
247
  services:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
248
  - postgres:12.2
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
249
250
251
252
  script:
  - bundle exec rake spec
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
253
254
Or you can pass some [extended configuration options](#extended-docker-configuration-options)
for `image` and `services`:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
255
256

```yaml
Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
257
258
default:
  image:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
259
    name: ruby:2.6
Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
260
    entrypoint: ["/bin/bash"]
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
261

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
262
  services:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
263
  - name: my-postgres:11.7
Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
264
265
266
    alias: db-postgres
    entrypoint: ["/usr/local/bin/db-postgres"]
    command: ["start"]
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
267

Kamil Trzciński's avatar
Kamil Trzciński включено в состав коммита
268
269
  before_script:
  - bundle install
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
270
271
272
273
274
275

test:
  script:
  - bundle exec rake spec
```

Thad Guidry's avatar
Thad Guidry включено в состав коммита
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
## Passing environment variables to services

You can also pass custom environment [variables](../variables/README.md)
to fine tune your Docker `images` and `services` directly in the `.gitlab-ci.yml` file.
For more information, see [custom environment variables](../variables/README.md#gitlab-ciyml-defined-variables)

```yaml
# The following variables will automatically be passed down to the Postgres container
# as well as the Ruby container and available within each.
variables:
  HTTPS_PROXY: "https://10.1.1.1:8090"
  HTTP_PROXY: "https://10.1.1.1:8090"
  POSTGRES_DB: "my_custom_db"
  POSTGRES_USER: "postgres"
  POSTGRES_PASSWORD: "example"
  PGDATA: "/var/lib/postgresql/data"
  POSTGRES_INITDB_ARGS: "--encoding=UTF8 --data-checksums"

services:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
295
- name: postgres:11.7
Thad Guidry's avatar
Thad Guidry включено в состав коммита
296
297
298
299
300
  alias: db
  entrypoint: ["docker-entrypoint.sh"]
  command: ["postgres"]

image:
GitLab Bot's avatar
GitLab Bot включено в состав коммита
301
  name: ruby:2.6
Thad Guidry's avatar
Thad Guidry включено в состав коммита
302
303
304
305
306
307
308
309
310
311
  entrypoint: ["/bin/bash"]

before_script:
- bundle install

test:
  script:
  - bundle exec rake spec
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
312
## Extended Docker configuration options
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
313

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
314
> Introduced in GitLab and GitLab Runner 9.4.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
315

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
316
317
When configuring the `image` or `services` entries, you can use a string or a map as
options:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
318

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
319
320
321
322
323
- when using a string as an option, it must be the full name of the image to use
  (including the Registry part if you want to download the image from a Registry
  other than Docker Hub)
- when using a map as an option, then it must contain at least the `name`
  option, which is the same name of the image as used for the string setting
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
324

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
325
For example, the following two definitions are equal:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
326

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
327
1. Using a string as an option to `image` and `services`:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
328

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
329
330
   ```yaml
   image: "registry.example.com/my/image:latest"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
331

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
332
333
334
335
   services:
   - postgresql:9.4
   - redis:latest
   ```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
336
337
338
339

1. Using a map as an option to `image` and `services`. The use of `image:name` is
   required:

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
340
341
342
   ```yaml
   image:
     name: "registry.example.com/my/image:latest"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
343

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
344
345
346
347
   services:
   - name: postgresql:9.4
   - name: redis:latest
   ```
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
348
349
350

### Available settings for `image`

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
351
> Introduced in GitLab and GitLab Runner 9.4.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
352

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
353
354
355
| Setting    | Required | GitLab version | Description |
|------------|----------|----------------| ----------- |
| `name`     | yes, when used with any other option      | 9.4 |Full name of the image that should be used. It should contain the Registry part if needed. |
GitLab Bot's avatar
GitLab Bot включено в состав коммита
356
| `entrypoint` | no     | 9.4 |Command or script that should be executed as the container's entrypoint. It will be translated to Docker's `--entrypoint` option while creating the container. The syntax is similar to [`Dockerfile`'s `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. |
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
357
358

### Available settings for `services`
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
359

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
360
> Introduced in GitLab and GitLab Runner 9.4.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
361

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
362
363
364
| Setting    | Required | GitLab version | Description |
|------------|----------|----------------| ----------- |
| `name`       | yes, when used with any other option  | 9.4 | Full name of the image that should be used. It should contain the Registry part if needed. |
GitLab Bot's avatar
GitLab Bot включено в состав коммита
365
366
| `entrypoint` | no     | 9.4 |Command or script that should be executed as the container's entrypoint. It will be translated to Docker's `--entrypoint` option while creating the container. The syntax is similar to [`Dockerfile`'s `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. |
| `command`    | no       | 9.4 |Command or script that should be used as the container's command. It will be translated to arguments passed to Docker after the image's name. The syntax is similar to [`Dockerfile`'s `CMD`](https://docs.docker.com/engine/reference/builder/#cmd) directive, where each shell token is a separate string in the array. |
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
367
| `alias`      | no       | 9.4 |Additional alias that can be used to access the service from the job's container. Read [Accessing the services](#accessing-the-services) for more information. |
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
368

GitLab Bot's avatar
GitLab Bot включено в состав коммита
369
NOTE: **Note:**
GitLab Bot's avatar
GitLab Bot включено в состав коммита
370
Alias support for the Kubernetes executor was [introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2229) in GitLab Runner 12.8, and is only available for Kubernetes version 1.7 or later.
GitLab Bot's avatar
GitLab Bot включено в состав коммита
371

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
372
### Starting multiple services from the same image
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
373

GitLab Bot's avatar
GitLab Bot включено в состав коммита
374
> Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](#extended-docker-configuration-options).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
375

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
376
377
Before the new extended Docker configuration options, the following configuration
would not work properly:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
378
379
380
381
382
383
384

```yaml
services:
- mysql:latest
- mysql:latest
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
385
386
387
388
The Runner would start two containers using the `mysql:latest` image, but both
of them would be added to the job's container with the `mysql` alias based on
the [default hostname naming](#accessing-the-services). This would end with one
of the services not being accessible.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
389

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
390
391
After the new extended Docker configuration options, the above example would
look like:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
392
393
394
395
396
397

```yaml
services:
- name: mysql:latest
  alias: mysql-1
- name: mysql:latest
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
398
  alias: mysql-2
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
399
400
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
401
The Runner will still start two containers using the `mysql:latest` image,
Evan Read's avatar
Evan Read включено в состав коммита
402
however now each of them will also be accessible with the alias configured
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
403
404
in `.gitlab-ci.yml` file.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
405
### Setting a command for the service
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
406

GitLab Bot's avatar
GitLab Bot включено в состав коммита
407
> Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](#extended-docker-configuration-options).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
408

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
409
410
411
412
413
Let's assume you have a `super/sql:latest` image with some SQL database
inside it and you would like to use it as a service for your job. Let's also
assume that this image doesn't start the database process while starting
the container and the user needs to manually use `/usr/bin/super-sql run` as
a command to start the database.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
414

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
415
416
417
Before the new extended Docker configuration options, you would need to create
your own image based on the `super/sql:latest` image, add the default command,
and then use it in job's configuration, like:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
418

GitLab Bot's avatar
GitLab Bot включено в состав коммита
419
```dockerfile
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
420
# my-super-sql:latest image's Dockerfile
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
421

Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
422
423
424
425
426
427
428
429
430
431
432
FROM super/sql:latest
CMD ["/usr/bin/super-sql", "run"]
```

```yaml
# .gitlab-ci.yml

services:
- my-super-sql:latest
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
433
434
After the new extended Docker configuration options, you can now simply
set a `command` in `.gitlab-ci.yml`, like:
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
435
436
437
438
439
440

```yaml
# .gitlab-ci.yml

services:
- name: super/sql:latest
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
441
  command: ["/usr/bin/super-sql", "run"]
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
442
443
```

GitLab Bot's avatar
GitLab Bot включено в состав коммита
444
As you can see, the syntax of `command` is similar to [Dockerfile's `CMD`](https://docs.docker.com/engine/reference/builder/#cmd).
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
445

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
446
### Overriding the entrypoint of an image
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
447

GitLab Bot's avatar
GitLab Bot включено в состав коммита
448
> Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](#extended-docker-configuration-options).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
449

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
450
451
452
453
454
455
456
457
Before showing the available entrypoint override methods, let's describe shortly
how the Runner starts and uses a Docker image for the containers used in the
CI jobs:

1. The Runner starts a Docker container using the defined entrypoint (default
   from `Dockerfile` that may be overridden in `.gitlab-ci.yml`)
1. The Runner attaches itself to a running container.
1. The Runner prepares a script (the combination of
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
458
   [`before_script`](../yaml/README.md#before_script-and-after_script),
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
459
   [`script`](../yaml/README.md#script),
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
460
   and [`after_script`](../yaml/README.md#before_script-and-after_script)).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
461
462
463
464
465
466
467
468
469
470
471
472
1. The Runner sends the script to the container's shell STDIN and receives the
   output.

To override the entrypoint of a Docker image, the recommended solution is to
define an empty `entrypoint` in `.gitlab-ci.yml`, so the Runner doesn't start
a useless shell layer. However, that will not work for all Docker versions, and
you should check which one your Runner is using. Specifically:

- If Docker 17.06 or later is used, the `entrypoint` can be set to an empty value.
- If Docker 17.03 or previous versions are used, the `entrypoint` can be set to
  `/bin/sh -c`, `/bin/bash -c` or an equivalent shell available in the image.

GitLab Bot's avatar
GitLab Bot включено в состав коммита
473
The syntax of `image:entrypoint` is similar to [Dockerfile's `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
474

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
475
476
477
478
Let's assume you have a `super/sql:experimental` image with some SQL database
inside it and you would like to use it as a base image for your job because you
want to execute some tests with this database binary. Let's also assume that
this image is configured with `/usr/bin/super-sql run` as an entrypoint. That
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
479
means that when starting the container without additional options, it will run
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
480
the database's process, while Runner expects that the image will have no
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
481
482
entrypoint or that the entrypoint is prepared to start a shell command.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
483
484
485
486
With the extended Docker configuration options, instead of creating your
own image based on `super/sql:experimental`, setting the `ENTRYPOINT`
to a shell, and then using the new image in your CI job, you can now simply
define an `entrypoint` in `.gitlab-ci.yml`.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
487

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
488
**For Docker 17.06+:**
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
489
490
491
492

```yaml
image:
  name: super/sql:experimental
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
493
494
495
  entrypoint: [""]
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
496
497
498
**For Docker =< 17.03:**

```yaml
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
499
500
501
image:
  name: super/sql:experimental
  entrypoint: ["/bin/sh", "-c"]
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
502
503
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
504
## Define image and services in `config.toml`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
505
506
507

Look for the `[runners.docker]` section:

Evan Read's avatar
Evan Read включено в состав коммита
508
```toml
Douwe Maan's avatar
Douwe Maan включено в состав коммита
509
[runners.docker]
GitLab Bot's avatar
GitLab Bot включено в состав коммита
510
  image = "ruby:latest"
Douwe Maan's avatar
Douwe Maan включено в состав коммита
511
512
513
  services = ["mysql:latest", "postgres:latest"]
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
514
The image and services defined this way will be added to all job run by
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
515
that runner.
Kamil Trzcinski's avatar
Kamil Trzcinski включено в состав коммита
516

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
517
## Define an image from a private Container Registry
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
518

Andrei Burd's avatar
Andrei Burd включено в состав коммита
519
520
521
522
523
524
525
526
527
528
529
530
To access private container registries, the GitLab Runner process can use:

- [Statically defined credentials](#using-statically-defined-credentials). That is, a username and password for a specific registry.
- [Credentials Store](#using-credentials-store). For more information, see [the relevant Docker documentation](https://docs.docker.com/engine/reference/commandline/login/#credentials-store).
- [Credential Helpers](#using-credential-helpers). For more information, see [the relevant Docker documentation](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers).

To define which should be used, the GitLab Runner process reads the configuration in the following order:

- `DOCKER_AUTH_CONFIG` variable provided as either:
  - A [variable](../variables/README.md#gitlab-cicd-environment-variables) in `.gitlab-ci.yml`.
  - A project's variables stored on the projects **Settings > CI/CD** page.
- `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the Runner.
Per Lundberg's avatar
Per Lundberg включено в состав коммита
531
- `config.json` file placed in `$HOME/.docker` directory of the user running GitLab Runner process.
Andrei Burd's avatar
Andrei Burd включено в состав коммита
532
533
534
  If the `--user` flag is provided to run the GitLab Runner child processes as unprivileged user,
  the home directory of the main GitLab Runner process user will be used.

Evan Read's avatar
Evan Read включено в состав коммита
535
536
NOTE: **Note:**
GitLab Runner reads this configuration **only** from `config.toml` and ignores it if
GitLab Bot's avatar
GitLab Bot включено в состав коммита
537
it's provided as an environment variable. This is because GitLab Runner uses **only**
Andrei Burd's avatar
Andrei Burd включено в состав коммита
538
539
540
`config.toml` configuration and doesn't interpolate **ANY** environment variables at
runtime.

Steve Azzopardi's avatar
Steve Azzopardi включено в состав коммита
541
542
543
544
545
546
547
548
### Requirements and limitations

- This feature requires GitLab Runner **1.8** or higher.
- For GitLab Runner versions **>= 0.6, <1.8** there was a partial
  support for using private registries, which required manual configuration
  of credentials on runner's host. We recommend to upgrade your Runner to
  at least version **1.8** if you want to use private registries.
- Not available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html),
GitLab Bot's avatar
GitLab Bot включено в состав коммита
549
  follow <https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2673> for
Steve Azzopardi's avatar
Steve Azzopardi включено в состав коммита
550
551
  details.

Andrei Burd's avatar
Andrei Burd включено в состав коммита
552
### Using statically-defined credentials
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
553

Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
554
555
There are two approaches that you can take in order to access a
private registry. Both require setting the environment variable
GitLab Bot's avatar
GitLab Bot включено в состав коммита
556
`DOCKER_AUTH_CONFIG` with appropriate authentication information.
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
557
558

1. Per-job: To configure one job to access a private registry, add
Alexander Tanayno's avatar
Alexander Tanayno включено в состав коммита
559
   `DOCKER_AUTH_CONFIG` as a job variable.
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
560
1. Per-runner: To configure a Runner so all its jobs can access a
Alexander Tanayno's avatar
Alexander Tanayno включено в состав коммита
561
   private registry, add `DOCKER_AUTH_CONFIG` to the environment in the
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
562
563
564
565
   Runner's configuration.

See below for examples of each.

Alexander Tanayno's avatar
Alexander Tanayno включено в состав коммита
566
#### Determining your `DOCKER_AUTH_CONFIG` data
Evan Read's avatar
Evan Read включено в состав коммита
567

Drew Blessing's avatar
Drew Blessing включено в состав коммита
568
As an example, let's assume that you want to use the `registry.example.com:5000/private/image:latest`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
569
image which is private and requires you to login into a private container registry.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
570
571
572

Let's also assume that these are the login credentials:

Evan Read's avatar
Evan Read включено в состав коммита
573
574
575
576
577
| Key      | Value                       |
|:---------|:----------------------------|
| registry | `registry.example.com:5000` |
| username | `my_username`               |
| password | `my_password`               |
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
578

Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
579
580
581
There are two ways to determine the value of `DOCKER_AUTH_CONFIG`:

- **First way -** Do a `docker login` on your local machine:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
582

GitLab Bot's avatar
GitLab Bot включено в состав коммита
583
  ```shell
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
584
585
  docker login registry.example.com:5000 --username my_username --password my_password
  ```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
586

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
587
  Then copy the content of `~/.docker/config.json`.
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
588

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
589
590
  If you don't need access to the registry from your computer, you
  can do a `docker logout`:
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
591

GitLab Bot's avatar
GitLab Bot включено в состав коммита
592
  ```shell
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
593
594
  docker logout registry.example.com:5000
  ```
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
595
596

- **Second way -** In some setups, it's possible that Docker client
GitLab Bot's avatar
GitLab Bot включено в состав коммита
597
  will use the available system key store to store the result of `docker
Markus Koller's avatar
Markus Koller включено в состав коммита
598
599
  login`. In that case, it's impossible to read `~/.docker/config.json`,
  so you will need to prepare the required base64-encoded version of
GitLab Bot's avatar
GitLab Bot включено в состав коммита
600
601
  `${username}:${password}` and create the Docker configuration JSON manually.
  Open a terminal and execute the following command:
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
602

GitLab Bot's avatar
GitLab Bot включено в состав коммита
603
  ```shell
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
604
  echo -n "my_username:my_password" | base64
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
605

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
606
607
608
  # Example output to copy
  bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
  ```
GitLab Bot's avatar
GitLab Bot включено в состав коммита
609

GitLab Bot's avatar
GitLab Bot включено в состав коммита
610
611
612
613
614
615
616
617
618
619
620
  Create the Docker JSON configuration content as follows:

  ```json
  {
      "auths": {
          "registry.example.com:5000": {
              "auth": "(Base64 content from above)"
          }
      }
  }
  ```
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
621

Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
622
#### Configuring a job
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
623

Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
624
625
To configure a single job with access for `registry.example.com:5000`,
follow these steps:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
626

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
627
1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
628
629
   Docker configuration file as the value:

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
630
631
632
633
634
635
636
637
638
   ```json
   {
       "auths": {
           "registry.example.com:5000": {
               "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
           }
       }
   }
   ```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
639

Drew Blessing's avatar
Drew Blessing включено в состав коммита
640
1. You can now use any private image from `registry.example.com:5000` defined in
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
641
   `image` and/or `services` in your `.gitlab-ci.yml` file:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
642

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
643
644
645
   ```yaml
   image: registry.example.com:5000/namespace/image:tag
   ```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
646

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
647
648
   In the example above, GitLab Runner will look at `registry.example.com:5000` for the
   image `namespace/image:tag`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
649
650
651

You can add configuration for as many registries as you want, adding more
registries to the `"auths"` hash as described above.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
652

Evan Read's avatar
Evan Read включено в состав коммита
653
654
NOTE: **Note:**
The full `hostname:port` combination is required everywhere
Drew Blessing's avatar
Drew Blessing включено в состав коммита
655
656
657
658
659
for the Runner to match the `DOCKER_AUTH_CONFIG`. For example, if
`registry.example.com:5000/namespace/image:tag` is specified in `.gitlab-ci.yml`,
then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`.
Specifying only `registry.example.com` will not work.

Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
660
661
662
### Configuring a Runner

If you have many pipelines that access the same registry, it'll
GitLab Bot's avatar
GitLab Bot включено в состав коммита
663
probably be better to setup registry access at the runner level. This
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
664
665
666
667
668
669
670
671
672
673
674
675
676
allows pipeline authors to have access to a private registry just by
running a job on the appropriate runner. It also makes registry
changes and credential rotations much simpler.

Of course this means that any job on that runner can access the
registry with the same privilege, even across projects. If you need to
control access to the registry, you'll need to be sure to control
access to the runner.

To add `DOCKER_AUTH_CONFIG` to a Runner:

1. Modify the Runner's `config.toml` file as follows:

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
677
678
679
680
   ```toml
   [[runners]]
     environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"]
   ```
Ross Vandegrift's avatar
Ross Vandegrift включено в состав коммита
681
682
683
684
685
686
687
688
689
690
691

1. Restart the Runner service.

NOTE: **Note:** The double quotes included in the `DOCKER_AUTH_CONFIG`
data must be escaped with backslashes. This prevents them from being
interpreted as TOML.

NOTE: **Note:** The `environment` option is a list. So your Runner may
have existing entries and you should add this to the list, not replace
it.

Andrei Burd's avatar
Andrei Burd включено в состав коммита
692
693
694
695
696
697
698
### Using Credentials Store

> Support for using Credentials Store was added in GitLab Runner 9.5.

To configure credentials store, follow these steps:

1. To use a credentials store, you need an external helper program to interact with a specific keychain or external store.
Evan Read's avatar
Evan Read включено в состав коммита
699
   Make sure helper program is available in GitLab Runner `$PATH`.
Andrei Burd's avatar
Andrei Burd включено в состав коммита
700
701

1. Make GitLab Runner use it. There are two ways to accomplish this. Either:
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
702

Evan Read's avatar
Evan Read включено в состав коммита
703
   - Create a
Andrei Burd's avatar
Andrei Burd включено в состав коммита
704
705
     [variable](../variables/README.md#gitlab-cicd-environment-variables)
     `DOCKER_AUTH_CONFIG` with the content of the
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
706
     Docker configuration file as the value:
Andrei Burd's avatar
Andrei Burd включено в состав коммита
707

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
708
709
710
711
712
     ```json
       {
         "credsStore": "osxkeychain"
       }
     ```
Andrei Burd's avatar
Andrei Burd включено в состав коммита
713

GitLab Bot's avatar
GitLab Bot включено в состав коммита
714
   - Or, if you are running self-managed Runners, add the above JSON to
GitLab Bot's avatar
GitLab Bot включено в состав коммита
715
     `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner will read this configuration file
Andrei Burd's avatar
Andrei Burd включено в состав коммита
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
     and will use the needed helper for this specific repository.

NOTE: **Note:** `credsStore` is used to access ALL the registries.
If you will want to use both images from private registry and public images from DockerHub,
pulling from DockerHub will fail, because Docker daemon will try to use the same credentials for **ALL** the registries.

### Using Credential Helpers

> Support for using Credential Helpers was added in GitLab Runner 12.0

As an example, let's assume that you want to use the `aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest`
image which is private and requires you to log in into a private container registry.

To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow these steps:

1. Make sure `docker-credential-ecr-login` is available in GitLab Runner's `$PATH`.

GitLab Bot's avatar
GitLab Bot включено в состав коммита
733
734
735
1. Have any of the following [AWS credentials setup](https://github.com/awslabs/amazon-ecr-credential-helper#aws-credentials).
   Make sure that GitLab Runner can access the credentials.

Andrei Burd's avatar
Andrei Burd включено в состав коммита
736
1. Make GitLab Runner use it. There are two ways to accomplish this. Either:
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
737

Andrei Burd's avatar
Andrei Burd включено в состав коммита
738
739
   - Create a [variable](../variables/README.md#gitlab-cicd-environment-variables)
     `DOCKER_AUTH_CONFIG` with the content of the
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
740
     Docker configuration file as the value:
Andrei Burd's avatar
Andrei Burd включено в состав коммита
741

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
742
743
744
745
746
747
748
     ```json
     {
       "credHelpers": {
         "aws_account_id.dkr.ecr.region.amazonaws.com": "ecr-login"
       }
     }
     ```
Andrei Burd's avatar
Andrei Burd включено в состав коммита
749

GitLab Bot's avatar
GitLab Bot включено в состав коммита
750
     This configures Docker to use the credential helper for a specific registry.
GitLab Bot's avatar
GitLab Bot включено в состав коммита
751
752
753
754
755
756
757
758
759

     or

     ```json
     {
       "credsStore": "ecr-login"
     }
     ```

GitLab Bot's avatar
GitLab Bot включено в состав коммита
760
     This configures Docker to use the credential helper for all Amazon ECR registries.
GitLab Bot's avatar
GitLab Bot включено в состав коммита
761

GitLab Bot's avatar
GitLab Bot включено в состав коммита
762
   - Or, if you are running self-managed Runners,
Andrei Burd's avatar
Andrei Burd включено в состав коммита
763
     add the above JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`.
GitLab Bot's avatar
GitLab Bot включено в состав коммита
764
     GitLab Runner will read this configuration file and will use the needed helper for this
Andrei Burd's avatar
Andrei Burd включено в состав коммита
765
766
767
768
769
     specific repository.

1. You can now use any private image from `aws_account_id.dkr.ecr.region.amazonaws.com` defined in
   `image` and/or `services` in your `.gitlab-ci.yml` file:

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
770
771
772
   ```yaml
   image: aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest
   ```
Andrei Burd's avatar
Andrei Burd включено в состав коммита
773

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
774
775
   In the example above, GitLab Runner will look at `aws_account_id.dkr.ecr.region.amazonaws.com` for the
   image `private/image:latest`.
Andrei Burd's avatar
Andrei Burd включено в состав коммита
776
777
778
779

You can add configuration for as many registries as you want, adding more
registries to the `"credHelpers"` hash as described above.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
780
## Configuring services
Douwe Maan's avatar
Douwe Maan включено в состав коммита
781

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
782
783
Many services accept environment variables which allow you to easily change
database names or set account names depending on the environment.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
784

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
785
786
GitLab Runner 0.5.0 and up passes all YAML-defined variables to the created
service containers.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
787

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
788
789
For all possible configuration variables check the documentation of each image
provided in their corresponding Docker hub page.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
790

Evan Read's avatar
Evan Read включено в состав коммита
791
792
793
NOTE: **Note:**
All variables will be passed to all services containers. It's not
designed to distinguish which variable should go where.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
794

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
795
### PostgreSQL service example
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
796

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
797
798
See the specific documentation for
[using PostgreSQL as a service](../services/postgres.md).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
799

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
800
### MySQL service example
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
801

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
802
803
See the specific documentation for
[using MySQL as a service](../services/mysql.md).
Douwe Maan's avatar
Douwe Maan включено в состав коммита
804

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
805
## How Docker integration works
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
806

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
807
Below is a high level overview of the steps performed by Docker during job
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
808
809
time.

Douwe Maan's avatar
Douwe Maan включено в состав коммита
810
1. Create any service container: `mysql`, `postgresql`, `mongodb`, `redis`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
811
1. Create cache container to store all volumes as defined in `config.toml` and
GitLab Bot's avatar
GitLab Bot включено в состав коммита
812
   `Dockerfile` of build image (`ruby:2.6` as in above example).
Douwe Maan's avatar
Douwe Maan включено в состав коммита
813
1. Create build container and link any service container to build container.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
814
815
1. Start build container and send job script to the container.
1. Run job script.
Douwe Maan's avatar
Douwe Maan включено в состав коммита
816
817
818
819
820
1. Checkout code in: `/builds/group-name/project-name/`.
1. Run any step defined in `.gitlab-ci.yml`.
1. Check exit status of build script.
1. Remove build container and all created service containers.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
821
## How to debug a job locally
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
822

Evan Read's avatar
Evan Read включено в состав коммита
823
824
825
NOTE: **Note:**
The following commands are run without root privileges. You should be
able to run Docker with your regular user account.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
826

827
First start with creating a file named `build_script`:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
828

GitLab Bot's avatar
GitLab Bot включено в состав коммита
829
```shell
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
830
cat <<EOF > build_script
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
831
832
git clone https://gitlab.com/gitlab-org/gitlab-runner.git /builds/gitlab-org/gitlab-runner
cd /builds/gitlab-org/gitlab-runner
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
833
make
Douwe Maan's avatar
Douwe Maan включено в состав коммита
834
835
836
EOF
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
837
838
839
840
841
842
843
Here we use as an example the GitLab Runner repository which contains a
Makefile, so running `make` will execute the commands defined in the Makefile.
Your mileage may vary, so instead of `make` you could run the command which
is specific to your project.

Then create some service containers:

GitLab Bot's avatar
GitLab Bot включено в состав коммита
844
```shell
Tomasz Maczukin's avatar
Tomasz Maczukin включено в состав коммита
845
846
docker run -d --name service-mysql mysql:latest
docker run -d --name service-postgres postgres:latest
Douwe Maan's avatar
Douwe Maan включено в состав коммита
847
848
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
849
850
851
852
853
854
855
This will create two service containers, named `service-mysql` and
`service-postgres` which use the latest MySQL and PostgreSQL images
respectively. They will both run in the background (`-d`).

Finally, create a build container by executing the `build_script` file we
created earlier:

GitLab Bot's avatar
GitLab Bot включено в состав коммита
856
```shell
GitLab Bot's avatar
GitLab Bot включено в состав коммита
857
docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.6 /bin/bash < build_script
Douwe Maan's avatar
Douwe Maan включено в состав коммита
858
859
```

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
860
The above command will create a container named `build` that is spawned from
GitLab Bot's avatar
GitLab Bot включено в состав коммита
861
the `ruby:2.6` image and has two services linked to it. The `build_script` is
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
862
863
864
865
866
867
piped using STDIN to the bash interpreter which in turn executes the
`build_script` in the `build` container.

When you finish testing and no longer need the containers, you can remove them
with:

GitLab Bot's avatar
GitLab Bot включено в состав коммита
868
```shell
Douwe Maan's avatar
Douwe Maan включено в состав коммита
869
870
docker rm -f -v build service-mysql service-postgres
```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
871
872
873
874

This will forcefully (`-f`) remove the `build` container, the two service
containers as well as all volumes (`-v`) that were created with the container
creation.