Merge branch 'windows-shared-runners-beta-12.7-docs' into 'master'

Add Windows Shared Runners to GitLab.com settings page of user docs

See merge request gitlab-org/gitlab!23222

doc/user/gitlab_com/index.md

@@ -95,7 +95,11 @@ IP based firewall can be configured by looking up all
 
 ## Shared Runners
 
-Shared Runners on GitLab.com run in [autoscale mode] and powered by Google Cloud Platform.
+GitLab offers Linux and Windows shared runners hosted on GitLab.com for executing your pipelines.
+
+### Linux Shared Runners
+
+Linux Shared Runners on GitLab.com run in [autoscale mode] and are powered by Google Cloud Platform.
 Autoscaling means reduced waiting times to spin up CI/CD jobs, and isolated VMs for each project,
 thus maximizing security. They're free to use for public open source projects and limited
 to 2000 CI minutes per month per group for private projects. More minutes
@@ -122,7 +126,7 @@ Below are the shared Runners settings.
 | Default Docker image                  | `ruby:2.5`                                        | -          |
 | `privileged` (run [Docker in Docker]) | `true`                                            | `false`    |
 
-### `config.toml`
+#### `config.toml`
 
 The full contents of our `config.toml` are:
 
@@ -184,6 +188,158 @@ sentry_dsn = "X"
       BucketName = "bucket-name"
 ```
 
+### Windows Shared Runners (beta)
+
+The Windows Shared Runners are currently in
+[beta](https://about.gitlab.com/handbook/product/#beta) and should not be used
+for production workloads.
+
+During the beta period for groups and private projects the use of
+Windows Shared Runners will count towards the [shared runner pipeline
+quota](https://docs.gitlab.com/ee/user/admin_area/settings/continuous_integration.html#shared-runners-pipeline-minutes-quota-starter-only)
+as if they are Linux Runners, we do have plans to change this in
+[#30835](https://gitlab.com/gitlab-org/gitlab/issues/30834).
+
+Windows Shared Runners on GitLab.com automatically autoscale by
+launching virtual machines on the Google Cloud Platform. This solution uses
+a new [autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md)
+developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html).
+Windows Shared Runners execute your CI/CD jobs on `n1-standard-2` instances with 2
+vCPUs and 7.5GB RAM. You can find a full list of available Windows packages in the
+[package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md).
+
+We want to keep iterating to get Windows Shared Runners in a stable state and
+[generally available](https://about.gitlab.com/handbook/product/#generally-available-ga).
+You can follow our work towards this goal in the
+[related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162).
+
+#### Configuration
+
+The full contents of our `config.toml` are:
+
+```toml
+concurrent = 10
+check_interval = 3
+
+[[runners]]
+  name = "windows-runner"
+  url = "https://gitlab.com/"
+  token = "TOKEN"
+  executor = "custom"
+  builds_dir = "C:\\GitLab-Runner\\builds"
+  cache_dir = "C:\\GitLab-Runner\\cache"
+  shell  = "powershell"
+  [runners.custom]
+    config_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe"
+    config_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "config"]
+    prepare_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe"
+    prepare_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "prepare"]
+    run_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe"
+    run_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "run"]
+    cleanup_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe"
+    cleanup_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "cleanup"]
+```
+
+The full contents of our `autoscaler/config.toml` are:
+
+```toml
+Provider = "gcp"
+Executor = "winrm"
+OS = "windows"
+LogLevel = "info"
+LogFormat = "text"
+LogFile = "C:\\GitLab-Runner\\autoscaler\\autoscaler.log"
+VMTag = "windows"
+
+[GCP]
+  ServiceAccountFile = "PATH"
+  Project = "some-project-df9323"
+  Zone = "us-east1-c"
+  MachineType = "n1-standard-2"
+  Image = "IMAGE"
+  DiskSize = 50
+  DiskType = "pd-standard"
+  Subnetwork = "default"
+  Network = "default"
+  Tags = ["TAGS"]
+  Username = "gitlab_runner"
+
+[WinRM]
+  MaximumTimeout = 3600
+  ExecutionMaxRetries = 0
+
+[ProviderCache]
+  Enabled = true
+  Directory = "C:\\GitLab-Runner\\autoscaler\\machines"
+```
+
+#### Example
+
+Below is a simple `.gitlab-ci.yml` file to show how to start using the
+Windows Shared Runners:
+
+```yaml
+.shared_windows_runners:
+  tags:
+  - shared
+  - windows
+  - windows-1809
+
+stages:
+  - build
+  - test
+
+before_script:
+ - date +"%H"
+ - echo ${HOUR}
+ - echo "started by ${GITLAB_USER_NAME}"
+
+build:
+  extends:
+  - .shared_windows_runners
+  stage: build
+  script:
+  - echo "running scripts in the build job"
+
+test:
+  extends:
+  - .shared_windows_runners
+  stage: test
+  script:
+  - echo "running scripts in the test job"
+```
+
+#### Limitations and known issues
+
+- All the limitations mentioned in our [beta
+  definition](https://about.gitlab.com/handbook/product/#beta).
+- The average provisioning time for a new Windows VM is 5 minutes.
+  This means that for the beta you will notice slower build start times
+  on the Windows Shared Runner fleet compared to Linux. In a future
+  release we will add the ability to the autoscaler which will enable
+  the pre-warming of virtual machines. This will significantly reduce
+  the time it takes to provision a VM on the Windows fleet. You can
+  follow along in this
+  [issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/issues/32).
+- The Windows Shared Runner fleet may be unavailable occasionally
+  for maintenance or updates.
+- The Windows Shared Runner virtual machine instances do not use the
+  GitLab Docker executor. This means that unlike the Linux Shared
+  Runners, you will not be able to specify `image` and `services` in
+  your pipeline configuration.
+- For the beta release, we have included a set of software packages in
+  the base VM image. If your CI job requires additional software that's
+  not included in this list, then you will need to add installation
+  commands to [`before_script`](../../ci/yaml/README.md#before_script-and-after_script) or [`script`](../../ci/yaml/README.md#script) to install the required
+  software. Note that each job runs on a new VM instance, so the
+  installation of additional software packages needs to be repeated for
+  each job in your pipeline.
+- The job may stay in a pending state for longer than the
+  Linux shared Runners.
+- There is the possibility that we introduce breaking changes which will
+  require updates to pipelines that are using the Windows Shared Runner
+  fleet.
+
 ## Sidekiq
 
 GitLab.com runs [Sidekiq](https://sidekiq.org) with arguments `--timeout=4 --concurrency=4`