Support for Cross-Account IAM Role Assumption in AWS Fleeting Plugin for GitLab Runner Autoscaler

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Summary

Currently, GitLab Runner’s AWS Fleeting Plugin does not support assuming cross-account IAM roles via native configuration (e.g., iam_profile, role_arn, or WithAssumeRoleCredentialOptions). This limitation prevents users from managing Auto Scaling Groups (ASGs) in different AWS accounts directly through the GitLab Runner manager.

Problem Statement

Users who run GitLab Runners in a central management account (e.g., AccountA) and wish to autoscale EC2 runners in one or more separate AWS accounts (e.g., AccountB, AccountC…) are currently blocked by the following issue:

  • The AWS Fleeting Plugin fails with:

rpc error: code = Unknown desc = unexpected number of autoscaling groups returned: 0

  • This occurs even when the instance role has permission to assume a valid cross-account role, and manual verification via aws sts assume-role works successfully.

Despite valid cross-account IAM configurations and working credential assumptions using the AWS CLI, the plugin is not able to discover ASGs in the target accounts, as it does not support injecting or refreshing temporary credentials via role assumption.

Workaround (Current State)

A workaround involves:

  1. Using aws sts assume-role to generate temporary credentials manually
  2. Saving them to named AWS profiles in ~/.aws/credentials
  3. Modifying config.toml to reference these profiles
  4. Automating credential refresh via cron (every 12h)
  5. Restarting the GitLab Runner service after refresh

This solution is cumbersome and error-prone, especially when managing runners across many accounts.

Feature Proposal

Implement native support for cross-account IAM Role assumption in the AWS Fleeting Plugin used by GitLab Runner’s docker-autoscaler executor. Specifically:

  1. Add role_arn, external_id, and session_name options to the plugin’s configuration (under [runners.autoscaler.options])
  2. Use AWS SDK’s AssumeRole mechanism internally to fetch temporary credentials automatically
  3. Support periodic credential refresh without restarting the GitLab Runner service
  4. Optionally support credential chaining, to assume a role via an intermediate role if needed

Benefits

  • Enables centralised GitLab Runner management across multiple AWS accounts
  • Simplifies secure multi-account deployment patterns in larger organisations
  • Removes the need for brittle scripting and manual credential refresh
  • Improves alignment with AWS IAM best practices by avoiding permanent keys

Justification

This is a common pattern in enterprise AWS environments that separate networking, infrastructure, and compute roles across accounts. Lack of support increases operational overhead and complicates secure CI/CD deployments.

Edited by 🤖 GitLab Bot 🤖