Code for running GitLab CI/CD jobs on cloud.gov or another CloudFoundry based PaaS.
The goal of this runner executor is to support most CI/CD use cases without
needing to modify your .gitlab-ci.yml
. Please note the current limitiations
and differences in comparison to the Docker executor:
CI_SERCVCE_<alias>
variable for each service defined in a job. Here is an
example snippet of GitLab CI Yaml showing the definition of a service and how
the job steps can then connect to that service:
# Start a HTTP "echo" service and then send a request to it
echo-test-job:
stage: test
image: ubuntu:jammy
services:
- name: http-https-echo:latest
# Note "echo" is the alias name, so the CI_SERVICE_alias variable key name
# for this service is CI_SERVICE_echo
alias: echo
script:
# Using the CI_SERVICE_alias to provide the FQDN of the service
- curl http://${CI_SERVICE_echo}:8080
This is a custom executor borrowing ideas from https://docs.gitlab.com/runner/executors/custom.html.
It runs a "manager" GitLab Runner instance responsible for listening for new jobs. Each job is run on a new application instance in CloudFoundry using the specified OCI image.
The relevant components of the solution are shown above with two running stages.
cf ssh
calls into the running containers.The above sequence diagram illustrates the series of events in a given job run.
Optional service lifecycles are not shown, but run as part of the prepare
phase.
The runner manager registration and other flow details are shown in Runner Execution Flow.
Log in to cloud.gov
cf login -a api.fr.cloud.gov --sso
Target the org and space for deployment
cf target -o ORGNAME -s SPACENAME
For example:
cf target -o sandbox-gsa -s bret.mogilefsky
Create a cloud.gov service account, tagged with gitlab-service-account
cf create-service cloud-gov-service-account space-deployer SERVICE_ACCOUNT_INSTANCE -t "gitlab-service-account"
Create a cloud.gov brokered S3 bucket - basic-sandbox
is suggested.
Note that OBJECT_STORE_INSTANCE
only needs to be unique within the specific space as it will have a prefix prepended to create the S3 bucket name.
cf create-service s3 basic-sandbox OBJECT_STORE_INSTANCE
Copy vars.yml-template
to vars.yml
cp vars.yml-template vars.yml
Edit vars.yml
and modify the values there as needed. In particular, you must
ci_server_token
provided when you configure the runner at the target GitLab URLservice_account_instance
name that you used when you created the service instance in step 3object_store_instance
name that you used when you created the brokered S3 bucket in step 4Deploy the GitLab runner
cf push --vars-file vars.yml
Check to see that the runner has registered itself in GitLab under your project repository under Settings -> CI/CD -> Runners (Expand)
At this point the runner should be available to run jobs. See Use GitLab - Use CI/CD to build your application - Getting started for much more on GitLab CI/CD and runners.
Problems with runner registration often requiring viewing it's logs.
cf logs --recent RUNNER-NAME
The GitLab Runner manager needs to contact the CloudFoundry API to schedule runner applications. This indicates your CloudFoundry space security group may be too restrictive or not set.
For a production deployment you should use tightly controlled egress filtering, ideally with a name based proxy.
Test Only - For a basic test environment with no privileged access you can use the following to apply a loose egress security group policy on cloud.gov:
cf bind-security-group public_networks_egress ORG_NAME --space SPACE_NAME
prepare.sh
.gitlab-runner-helper
installation in prepare.sh
.Recent versions of gitlab-runner
expose almost all initial configuration
variables for the register
subcommand as environment variables. This allows
us to do almost all configuration in manifest.yml
and skip modifying
command line options in runner/.profile
or having a .toml add on.