GitLab Runner on AWS Windows EC2 Instances
Prerequisites :
- EC2 instance using latest
Windows Server-2019
AMI. Git
is installed.- A password for your user account, if you want to run it under your user account rather than the Built-in System Account.
Microsoft Docker Provider
(PowerShell as administrator):
Ensure Hyper-V is enabled
Enable-WindowsOptionalFeature
-Online
-FeatureName
Microsoft-Hyper-V
-All
Install all Hyper-V tools
Install-WindowsFeature
RSAT-hyper-V-tools
-IncludeAllSubFeature
Install the Microsoft Docker Provider
Install-PackageProvider
-Name
NuGet -MinimumVersion
2.8.5.201 -Force
Install-Module
-Name
DockerMsftProvider -Repository
PSGallery -Force
Install Docker
Install-Package
-Name
docker -ProviderName
DockerMsftProvider
Restart Server to ensure Docker service is running
Restart-Computer
-Force
Installation Steps:
- Create a folder , example —
C:\GitLab-Runner
. - Download the binary for 64-bit or 32-bit and put it into the folder you created. The following assumes you have renamed the binary to
gitlab-runner.exe
(optional). - Make sure to restrict the
Write
permissions on the GitLab Runner directory and executable. If you do not set these permissions, regular users can replace the executable with their own and run arbitrary code with elevated privileges.
Register Runner:
- Run the following command to register and install GitLab Windows runner. We need to run the commands from elevated command prompt :
Register GitLab Runner
.\gitlab-runner.exe register
Install GitLab Runner
.\gitlab-runner.exe install
Start GitLab Runner Service
.\gitlab-runner.exe start
- Once the commands are executed, check
GitLab Repo → Settings → CI/CD → Runners
section and verify the runner is added and showing Online status. - Execute the Pipeline with matching tag and make sure the runner is getting picked and pipeline is successful .
Configuration for Concurrent execution:
- After registration is completed we need to update `config.toml` file for concurrent execution. We need to change the `concurrent` value based on requirement.
concurrent = 5
check_interval = 0
- Restart the runner service and verify service is up with following commands:
Configuration
.\gitlab-runner.exe stop
.\gitlab-runner.exe start
.\gitlab-runner.exe verify
- Go to the repo and run the pipeline concurrently number of times and it should run concurrent pipeline till the concurrent value is hit.
Limitations:
- Windows GitLab runner don’t support Autoscaling as of now. We can achieve concurrency for executor using config.toml but autoscaling Windows gitlab runner is not possible yet.
- GitLab Runner only supports the following versions of Windows which follows Microsoft’s support lifecycle for Windows:
Windows Server 20H2.
Windows Server 2004.
Windows Server 1809.
- Linux container is not supported as executor on EC2 Windows runner. We need bare-metal Windows for this to work.
- Docker Desktop is not supported on Windows EC2 runner as it requires hardware support for Hyper-V Nested Virtualization. We need bare-metal Windows for this to work.
- Only Microsoft supported official Windows images can be used as Executor. Unsupported Windows image can not be used.
- Docker-in-docker is not supported.
- Gitlab runner installation must use
'C:'
as installation drive letter. Other drive letters are not supported yet.
Other Important GitLab Runner Commands:
Stop GitLab Runner Service
.\gitlab-runner.exe stop
Uninstall GitLab Runner
.\gitlab-runner.exe uninstall
Get GitLab Runner Logs
Get-WinEvent
-ProviderName
gitlab-runner
Troubleshooting :
- Issue: Fail to Pull image
Cause: The image is not supported for Windows Docker
Resolution: Use Microsoft supported image as executor.
- Issue: Runner showing offline / not connected in GitLab Repo CI/CD settings
Cause: GitLab runner service is stopped or it is uninstalled
Resolution: Start GitLab runner service using .\gitlab-runner.exe start command or install using .\gitlab-runner.exe install command and then start the service. Verify service is up.
- Issue: GitLab pipeline is stuck
Cause: No runner with matching tag found
Resolution: Check GitLab runner section and update tag as required.
- Issue: Failed to Pull image , not enough space available.
Cause: Less space available on disk
Resolution: Increase disk size or remove unwanted files to free up some spaces.
- Issue: System failure
Cause: Container OS does not matches with host OS
Resolution: Use compatible OS
#aws #linux #cicd #gitlab