Add runners.cache section

1 files changed, 90 insertions, 72 deletions

diff --git a/doc/articles/runner_autoscale_aws/index.md b/doc/articles/runner_autoscale_aws/index.md
index fe1b4b2c897..40622aaac15 100644
--- a/doc/articles/runner_autoscale_aws/index.md
+++ b/doc/articles/runner_autoscale_aws/index.md
@@ -111,78 +111,96 @@ check_interval = 0
 
 Let's break it down to pieces.
 
-- Global section
-
-    ```toml
-    concurrent = 3
-    check_interval = 0
-    ```
-
-- `[[runners]]`
-
-    ```toml
-    [[runners]]
-      name = "gitlab-aws-autoscaler"
-      url = "<url to your GitLab CI host>"
-      token = "<registration token>"
-      executor = "docker+machine"
-      limit = 4
-    ```
-
-- `[runners.docker]`
-
-    ```toml
-      [runners.docker]
-        image = "alpine"
-        privileged = true
-        disable_cache = false
-        volumes = ["/cache"]
-    ```
-
-- `[runners.cache]`
-
-    ```toml
-      [runners.cache]
-        Type = "s3"
-        ServerAddress = "s3.amazonaws.com"
-        AccessKey = "<your AWS Access Key ID>"
-        SecretKey = "<your AWS Secret Access Key>"
-        BucketName = "<the bucket where your cache should be kept>"
-        BucketLocation = "us-east-1"
-        Shared = true
-    ```
-
-- `[runners.machine]`
-
-    ```toml
-      [runners.machine]
-        IdleCount = 1
-        IdleTime = 1800
-        MaxBuilds = 100
-        MachineDriver = "amazonec2"
-        MachineName = "gitlab-docker-machine-%s"
-        OffPeakPeriods = ["* * 0-7,19-23 * * mon-fri *", "* * * * * sat,sun *"]
-        OffPeakIdleCount = 0
-        OffPeakIdleTime = 1200
-        MachineOptions = [
-          "amazonec2-access-key=XXXX",
-          "amazonec2-secret-key=XXXX",
-          "amazonec2-region=us-east-1",
-          "amazonec2-vpc-id=vpc-xxxxx",
-          "amazonec2-subnet-id=subnet-xxxxx",
-          "amazonec2-use-private-address=true",
-          "amazonec2-tags=Name,gitlab-runner-autoscale",
-          "amazonec2-security-group=docker-machine-scaler",
-          "amazonec2-instance-type=m4.2xlarge",
-          "amazonec2-ssh-user=ubuntu",
-          "amazonec2-ssh-keypath=/etc/gitlab-runner/certs/gitlab-aws-autoscaler",
-          "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).
+### Global section
+
+```toml
+concurrent = 3
+check_interval = 0
+```
+
+### `[[runners]]`
+
+```toml
+[[runners]]
+  name = "gitlab-aws-autoscaler"
+  url = "<url to your GitLab CI host>"
+  token = "<registration token>"
+  executor = "docker+machine"
+  limit = 4
+```
+
+### `[runners.docker]`
+
+```toml
+  [runners.docker]
+    image = "alpine"
+    privileged = true
+    disable_cache = false
+    volumes = ["/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.
+
+In the following example, we use Amazon S3:
+
+```toml
+  [runners.cache]
+    Type = "s3"
+    ServerAddress = "s3.amazonaws.com"
+    AccessKey = "<your AWS Access Key ID>"
+    SecretKey = "<your AWS Secret Access Key>"
+    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]`
+
+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
+    MaxBuilds = 100
+    MachineDriver = "amazonec2"
+    MachineName = "gitlab-docker-machine-%s"
+    OffPeakPeriods = ["* * 0-7,19-23 * * mon-fri *", "* * * * * sat,sun *"]
+    OffPeakIdleCount = 0
+    OffPeakIdleTime = 1200
+    MachineOptions = [
+      "amazonec2-access-key=XXXX",
+      "amazonec2-secret-key=XXXX",
+      "amazonec2-region=us-east-1",
+      "amazonec2-vpc-id=vpc-xxxxx",
+      "amazonec2-subnet-id=subnet-xxxxx",
+      "amazonec2-use-private-address=true",
+      "amazonec2-tags=Name,gitlab-runner-autoscale",
+      "amazonec2-security-group=docker-machine-scaler",
+      "amazonec2-instance-type=m4.2xlarge",
+      "amazonec2-ssh-user=ubuntu",
+      "amazonec2-ssh-keypath=/etc/gitlab-runner/certs/gitlab-aws-autoscaler",
+      "amazonec2-zone=a",
+      "amazonec2-root-size=32",
+    ]
+```
+
+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