> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploying a Runner with CloudFormation

> Deploy a Blink self-hosted runner on AWS using a CloudFormation template.

## Prerequisites

1. **AWS Account:** You need to have an AWS account to use AWS services, including CloudFormation.
2. **AWS EC2 Key Pair:** Before creating the CloudFormation stack, you should have an EC2 Key Pair set up in your AWS account. If you don't have one, you can follow the AWS documentation to create a key pair.
3. **Blink User:** You must have either the [Owner role](/docs/blink-platform/account-management/roles#1-owner),[Contributor role](/docs/blink-platform/account-management/roles#2-contributor), or a [custom role](/docs/blink-platform/account-management/roles#adding-a-new-role) that includes both the `runners:view` and `runners:edit` permissions. To learn more about role-based access and permissions, see the [User Roles documentation](/docs/blink-platform/account-management/roles).

***

## Deployment Guide

<Tip>Use CloudFormation as an option to deploy runners, if you don't have Helm or a Host with a Docker Engine.</Tip>

<Steps>
  <Step title="Add a New Runner">
    In the left-hand side navigation bar select **Runners** and proceed by clicking the "New Runner" button in the top-left corner. A dialogue box will then open.
  </Step>

  <Step title="Fill in the Parameters">
    * **Name**: Enter a name for the Runner group.
    * **Tags**: Add or create tags (optional).
    * **Default:** Check this box to set this Runner group as the default. When enabled, any workflows that do not explicitly specify a Runner group will automatically be assigned to this one.
  </Step>

  <Step>
    Click on the **CloudFormation** option and click on the blue *Cloudformation stack* link.
  </Step>

  <Step title="Sign into your AWS Account">
    Please sign into your AWS Account if you are not already signed in. You will then be redirected to a new page where you must fill out the **Quick create stack** form.
  </Step>

  <Step title="Enter the values in the form as follows">
    <div className="integrations-table">
      | Parameter                  | Description                                                                                                                                                                                                                        |
      | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | Stack name                 | Give your stack a name                                                                                                                                                                                                             |
      | BlinkURL                   | The Blink URL the runner should connect to. Do not change the default value. This parameter is mandatory.                                                                                                                          |
      | DiskSize                   | The disk size of the EC2 instance running the runner. Default is 40. This parameter is mandatory.                                                                                                                                  |
      | InstanceEc2KeyPair         | The EC2 Key Pair used for logging in to the EC2 instance running the Runner. This parameter is mandatory.                                                                                                                          |
      | InstanceSshAccessCIdrBlock | A CIDR block describing the IP addresses from which the EC2 instance running the Runner should be accessible from. This parameter is mandatory.                                                                                    |
      | InstanceType               | The type of the EC2 instance running the runner. Select a type from the drop-down menu. This parameter is mandatory.                                                                                                               |
      | LatestAmiID                | The path of the AWS SSM parameter which stores the AMI ID of the latest Amazon Linux version. Do not change the default value.                                                                                                     |
      | RunnerApiKey               | Copy from the text area in the Blink platform step 2 and paste the value. This parameter is mandatory.                                                                                                                             |
      | RunnerVersion              | Do not change the default value. This parameter is mandatory.                                                                                                                                                                      |
      | SubnetId                   | ID of a subnet which can access the internet in the given VPC. If this parameter and Vpcid will be left empty, a VPC with a public Subnet and an internet gateway will be created. Otherwise this parameter should be specified.   |
      | VpcId                      | ID of a VPC to create the EC2 instance running the runner in. If this parameter and SubnetId will be left empty, a VPC with a public Subnet and an internet gateway will be created. Otherwise this parameter should be specified. |
      | OnPremVaultUrl             | The URL of the Vault instance the Runner should connect to. Should be specified together with the OnPremVaultRootToken parameter.                                                                                                  |
      | OnPremVaultRootToken       | The Root Token of the Vault instance the Runner should connect to. Should be specified together with the OnPremVaultUrl parameter.                                                                                                 |
    </div>
  </Step>

  <Step title="Create Stack">
    Once you have entered all the correct values click 'Create stack'. AWS will create a stack form with all the specific values you filled out in the form.
  </Step>

  <Step title="Navigate to the Runners page in the **Blink Platform**">
    Click 'Close'. You can then head over to the **Runners** page in the **Blink Platform**, where you will see that your runner is now connected and how many instances it has.

    <Frame>
      <img src="https://mintcdn.com/blinkops-2/xyKLDJHFYJazyJhl/img/Runners/runners10.png?fit=max&auto=format&n=xyKLDJHFYJazyJhl&q=85&s=ed33a22902629f6e242cbc299f3bb8af" width="2830" height="430" data-path="img/Runners/runners10.png" />
    </Frame>
  </Step>

  <Step title="Connecting to the Runner Host created with CloudFormation">
    Once the stack is fully created from the above template, navigate to the `Outputs` tab. There you can find the `Ec2InstanceUser` and `Ec2InstancePublicDnsName` outputs, among others. Using the values of these 2 outputs and the key file which corresponds to the EC2 Key Pair you selected when creating the stack (The file should have been downloaded when the Key Pair was created), you should be able to log in to the Runner host by running the following command (given that the IP of the host from which you're running the command is within the range defined by the CIDR block you specified when creating the stack):

    ```jsx theme={"dark"}
      ssh -i <path_to_key_file> <value of Ec2InstanceUser output>@<value of Ec2InstancePublicDnsName output>
    ```
  </Step>
</Steps>

***

## Related Articles

<CardGroup cols={2}>
  <Card title="Deploying a Runner" icon="code-fork" href="/docs/blink-platform/runners/deploying-runner/deploying-self-hosted">
    Learn how to deploy a Blink Runner to execute workflows securely within your environment.
  </Card>

  <Card title="Deploying a Runner with Docker" icon="docker" href="/docs/blink-platform/runners/deploying-runner/dockers-runner">
    Guide to installing, configuring and deploying a Runner using Docker
  </Card>

  <Card title="Deploying a Runner with Kubernetes" icon="dharmachakra" href="/docs/blink-platform/runners/deploying-runner/kubernetes-runner">
    Guide to installing, configuring and deploying a Runner using Kubernetes
  </Card>

  <Card title="Configuring a Runner Group" icon="rectangle-history" href="/docs/blink-platform/runners/deploying-runner/runner-group">
    Deploy multiple on-prem Runners for high availability, parallel execution, or workload isolation.
  </Card>
</CardGroup>