summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSteve Azzopardi <steveazz@outlook.com>2018-09-27 13:35:16 +0200
committerSteve Azzopardi <steveazz@outlook.com>2018-10-24 08:17:54 +0200
commit84fa85d5a8df90a7b74372f7778229dcbb02a69b (patch)
treef6eed90ee094e8e7d56242bb26584d9d06b16b15
parent22ab1a82ff9b6d0fda64df0d6b633fd588dd965e (diff)
downloadgitlab-ce-84fa85d5a8df90a7b74372f7778229dcbb02a69b.tar.gz
Add documentation for DOCKER_STRATEGYdocs/runner-3605-document-new-docker-strategy
-rw-r--r--doc/ci/interactive_web_terminal/index.md9
-rw-r--r--doc/ci/yaml/README.md39
2 files changed, 42 insertions, 6 deletions
diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md
index 1ddc1bf4d7e..341643e647f 100644
--- a/doc/ci/interactive_web_terminal/index.md
+++ b/doc/ci/interactive_web_terminal/index.md
@@ -25,11 +25,9 @@ Two things need to be configured for the interactive web terminal to work:
NOTE: **Note:** Not all executors are
[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
-NOTE: **Note:** The `docker` executor does not keep running
-after the build script is finished. At that point, the terminal will automatically
-disconnect and will not wait for the user to finish. Please follow [this
-issue](https://gitlab.com/gitlab-org/gitlab-runner/issues/3605) for updates on
-improving this behavior.
+NOTE: **Note:** For full support on `docker` executor please use the
+[DOCKER_STRATEGY: exec][docker-strategy] inside of `.gitlab-ci.yml` variables
+declaration.
Sometimes, when a job is running, things don't go as you would expect, and it
would be helpful if one can have a shell to aid debugging. When a job is
@@ -52,3 +50,4 @@ close the terminal window.
![finished job with terminal open](img/finished_job_with_terminal_open.png)
[session-server]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section
+[docker-strategy]: ../yaml/README.md#docker-strategy
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 4b2a6ccc7e4..d4740273784 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1836,6 +1836,42 @@ variables:
You can set it globally or per-job in the [`variables`](#variables) section.
+### Docker Strategy
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/issues/3605) in GitLab 11.4.
+
+You can set the `DOCKER_STRATEGY` either globally or per-job in
+[`variables`](#variables) section. If left unspecified, the default is
+`attach` which is the same behavior pre 11.4.
+
+`DOCKER_STRATEGY` defines the behavior of how the runner handle the build
+containers.
+
+`attach` is the default option, and follow the same behavior that the runner
+has been using. A container is started with the build script as the main
+process and exists as soon as the script is done.
+
+```yaml
+variables:
+ DOCKER_STRATEGY: attach
+```
+
+`exec` is the new workflow the runner follows to handle the build container,
+which tries to mimic the same way our [kubernetes
+executor](https://docs.gitlab.com/runner/executors/kubernetes.html) work.
+Meaning the build container is started in [detached
+mode](https://docs.docker.com/engine/reference/run/#detached--d) that invokes
+a shell. This allows the container to keep running until stopped/killed as
+the end of the stage. The build script is then executed using the `exec`
+functionality. Doing so will allow the runner to access the container even
+after the build script has started, such as [interactive web
+terminals][debugging-running-job].
+
+```yaml
+variables:
+ DOCKER_STRATEGY: exec
+```
+
## Special YAML features
It's possible to use special YAML features like anchors (`&`), aliases (`*`)
@@ -2032,4 +2068,5 @@ CI with various languages.
[schedules]: ../../user/project/pipelines/schedules.md
[variables-expressions]: ../variables/README.md#variables-expressions
[ee]: https://about.gitlab.com/gitlab-ee/
-[gitlab-versions]: https://about.gitlab.com/products/ \ No newline at end of file
+[gitlab-versions]: https://about.gitlab.com/products/
+[debugging-running-job]: ../interactive_web_terminal/index.md#debugging-a-running-job