Add runners.cache section

doc/articles/runner_autoscale_aws/index.md

@@ -111,37 +111,45 @@ check_interval = 0
 
 Let's break it down to pieces.
 
-- Global section
+### Global section
 
-    ```toml
-    concurrent = 3
-    check_interval = 0
-    ```
+```toml
+concurrent = 3
+check_interval = 0
+```
 
-- `[[runners]]`
+### `[[runners]]`
 
-    ```toml
-    [[runners]]
+```toml
+[[runners]]
   name = "gitlab-aws-autoscaler"
   url = "<url to your GitLab CI host>"
   token = "<registration token>"
   executor = "docker+machine"
   limit = 4
-    ```
+```
 
-- `[runners.docker]`
+### `[runners.docker]`
 
-    ```toml
+```toml
   [runners.docker]
     image = "alpine"
     privileged = true
     disable_cache = false
     volumes = ["/cache"]
-    ```
+```
+
+### `[runners.cache]`
 
-- `[runners.cache]`
+To speed up your jobs, GitLab Runner provides a cache mechanism where selected
+directories and/or files are saved and shared between subsequent jobs.
+While not required for this setup, it is recommended to use the shared cache
+mechanism that GitLab Runner provides. Since new instances will be created on
+demand, it is essential to have a common place where cache is stored.
 
-    ```toml
+In the following example, we use Amazon S3:
+
+```toml
   [runners.cache]
     Type = "s3"
     ServerAddress = "s3.amazonaws.com"
@@ -150,11 +158,20 @@ Let's break it down to pieces.
     BucketName = "<the bucket where your cache should be kept>"
     BucketLocation = "us-east-1"
     Shared = true
-    ```
+```
+
+Here's some more info to get you started:
+
+- [The `[runners.cache]` section](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-cache-section)
+- [Deploying and using a cache server for GitLab Runner](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching)
+- [How cache works](../../ci/yaml/README.md#cache)
 
-- `[runners.machine]`
+### `[runners.machine]`
 
-    ```toml
+This is the most important part of the configuration and it's the one that
+tells GitLab Runner how and when to spawn new Docker Machine instances.
+
+```toml
   [runners.machine]
     IdleCount = 1
     IdleTime = 1800
@@ -179,10 +196,11 @@ Let's break it down to pieces.
       "amazonec2-zone=a",
       "amazonec2-root-size=32",
     ]
-    ```
+```
 
-    Under `MachineOptions` you can add anything that the [AWS Docker Machine driver
-    supports](https://docs.docker.com/machine/drivers/aws/#options).
+TIP: **Tip:**
+Under `MachineOptions` you can add anything that the [AWS Docker Machine driver
+supports](https://docs.docker.com/machine/drivers/aws/#options).
 
 ## Cutting down costs with Amazon EC2 Spot instances