> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# cci-labs/on-demand-runner

A orb that lets users spin up runners on demand durning a pipeline. Users are able to provision an EC2 instance on the fly, install the runner agent, and allow the runner to accept units of work.


## Jobs

### deploy

Provision and Configure an On Demand Runner Required Environment Variables:
  - AWS_AMI_ID
  - AWS_SECURITY_GROUP_ID
  - AWS_SSH_KEY
  - CIRCLECI_NAMESPACE
  - CIRCLE_TOKEN
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY


| Parameter | Type | Default | Description |
|---|---|---|---|
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. AWS_ACCESS_KEY_ID.
 |
| `aws-ami-id` | env_var_name | AWS_AMI_ID | An AWS AMI(Amazon Machine Image) ID for the image you want
spun up as an EC2 instance. Set this to the name of
the environment variable you will use to hold this
value, i.e. AWS_AMI_ID.
 |
| `aws-instance-type` | env_var_name | AWS_INSTANCE_TYPE | A valid instance type/size for a EC2 instance. If no instance type is provided
a t2.mirco will be selected. Set this to the name of the environment variable
you will use to hold this value, i.e. AWS_INSTANCE_TYPE.
 |
| `aws-region` | env_var_name | AWS_DEFAULT_REGION | Env var of AWS region to operate in. If no region is provided US-EAST-1
will be selected.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. $AWS_SECRET_ACCESS_KEY.
 |
| `aws-security-group-id` | env_var_name | AWS_SECURITY_GROUP_ID | The ID of the AWS security group you want to be applied
to the EC2 instance(s). Set this to the name of
the environment variable you will use to hold this
value, i.e. AWS_SECURITY_GROUP_ID.
 |
| `aws-ssh-key` | env_var_name | AWS_SSH_KEY | The name of the SSH key you want the EC2 instance(s) to have
injected. Please note you need to already have uploaded the key
to AWS to reference the SSH key name. Set this to the name of
the environment variable you will use to hold this value, i.e. AWS_SSH_KEY.
 |
| `aws-vpc-id` | env_var_name | AWS_VPC_ID | The ID of the VPC you want the EC2 instance(s) to be
deployed in. If left blank, the default VPC will be selected.
Set this to the name of the environment variable you will use
to hold this value, i.e. AWS_VPC_ID.
 |
| `circle-token` | env_var_name | CIRCLE_TOKEN | A valid Circle token for interacting with the CircleCI API. Please see
https://circleci.com/docs/2.0/managing-api-tokens/ for more details.
 |
| `circleci-namespace` | env_var_name | CIRCLECI_NAMESPACE | A CircleCI generated namespace for your organization. Please see
https://circleci.com/docs/2.0/orb-concepts/#namespaces for more details.
 |
| `number_of_runners` | env_var_name | NUMBER_OF_RUNNERS | Number of on demand runners to deploy. If no number is provided only 1
on demand runner will be deployed. PLEASE be careful setting this number.
 |
| `number_of_waits` | env_var_name | NUMBER_OF_WAITS | Number of on waits(10 seconds each) for the EC2 instance(s) to be provisioned before failure.
If no number is provided 18 waits(3 minutes) will be selected.
 |
| `resource_class` | string |  | Name of the resource class that will be generated and used for On Demand Runners.
If you do not have a resource class to use, please pass in 'pipeline.id'. Generally, it best
practice to pass in 'pipeline.id'. PLEASE note you need to set resource class to a
name that is not currently being used, as the resource class will be deleted.
 |
| `runner_user` | env_var_name | RUNNER_USER | The username the runner agent will utilize to run its service. If no username is given 'circleci' will be used.
 |
| `tag` | string | 3.10 | The `cimg/python` Docker image version tag. |
| `version` | string | 2.9.* | Ansible Version To Be Installed |

### destroy

Deprovision and Remove an On Demand Runner Required Environment Variables:
  - AWS_SSH_KEY
  - CIRCLECI_NAMESPACE
  - CIRCLE_TOKEN
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY


| Parameter | Type | Default | Description |
|---|---|---|---|
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. AWS_ACCESS_KEY_ID.
 |
| `aws-region` | env_var_name | AWS_DEFAULT_REGION | Env var of AWS region to operate in. If no region is provided US-EAST-1
will be selected.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. $AWS_SECRET_ACCESS_KEY.
 |
| `aws-ssh-key` | env_var_name | AWS_SSH_KEY | The name of the SSH key you want the EC2 instance(s) to have
injected. Please note you need to already have uploaded the key
to AWS to reference the SSH key name. Set this to the name of
the environment variable you will use to hold this value, i.e. AWS_SSH_KEY.
 |
| `circle-token` | env_var_name | CIRCLE_TOKEN | A valid Circle token for interacting with the CircleCI API. Please see
https://circleci.com/docs/2.0/managing-api-tokens/ for more details.
 |
| `circleci-namespace` | env_var_name | CIRCLECI_NAMESPACE | A CircleCI generated namespace for your organization. Please see
https://circleci.com/docs/2.0/orb-concepts/#namespaces for more details.
 |
| `number_of_runners` | env_var_name | NUMBER_OF_RUNNERS | Number of on demand runners to deploy. If no number is provided only 1
on demand runner will be deployed. PLEASE be careful setting this number.
 |
| `number_of_waits` | env_var_name | NUMBER_OF_WAITS | Number of on waits(10 seconds each) for the EC2 instance(s) to be provisioned before failure.
If no number is provided 18 waits(3 minutes) will be selected.
 |
| `resource_class` | string |  | Name of the resource class that will be generated and used for an On Demand Runner.
If you do not have a resource class to use, please pass in 'pipeline.id'. Generally, it best
practice to pass in 'pipeline.id'. PLEASE note you need to set resource class to a
name that is not currently being used, as the resource class will be deleted.
 |
| `tag` | string | 3.10 | The `cimg/python` Docker image version tag. |
| `version` | string | 2.9.* | Ansible Version To Be Installed |

## Examples

### run-test-on-runner

Deploy an On Demand Runner, Do Testing on the Runner and Destroy the On Demand Runner


```yaml
version: '2.1'
orbs:
  on-demand-runner: cci-labs/on-demand-runner@1.0.0
jobs:
  run-test-on-runner:
    machine: true
    resource_class: NAMESPACE/<< pipeline.id >>
    steps:
      - run: echo "Hello World! I am running on an On Demand Runner!"
workflows:
  example-workflow:
    jobs:
      - on-demand-runner/deploy:
          context: aws-creds
          resource_class: << pipeline.id >>
      - run-test-on-runner:
          requires:
            - on-demand-runner/deploy
      - on-demand-runner/destroy:
          context: aws-creds
          requires:
            - run-test-on-runner
          resource_class: << pipeline.id >>
```