Knowledge document for Fargate GitLab runners CI
This repo is documentation about our GitLab CI on AWS ECS system using Fargate tasks. Mainly following the Official GitLab Fargate Guide.
We use an EC2 instance that polls GitLab for pipeline requests, and schedules the ECS Fargate tasks. Each job in the pipeline will get scheduled into a different Fargate container, and the EC2 will coordinate between them.
Since our GitLab pipelines are based on alpine, we need to modify the Dockerfile mentioned in the official docs. We change the underlying image to alpine and use APK to install stuff.
In the dockerfile we specify an Entrypoint script, ours differs a bit from the guide again, due to different underlying OS, we need to add some alpine-specific commands to make sure the SSH server works correctly.
A little Registration Script utility was written to help register many tokens at once. It registers a group/project using the GitLab-runner binary and then uses string replace to correct the configuration file, as some changes are needed like mentioned in the official docs. You use the script just by executing it with a list of runner tokens as command line parameters. If you have a very large amount of tokens that do not fit within the CLI limit, you might need to modify the script or split the list into smaller chunks.
We forked the official GitLab Fargate driver to add retries to the SSH execution in order to prevent errors.
Our Fork: https://gitlab.com/ekronot2023/fargate
Original Repo: https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/fargate
You should follow the official guide as mentioned at the start, here are some comments about the divergence from the original guide:
Build the Dockerfile into an image, giving it an appropriate name. Docs
After your image is built, Go to AWS ECR (Elastic Container Registry), and select or create a new repo. Then click the 'View push commands' button and follow the instructions on how to authenticate and push your image to ECR. Docs
Create an EC2 instance following the instructions on the Docs, including the IAM role, Security Group, and Key Pair (Unless you have one already).
Follow the instructions on the Docs to install the GitLab runner, up until the point of installing the Fargate driver. Here we diverge from the docs a little bit, we modified the driver to reconnect on SSH connection, to prevent some of the errors that we encountered.
In the EC2, install Go according to the official instructions. Clone our fork of the driver. Inside the clone repo, run go build ./cmd/fargate/. Copy the resulting binary to /opt/gitlab-runner/.
Follow the 5 and 6 Docs to create and configure the ECS cluster with the Fargate task. Remember to input the ECR image we created earlier, and change the config from stage 4 to match the ECS cluster.