Merge branch 'docs-hchouraria-docker-services-registry-portion-in-image-name' into 'master'

Docs: Troubleshooting "lookup docker: no such host" errors

See merge request gitlab-org/gitlab!63364

doc/ci/docker/using_docker_build.md

@@ -840,3 +840,30 @@ This issue occurs because Docker starts on TLS automatically.
   [use the Docker executor with the Docker image](#use-the-docker-executor-with-the-docker-image-docker-in-docker).
 - If you are upgrading from v18.09 or earlier, read our
   [upgrade guide](https://about.gitlab.com/blog/2019/07/31/docker-in-docker-with-docker-19-dot-03/).
+
+### Docker `no such host` error
+
+You may get an error that says
+`docker: error during connect: Post https://docker:2376/v1.40/containers/create: dial tcp: lookup docker on x.x.x.x:53: no such host`.
+
+This issue can occur when the service's image name
+[includes a registry hostname](../../ci/services/index.md#available-settings-for-services). For example:
+
+```yaml
+image: docker:19.03.12
+
+services:
+  - registry.hub.docker.com/library/docker:19.03.12-dind
+```
+
+A service's hostname is [derived from the full image name](../../ci/services/index.md#accessing-the-services).
+However, the shorter service hostname `docker` is expected.
+To allow service resolution and access, add an explicit alias for the service name `docker`:
+
+```yaml
+image: docker:19.03.12
+
+services:
+  - name: registry.hub.docker.com/library/docker:19.03.12-dind
+    alias: docker
+```

doc/ci/services/index.md

@@ -228,7 +228,7 @@ test:
 
 | Setting    | Required | GitLab version | Description |
 |------------|----------|----------------| ----------- |
-| `name`       | yes, when used with any other option  | 9.4 | Full name of the image to use. It should contain the Registry part if needed. |
+| `name`       | yes, when used with any other option  | 9.4 | Full name of the image to use. If the full image name includes a registry hostname, use the `alias` option to define a shorter service access name. For more information, see [Accessing the services](#accessing-the-services). |
 | `entrypoint` | no     | 9.4 |Command or script to execute as the container's entrypoint. It's 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's 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. |
 | `alias` (1)     | 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. |