Migrate the multi-runner configuration from v1 to v2

Multi-runner v2 changes the configuration contract so that shared defaults, runner behavior, orchestration, and compute settings have clear ownership. The v2 contract is nested and provider-oriented; it is not a rename of every flat v1 variable.

This page explains how to translate the configuration. Moving the existing Terraform state is a separate step. After updating the configuration, follow the v1-to-v2 state migration runbook before applying v2 to an existing deployment.

What changes in v2

The v1 interface spreads shared settings across module inputs and puts most per-runner settings inside multi_runner_config.<name>.runner_config.

The v2 interface has two levels:

1. global_config* variables hold defaults shared by all runner lanes.
2. multi_runner_config.<name> holds a lane's overrides and selects exactly one orchestration provider and one compute provider.

The current providers are:

• orchestration_provider.webhook
• compute_provider.aws.ec2

Global provider blocks supply defaults and shared settings. They do not select the provider for a lane. Provider selection belongs inside each multi_runner_config.<name> entry.

Complete migration example

The repository includes a complete side-by-side migration example in examples/migration-test. It keeps the same lane key, resource prefix, and state backend while showing the v1 and v2 configuration as sibling directories:

• v1 main.tf and v2 main.tf
• v1 variables.tf and v2 variables.tf
• v1 v1.tfvars and v2 v2.tfvars
• v1 providers.tf and v2 providers.tf
• migration test README

Open the two main.tf files next to each other to see the configuration translation: v1 uses the legacy flat runner_config shape, while v2 uses global defaults plus nested runner, orchestration, and compute-provider blocks. The example also shows the corresponding v1 and v2 variable files and keeps the lane name (for example, large) unchanged. Use these files as a reference when adapting an existing deployment; do not apply both directories to the same deployment at the same time. After updating the real configuration, run the state migration procedure before the first v2 plan.

Global configuration

Use the following global variables for settings shared by multiple lanes:

For example, shared GitHub, runner, observability, webhook, and EC2 defaults are configured like this:

experimental_features = ["multi-runner-v2"]

global_config = {
  tags = {
    Environment = "production"
  }

  runner = {
    os           = "linux"
    architecture = "x64"
    extra_labels = ["self-hosted"]
  }
}

global_config_github = {
  app = {
    id             = var.github_app.id
    key_base64     = var.github_app.key_base64
    webhook_secret = var.github_webhook_secret
  }
}

global_config_observability = {
  logs = {
    retention_in_days = 30
  }
  metrics = {
    enabled = true
  }
}

global_config_orchestration_provider = {
  webhook = {
    eventbridge = {
      enabled       = true
      accept_events = ["workflow_job"]
    }
  }
}

global_config_compute_provider = {
  aws = {
    ec2 = {
      vpc_id      = module.network.vpc_id
      subnet_ids  = module.network.private_subnet_ids
    }
  }
}

The other global_config_* variables follow the same ownership model. Put a value in the global block when it is common to all lanes; put an override in a lane only when that lane needs a different value.

Per-lane configuration

Each v2 lane is keyed by the same logical runner name used in v1, but its settings use canonical nested blocks:

multi_runner_config = {
  large = {
    runner = {
      name_prefix = "large-"
      extra_labels = ["large"]
    }

    orchestration_provider = {
      webhook = {
        runner = {
          ephemeral     = true
          maximum_count = 10
        }

        matcherConfig = {
          labelMatchers = [["self-hosted", "linux", "x64", "large"]]
        }

        job_retry = {
          enabled = true
        }
      }
    }

    compute_provider = {
      aws = {
        ec2 = {
          instance_types = ["m6i.large"]
        }
      }
    }
  }
}

Values are resolved as:

lane override > global default > provider/module default

Tags merge at the same levels. A lane override changes only that lane; it does not change shared singleton resources or defaults for other lanes.

Common v1-to-v2 translations

The following table covers the most common settings. The exact v1 path can be either a root module variable or an attribute under multi_runner_config.<name>.runner_config.

Settings that are specific to one lane should remain in that lane instead of being copied into a global block.

Legacy and deprecated inputs

The following shapes belong to the stable v1 interface and should not be used for new v2 configuration:

• Root-level flat runner, webhook, pool, retry, SSM, logging, and EC2 inputs.
• github_app and additional_github_apps instead of global_config_github.
• multi_runner_config.<name>.runner_config and its flat attributes.
• v1 names such as enable_ephemeral_runners, enable_jit_config, runners_maximum_count, pool_config, and job_retry when they are used in the old location.

These legacy inputs remain available for v1 compatibility while the v2 interface is experimental. They are migration sources, not aliases that should be mixed into a v2 lane. When v2 is enabled, a lane containing the legacy runner_config object is rejected during validation.

The v2 names use canonical ownership and enablement conventions. For example:

# v1
multi_runner_config = {
  large = {
    runner_config = {
      enable_ephemeral_runners = true
      enable_jit_config         = true
      runners_maximum_count    = 10
      instance_types            = ["m6i.large"]
    }
  }
}

# v2
multi_runner_config = {
  large = {
    orchestration_provider = {
      webhook = {
        runner = {
          ephemeral          = true
          jit_config_enabled = true
          maximum_count      = 10
        }
      }
    }
    compute_provider = {
      aws = {
        ec2 = {
          instance_types = ["m6i.large"]
        }
      }
    }
  }
}

Feature gate and validation

V2 is selected only by explicitly setting:

experimental_features = ["multi-runner-v2"]

When the feature is enabled, Terraform validates that:

• The v2 GitHub App is complete under global_config_github.app.
• Every lane has a webhook orchestration provider and an AWS EC2 compute provider.
• Each lane has EC2 instance types, a VPC, and at least one subnet.
• No lane uses the legacy runner_config object.

Do not enable the feature flag until the configuration has been converted and the state migration has been planned. The feature flag changes which module resources are selected; it does not move existing state by itself.

Recommended migration order

1. Copy the v1 configuration and convert it to the v2 nested contract.
2. Keep the same lane keys, resource prefix, AWS account, region, backend, and root module address.
3. Validate the v2 configuration without applying it.
4. Use the state migration runbook to back up the v1 state and move the state addresses.
5. Enable experimental_features = ["multi-runner-v2"] and run a v2 plan.
6. Review the plan for unexpected replacements or resource recreation.
7. Apply v2 and run a second plan to confirm that it is empty.

Changing the input names without moving state leaves Terraform unable to match the old v1 addresses to the v2 resources. Conversely, moving state without converting the configuration leaves the v2 validation and provider contract unsatisfied.