Merge branch 'docs-ci-variable-types-usage-example' into 'master'

Docs: Update documentation with CI variable types usage example

See merge request gitlab-org/gitlab-ce!28515

(cherry picked from commit 0702d4b6899648ba12a747824f3db86c2f4aa42e)

706dfdb7 Add CI variable types usage example
7b9a52c0 Update screenshot to match latest CI variables UI
83cd1a76 Fix typo in CI variables docs
3e5b4ce8 Apply suggestion to doc/ci/variables/README.md
b7d820a4 Apply suggestion to doc/ci/variables/README.md
9d2bef55 Apply suggestion to doc/ci/variables/README.md
cb637cc9 Apply suggestion to doc/ci/variables/README.md
c13648a8 Apply suggestion to doc/ci/variables/README.md
121917cb Apply suggestion to doc/ci/variables/README.md
cf95e5ec Apply suggestion to doc/ci/variables/README.md
556d5ebf Apply suggestion to doc/ci/variables/README.md

3 files changed, 23 insertions, 2 deletions

diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index 1ba22070abe..67e1d316f02 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -58,8 +58,29 @@ the need to specify the value itself.
 
 There are two types of variables supported by GitLab:
 
-- `env_var`: the runner will create environment variable named same as the variable key and set its value to the variable value.
-- `file`: the runner will write the variable value to a temporary file and set the path to this file as the value of an environment variable named same as the variable key.
+- "Variable": the Runner will create an environment variable named same as the variable key and set its value to the variable value.
+- "File": the Runner will write the variable value to a temporary file and set the path to this file as the value of an environment variable named same as the variable key.
+
+Many tools (like [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) and [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable)) provide the ability to customise configuration using files by either providing the file path as a command line argument or an environment variable. Prior to the introduction of variable types, the common pattern was to use the value of a CI variable, save it in a file, and then use the newly created file in your script:
+
+```bash
+# Save the content of variable in a file
+echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem"
+ # Use the newly created file
+kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem"
+```
+
+This can be simplified by creating a variable of type "File" and using it directly. For example, let's say we have the following variables.
+
+![CI/CD settings - variable types usage example](img/variable_types_usage_example.png)
+
+We can then call them from `.gitlab-ci.yml` like this:
+
+```bash
+kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"
+```
+
+Variable types can be set via the [UI](#via-the-ui) or the [API](../../api/project_level_variables.md#create-variable), but not in `.gitlab-ci.yml`.
 
 #### Masked variables
 
diff --git a/doc/ci/variables/img/new_custom_variables_example.png b/doc/ci/variables/img/new_custom_variables_example.png
index 4b78e0ff587..efe104efe4c 100644
--- a/doc/ci/variables/img/new_custom_variables_example.png
+++ b/doc/ci/variables/img/new_custom_variables_example.png
diff --git a/doc/ci/variables/img/variable_types_usage_example.png b/doc/ci/variables/img/variable_types_usage_example.png
new file mode 100644
index 00000000000..0e8bde891fe
--- /dev/null
+++ b/doc/ci/variables/img/variable_types_usage_example.png