Installation

IAM policy builder

Generate the orchestrator role's IAM policy with your account ID, region, and runner instance role substituted in. Copy or download — no values leave the browser.

2 min read

Fill in the three fields below. The policy regenerates as you type. Nothing is sent anywhere — substitution runs entirely in your browser.

12 digits. The account where the orchestrator runs.
Single region. Matches aws.region in your YAML config.
The role the orchestrator passes to spawned EC2 instances. Just the name, not the ARN. Leave blank if your pools won't attach an instance profile -- the PassRunnerInstanceProfile statement is omitted from the generated policy.
// fill the fields above to generate the policy

Apply the policy

Save what you copied as iam-role.json (or use the Download button), then attach it to the orchestrator’s IAM role with the AWS CLI:

ROLE=pacer-orchestrator     # the role your tool assumes; not the runner-instance role

aws iam put-role-policy \
  --role-name "$ROLE" \
  --policy-name pacer-orchestrator \
  --policy-document file://iam-role.json

Verify it landed:

aws iam get-role-policy \
  --role-name "$ROLE" \
  --policy-name pacer-orchestrator \
  --query 'PolicyDocument.Statement[].Sid' --output table

You should see the Sids that were generated — DescribeForValidation, ReadOnDemandPricing, ValidateInstanceProfileAtPoolSave, CreateTaggedLaunchTemplate, ModifyOnlyOurLaunchTemplates, RunInstancesReadOnlyResources, RunInstancesFromOurLaunchTemplate, RunInstancesTaggedInstanceAndVolume, TagOnCreate, TerminateOnlyOurInstances, and (only when you provided a runner instance role above) PassRunnerInstanceProfile.

Notes

  • The gha:managed-by value is hard-coded to pacer in the binary (internal/core/ec2lt/ec2lt.go::ManagedByTagValue). Don’t change it unless you also fork the binary.
  • Runner instance role is optional. Leave the field blank if your pools won’t attach an instance profile – the generator drops the PassRunnerInstanceProfile statement entirely. The orchestrator’s iam:PassRole permission is only exercised when a pool’s iam_instance_profile field is non-empty AND the launch causes EC2 to attach a profile to the instance. If you later add an instance profile to a pool, regenerate the policy with the role name filled in – otherwise the spawn fails with Insufficient privileges to pass role.
  • Cost-tracking statements (ReadOnDemandPricing, ec2:DescribeSpotPriceHistory inside DescribeForValidation) are optional. Drop them if you don’t want at-launch cost snapshots; the orchestrator will log a warning and stamp NULL prices.
  • ValidateInstanceProfileAtPoolSave is optional. Without it the pool save still works, but a missing instance profile only surfaces at the first spawn (with a cryptic EC2 error). Harmless to keep even when no pool uses an instance profile.
  • For multiple runner-instance roles, edit the Resource of PassRunnerInstanceProfile to a list of role ARNs, or to a path-based wildcard like arn:aws:iam::ACCOUNT:role/runners/*.
  • Want to verify the policy’s effective decisions before applying? See the simulator commands at the bottom of the AWS-side guide.