---
page_title: "ona_runner Resource - ona"
subcategory: "Runners"
description: |-
  Ona runner registration. Use this resource to create a remote runner record, then deploy the runner with the generated setup output for the selected provider.
---

# ona_runner (Resource)

Ona runner registration. Use this resource to create a remote runner record, then deploy the runner with the generated setup output for the selected provider.

For product context, see [Runner infrastructure](https://ona.com/docs/ona/runners/overview), [AWS runners](https://ona.com/docs/ona/runners/aws/overview), and [GCP runners](https://ona.com/docs/ona/runners/gcp/overview).

## Example Usage

```terraform
variable "custom_metrics_password" {
  description = "Password or token for the custom metrics pipeline."
  type        = string
  sensitive   = true
}

resource "ona_runner" "aws_primary" {
  name            = "aws-us-east-primary"
  runner_provider = "aws_ec2"

  configuration {
    region                           = "us-east-1"
    release_channel                  = "stable"
    auto_update                      = true
    devcontainer_image_cache_enabled = true
    log_level                        = "info"

    metrics {
      managed {
        enabled = true
      }
    }

    update_window {
      start = "02:00"
      end   = "04:00"
    }
  }
}

# AWS runners return a CloudFormation template URL for runner deployment.
output "aws_cloudformation_template_url" {
  value = ona_runner.aws_primary.cloudformation_template_url
}

output "aws_terraform_module_url" {
  value = ona_runner.aws_primary.terraform_module_url
}

# GCP runners do not use CloudFormation, so cloudformation_template_url is null.
resource "ona_runner" "gcp_primary" {
  name            = "gcp-us-central-primary"
  runner_provider = "gcp"

  configuration {
    release_channel                  = "stable"
    auto_update                      = true
    devcontainer_image_cache_enabled = true
    log_level                        = "info"

    metrics {
      custom {
        enabled  = true
        url      = "https://metrics.example.com/api/v1/write"
        username = "runner"
        password = var.custom_metrics_password

        # Change this marker with password to rotate the custom metrics credentials.
        password_version = "1"
      }
    }
  }
}

output "gcp_terraform_module_url" {
  value = ona_runner.gcp_primary.terraform_module_url
}
```

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- `name` (String) Runner display name shown in Ona.
- `runner_provider` (String) Cloud provider for the runner. Supported values are `aws_ec2` and `gcp`. Changing this value replaces the runner.

### Optional

> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.

- `configuration` (Block, Optional) Runner configuration applied to the remote runner. Some fields are provider defaults and are preserved in Terraform state after creation. (see [below for nested schema](#nestedblock--configuration))

### Read-Only

- `cloudformation_template_url` (String) CloudFormation template URL for AWS EC2 runner setup. This is populated only for `aws_ec2` runners and is null for GCP runners.
- `created_at` (String) Time when the runner was created.
- `creator` (Attributes) Identity that created the runner. (see [below for nested schema](#nestedatt--creator))
- `id` (String) Terraform resource ID. This is the same value as `runner_id`.
- `kind` (String) Runner kind assigned by the Ona API from the selected provider.
- `runner_id` (String) Ona runner ID. Use this value when configuring runner environment classes, SCM integrations, and runner token flows.
- `terraform_module_url` (String) Terraform module URL for deploying runner infrastructure with native cloud-provider resources. AWS EC2 runners link to the unversioned public AWS module repository because it has no official release; GCP runners link to the latest published module in the Terraform Registry.

<a id="nestedblock--configuration"></a>
### Nested Schema for `configuration`

Optional:

> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.

- `auto_update` (Boolean) Whether the runner should automatically update itself. Defaults to the provider value `true`.
- `devcontainer_image_cache_enabled` (Boolean) Whether the shared devcontainer image build cache is enabled for this runner. Defaults to the provider value `true`.
- `log_level` (String) Runner log level. Supported values are `debug`, `info`, `warn`, and `error`. Defaults to the provider value `info`.
- `metrics` (Block, Optional) Metrics delivery configuration. Configure Ona-managed metrics, a custom remote-write pipeline, or both. (see [below for nested schema](#nestedblock--configuration--metrics))
- `region` (String) Cloud region for the runner. Required for `aws_ec2` runners and omitted for providers that do not use this setting. Changing this value replaces the runner.
- `release_channel` (String) Runner release channel. Supported values are `stable` and `latest`. Defaults to the provider value `stable`.
- `update_window` (Block, Optional) Daily UTC window during which runner auto-updates may run. (see [below for nested schema](#nestedblock--configuration--update_window))

<a id="nestedblock--configuration--metrics"></a>
### Nested Schema for `configuration.metrics`

Optional:

> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.

- `custom` (Block, Optional) Custom remote-write metrics pipeline configuration. (see [below for nested schema](#nestedblock--configuration--metrics--custom))
- `managed` (Block, Optional) Ona-managed metrics pipeline configuration. (see [below for nested schema](#nestedblock--configuration--metrics--managed))

<a id="nestedblock--configuration--metrics--custom"></a>
### Nested Schema for `configuration.metrics.custom`

Optional:

> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.

- `enabled` (Boolean) Whether the runner sends metrics to the custom pipeline. Defaults to `false`.
- `password` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Password or token for authenticating to the custom metrics pipeline. This write-only value is sent to Ona but is not stored in Terraform plan or state. Set this when creating the custom pipeline or changing `password_version`.
- `password_version` (String) User-managed rotation marker for resubmitting `password`. Change this value with a new password to rotate the custom metrics credentials.
- `url` (String) Remote-write URL for the custom metrics pipeline.
- `username` (String) Username for authenticating to the custom metrics pipeline.


<a id="nestedblock--configuration--metrics--managed"></a>
### Nested Schema for `configuration.metrics.managed`

Optional:

- `enabled` (Boolean) Whether the runner sends metrics through Ona's managed metrics pipeline. Defaults to `false`.



<a id="nestedblock--configuration--update_window"></a>
### Nested Schema for `configuration.update_window`

Optional:

- `end` (String) End time in `HH:00` UTC format. If omitted, the API defaults to two hours after `start`.
- `start` (String) Start time in `HH:00` UTC format. Required when `update_window` is set.



<a id="nestedatt--creator"></a>
### Nested Schema for `creator`

Read-Only:

- `id` (String) Creator subject ID.
- `principal` (String) Creator principal type.

## Import

Import is supported using the following syntax:

The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:

```shell
#!/usr/bin/env sh

terraform import ona_runner.aws_primary 01980ed3-a090-7b5b-a74c-9bf5d8cfe53c
```