Runway on Kubernetes Service

This guide walks you through onboarding your service to Runway for deployment on Kubernetes (AWS EKS or GCP GKE).

Ensure your service repository meets these requirements:

1. Project access tokens (recommended): Onboard your service repository to infra-mgmt to automate Project Access Token management, including token rotation. Follow the onboarding instructions in the repository README.

2. Container image pipeline: Your repository must build and push container images to the GitLab Container Registry. For Go applications, we recommend using goreleaser.

3. Semantic versioning: Include the semantic-release job from the common-ci-tasks repository. This automates version management and triggers deployments through git tags.

The workload inventory registers your service with Runway and grants deployment permissions.

1. Choose a Runway service ID: Select a globally unique identifier for your service.

   • Maximum length: 57 characters for EKS, 23 characters for GKE
   • If deploying to both EKS and GKE, create two separate service IDs (one per runtime)

2. Find your project ID: In your GitLab repository, click the vertical dots menu (⋮) and select “Copy project ID”

3. Identify authorized users: List the GitLab usernames (handles) who should have permission to release new versions

1. Open the appropriate workload inventory file:

   • AWS EKS: config/runtimes/eks/workloads.yml
   • GCP GKE: config/runtimes/gke/workloads.yml

2. Add your service entry following this format:

   - runway_service_id: your-service-id
     project_id: 12345678
     members:
       - username1
       - username2

3. Create a merge request and assign it to a Runway team member (see CODEOWNERS for the current list)

4. Ensure the CI pipeline passes before requesting review

After your workload inventory entry is merged, configure your service repository with the required Runway files.

Create a .runway directory in your repository root with a subdirectory matching your Runway service ID:

.runway/
└── your-service-id/
    ├── default-values.yaml
    └── eks-service.yaml  # or gke-service.yaml

Create .runway/${RUNWAY_SERVICE_ID}/default-values.yaml to define your service’s Kubernetes resources. This configuration generates a provider-agnostic Helm chart.

apiVersion: runway/v1.0.0-beta
kind: RunwayKubernetesService
metadata:
  name: example-service
spec:
  services:
    frontend:  # Service component name
      image: "registry.gitlab.com/gitlab-com/gl-infra/platform/runway/example-service:{{ .AppVersion }}"
      command: ["/bin/frontend"]
      container_port: 8080

      # Autoscaling configuration
      scalability:
        min_instances: 1
        max_instances: 20
        cpu_utilization: 70

      # Prometheus metrics configuration
      observability:
        scrape_targets:
          - "localhost:8082"

      # Resource requirements and limits
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
          ephemeral-storage: "512Mi"
        limits:
          cpu: "200m"
          memory: "256Mi"
          ephemeral-storage: "1Gi"

      # Health check configuration
      startup_probe:
        path: "/health?type=startup"
        timeout_seconds: 1
        period_seconds: 10
        failure_threshold: 10
      liveness_probe:
        path: "/health?type=liveness"
        timeout_seconds: 1
        period_seconds: 10
        failure_threshold: 3

Note: The {{ .AppVersion }} placeholder is automatically replaced with your service version during the build process.

Create a deployment configuration file based on your target runtime:

example-service-eks:
  serviceMixins:
    - "runway-eks.service-mixin"  # Required for EKS deployments

  metadata:
    labels:  # Required for infrastructure services
      gitlab.com/department: eng-infra
      gitlab.com/department_group: eng-infra-scalability
      gitlab.com/owner_email_handle: fforster
      gitlab.com/product_category: scalability

example-service-gke:
  serviceMixins:
    - "runway-gke.service-mixin"  # Required for GKE deployments

  metadata:
    labels:  # Required for infrastructure services
      gitlab.com/department: eng-infra
      gitlab.com/department_group: eng-infra-scalability
      gitlab.com/owner_email_handle: fforster
      gitlab.com/product_category: scalability

Important: The serviceMixins field is required to inject runtime-specific resources (such as Gateway definitions) into your Helm chart. The metadata labels are mandatory for infrastructure services—see the GitLab Infrastructure Standards for valid values.

Add Runway to your .gitlab-ci.yml file to enable automated deployments:

include:
  - project: 'gitlab-com/gl-infra/platform/runway/runwayctl'
    file: 'ci-tasks/service-project/helm-chart.yml'
    ref: v3.82.0  # Use the latest version from Runway releases
    inputs:
      runway_service_id: example-service-eks  # Your Runway service ID
      runway_version: v3.82.0  # Must match the ref above
      runtime: eks  # or 'gke'

Important:

• Check the Runway releases page for the latest version
• Both ref and runway_version must use the same version number
• Consider setting up Renovate to automatically update Runway versions

The CI configuration adds two types of jobs to your pipeline:

1. Dry-run jobs (merge request pipelines): Validate your configuration without deploying
2. Release jobs (tag pipelines): Deploy your service when a new semantic version tag is created

Your service deploys automatically when:

• A commit triggers a new semantic release (feat, fix, or breaking change)
• The semantic-release job creates a new version tag
• The tag pipeline runs and executes the release job

Maintenance commits (chore, docs, …) don’t trigger deployments by default.

• Monitor your merge request and tag pipelines to verify successful deployment
• Review the GitLab Infrastructure Standards for metadata label requirements
• Set up Renovate for automatic Runway version updates
• Consult the Runway team in the #g_runway Slack channel for support

To deploy your service to both EKS and GKE:

1. Create two separate Runway service IDs (e.g., myservice-eks and myservice-gke)
2. Add both IDs to their respective workload inventories
3. Create separate configuration directories for each:

   .runway/
   ├── myservice-eks/
   │   ├── default-values.yaml
   │   └── eks-service.yaml
   └── myservice-gke/
       ├── default-values.yaml
       └── gke-service.yaml

4. Include ci-tasks/service-project/helm-chart.yml twice in your .gitlab-ci.yml, once for each Runway Service ID