5 files changed, 79 insertions, 28 deletions
diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md
index 558f53a9535..5ac66846ab7 100644
--- a/doc/ci/services/gitlab.md
+++ b/doc/ci/services/gitlab.md
@@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference
 ---
 
-# Use GitLab as a microservice
+# Use GitLab as a microservice **(FREE)**
 
 Many applications need to access JSON APIs, so application tests might need access
 to APIs too. The following example shows how to use GitLab as a microservice to give
@@ -24,10 +24,9 @@ tests access to the GitLab API.
      GITLAB_ROOT_PASSWORD: "password"  # to access the api with user root:password
    ```
 
-1. To set values for the `GITLAB_HTTPS` and `GITLAB_ROOT_PASSWORD`,
-   [assign them to a variable in the user interface](../variables/index.md#add-a-cicd-variable-to-a-project).
-   Then assign that variable to the corresponding variable in your
-   `.gitlab-ci.yml` file.
+NOTE:
+Variables set in the GitLab UI are not passed down to the service containers.
+[Learn more](../variables/index.md#).
 
 Then, commands in `script:` sections in your `.gitlab-ci.yml` file can access the API at `http://gitlab/api/v4`.
 
diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md
index c7891998a37..4114833d1c8 100644
--- a/doc/ci/services/index.md
+++ b/doc/ci/services/index.md
@@ -6,7 +6,7 @@ comments: false
 type: index
 ---
 
-# Services
+# Services **(FREE)**
 
 The `services` keyword defines a Docker image that runs during a `job`
 linked to the Docker image that the image keyword defines. This allows
@@ -186,6 +186,34 @@ following these rules:
 To override the default behavior, you can
 [specify a service alias](#available-settings-for-services).
 
+### Connecting services
+
+You can use inter-dependent services with complex jobs, like end-to-end tests where an
+external API needs to communicate with its own database.
+
+For example, for an end-to-end test for a front-end application that uses an API, and where the API needs a database:
+
+```yaml
+end-to-end-tests:
+  image: node:latest
+  services:
+    - name: selenium/standalone-firefox:${FIREFOX_VERSION}
+      alias: firefox
+    - name: registry.gitlab.com/organization/private-api:latest
+      alias: backend-api
+    - postgres:9.6.19
+  variables:
+    FF_NETWORK_PER_BUILD: 1
+    POSTGRES_PASSWORD: supersecretpassword
+    BACKEND_POSTGRES_HOST: postgres
+  script:
+    - npm install
+    - npm test
+```
+
+For this solution to work, you must use
+[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job).
+
 ## Passing CI/CD variables to services
 
 You can also pass custom CI/CD [variables](../variables/index.md)
@@ -311,6 +339,34 @@ services:
 
 The syntax of `command` is similar to [Dockerfile's `CMD`](https://docs.docker.com/engine/reference/builder/#cmd).
 
+## Using `services` with `docker run` (Docker-in-Docker) side-by-side
+
+Containers started with `docker run` can also connect to services provided by GitLab.
+
+When booting the service is expensive or time consuming, you can use
+this technique to run tests from different client environments,
+while only booting up the tested service once.
+
+```yaml
+access-service:
+  stage: build
+  image: docker:19.03.1
+  services:
+    - docker:dind                    # necessary for docker run
+    - tutum/wordpress:latest
+  variables:
+    FF_NETWORK_PER_BUILD: "true"     # activate container-to-container networking
+  script: |
+    docker run --rm --name curl \
+      --volume  "$(pwd)":"$(pwd)"    \
+      --workdir "$(pwd)"             \
+      --network=host                 \
+      curlimages/curl:7.74.0 curl "http://tutum-wordpress"
+```
+
+For this solution to work, you must use
+[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job).
+
 ## How Docker integration works
 
 Below is a high level overview of the steps performed by Docker during job
diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md
index c691a6ef33d..d0ac123ba62 100644
--- a/doc/ci/services/mysql.md
+++ b/doc/ci/services/mysql.md
@@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference
 ---
 
-# Using MySQL
+# Using MySQL **(FREE)**
 
 Many applications depend on MySQL as their database, and you may
 need it for your tests to run.
@@ -16,11 +16,9 @@ If you want to use a MySQL container, you can use [GitLab Runner](../runners/ind
 
 This example shows you how to set a username and password that GitLab uses to access the MySQL container. If you do not set a username and password, you must use `root`.
 
-1. [Create CI/CD variables](../variables/index.md#custom-cicd-variables) for your
-   MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**,
-   and clicking **Add Variable**.
-
-   This example uses `$MYSQL_DB` and `$MYSQL_PASS` as the keys.
+NOTE:
+Variables set in the GitLab UI are not passed down to the service containers.
+[Learn more](../variables/index.md).
 
 1. To specify a MySQL image, add the following to your `.gitlab-ci.yml` file:
 
@@ -39,8 +37,8 @@ This example shows you how to set a username and password that GitLab uses to ac
    ```yaml
    variables:
      # Configure mysql environment variables (https://hub.docker.com/_/mysql/)
-     MYSQL_DATABASE: $MYSQL_DB
-     MYSQL_ROOT_PASSWORD: $MYSQL_PASS
+     MYSQL_DATABASE: $MYSQL_DATABASE
+     MYSQL_ROOT_PASSWORD: $MYSQL_ROOT_PASSWORD
    ```
 
    The MySQL container uses `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` to connect to the database.
diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md
index 8d14e4795d2..62838e04969 100644
--- a/doc/ci/services/postgres.md
+++ b/doc/ci/services/postgres.md
@@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference
 ---
 
-# Using PostgreSQL
+# Using PostgreSQL **(FREE)**
 
 As many applications depend on PostgreSQL as their database, you
 eventually need it in order for your tests to run. Below you are guided how to
@@ -16,6 +16,10 @@ do this with the Docker and Shell executors of GitLab Runner.
 If you're using [GitLab Runner](../runners/index.md) with the Docker executor,
 you basically have everything set up already.
 
+NOTE:
+Variables set in the GitLab UI are not passed down to the service containers.
+[Learn more](../variables/index.md).
+
 First, in your `.gitlab-ci.yml` add:
 
 ```yaml
@@ -23,25 +27,19 @@ services:
   - postgres:12.2-alpine
 
 variables:
-  POSTGRES_DB: nice_marmot
-  POSTGRES_USER: runner
-  POSTGRES_PASSWORD: ""
+  POSTGRES_DB: $POSTGRES_DB
+  POSTGRES_USER: $POSTGRES_USER
+  POSTGRES_PASSWORD: $POSTGRES_PASSWORD
   POSTGRES_HOST_AUTH_METHOD: trust
 ```
 
-To set values for the `POSTGRES_DB`, `POSTGRES_USER`,
-`POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`,
-[assign them to a CI/CD variable in the user interface](../variables/index.md#custom-cicd-variables),
-then assign that variable to the corresponding variable in your
-`.gitlab-ci.yml` file.
-
 And then configure your application to use the database, for example:
 
 ```yaml
 Host: postgres
-User: runner
-Password: ''
-Database: nice_marmot
+User: $PG_USER
+Password: $PG_PASSWORD
+Database: $PG_DB
 ```
 
 If you're wondering why we used `postgres` for the `Host`, read more at
diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md
index d8c7b805864..a3446fc2677 100644
--- a/doc/ci/services/redis.md
+++ b/doc/ci/services/redis.md
@@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference
 ---
 
-# Using Redis
+# Using Redis **(FREE)**
 
 As many applications depend on Redis as their key-value store, you
 eventually need it in order for your tests to run. Below you are guided how to