README.md

runwayctl

Runway command line tool.

Hacking on runwayctl

Preparing your Environment

1. Follow the developer setup guide at https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md.

2. Clone this project

3. Run scripts/prepare-dev-env.sh

4. Download https://gitlab.com/gitlab-org/terraform-images/-/raw/master/src/bin/gitlab-terraform.sh and have it on your $PATH as gitlab-terraform

5. Have https://github.com/docker/docker-credential-helpers installed on your path

6. Have a running Docker daemon

7. Configure authentication to the GCR registry: gcloud auth configure-docker us-east1-docker.pkg.dev

8. Configure the following environment variables:

   CI_API_V4_URL=https://gitlab.com/api/v4
   CI_PROJECT_ID=<id of the runway deployment repository>
   GITLAB_USER_LOGIN=<gitlab username>
   TF_PASSWORD=<gitlab token>
   TF_VAR_runway_service_id=<name of the runway deployment repository>
   TF_VAR_canary_percent=100
   TF_VAR_image=registry.gitlab.com/<path to your image>

9. Run make. This will create the runwayctl binary. Put this binary where your $PATH can find it, or use its full path when invoking commands. Make sure to recompile the binary every time you change Terraform files to make sure your changes are reflected.

Manual testing

To test changes in a specific branch, you can set runway_version to the branch name in a test project. This uses Runway at the specified branch, allowing you to see the effect of changes before the changes are merged into main.

In a test project, modify .gitlab-ci.yml to include Runway from a branch:

include:
  - project: 'gitlab-com/gl-infra/platform/runway/runwayctl'
    file: 'ci-tasks/service-project/runway.yml'
    inputs:
      runway_service_id: example-service-t205j6
      image: "$CI_REGISTRY_IMAGE/example-service:${CI_COMMIT_SHORT_SHA}"
      runway_version: my-development-branch
      #               ^^^^^^^^^^^^^^^^^^^^^

Note: Docker image tags for development branches are based on CI_COMMIT_REF_SLUG, eg replaces / with -.

If you are unsure of runway_version format, refer to container register.

Caveats

• Terraform state is often not backwards compatible. If the development branch uses a newer Terraform version, reverting the changes may leave the project in a broken state. In that case, you will likely need to "fail forward", i.e. upgrade to a newer Terraform version.
• The Git branch name and Docker tag have to match. This is not the case when the branch contains slashes, since the Git branch "foo/bar" results in the Docker tag "foo-bar".

Service Manifest

The service manifest allows service owners to configure infrastructure for a service. The file is named .runway/runway.yml and it adheres to JSON Schema specification for document annotation and validation.

The schema file is currently used for validation in CI pipelines and generating static documentation. Optionally, the schema file can be used locally w/ editor support to provide autocomplete and syntax highlighting.

The schema file is in the runwayctl repository. Refer to the generated static documentation for details.