Manage Runpod infrastructure with Terraform

The Runpod Terraform provider lets you manage Runpod infrastructure declaratively using HashiCorp Terraform. Define pods, serverless endpoints, templates, and machines in HCL configuration files, apply them with terraform apply, and track state like any other Terraform-managed resource.

Prerequisites

Terraform 1.0 or higher
A Runpod API key

Install and configure

Add the provider to your configuration

Create a main.tf file and declare the Runpod provider:

terraform {
  required_providers {
    runpod = {
      source  = "runpod/runpod"
      version = "~> 1.0"
    }
  }
}

provider "runpod" {
  api_key = var.runpod_api_key
}

Set your API key

The recommended approach is to pass your API key as an environment variable so it stays out of your configuration files:

export RUNPOD_API_KEY="your-api-key-here"

Or declare it as a Terraform variable and pass it at apply time:

variable "runpod_api_key" {
  description = "Runpod API key"
  type        = string
  sensitive   = true
}

terraform apply -var="runpod_api_key=your-api-key-here"

Initialize and apply

terraform init
terraform plan
terraform apply

Quick example: create a pod

This example creates a GPU pod running Miniconda with SSH enabled:

terraform {
  required_providers {
    runpod = {
      source  = "runpod/runpod"
      version = "~> 1.0"
    }
  }
}

provider "runpod" {
  api_key = var.runpod_api_key
}

variable "runpod_api_key" {
  type      = string
  sensitive = true
}

resource "runpod_pod" "my_pod" {
  image_name  = "runpod/miniconda:py3.10-cuda11.8.0"
  gpu_count   = 1
  gpu_type_id = "NVIDIA GeForce RTX 4090"
  cloud_type  = "SECURE"
  start_ssh   = true

  env = [
    "MY_VAR=hello"
  ]
}

output "pod_id" {
  value = runpod_pod.my_pod.id
}

output "pod_status" {
  value = runpod_pod.my_pod.status
}

Resources

`runpod_pod`

Creates and manages a Runpod pod.

resource "runpod_pod" "example" {
  image_name  = "runpod/miniconda:py3.10-cuda11.8.0"
  gpu_count   = 1
  gpu_type_id = "NVIDIA GeForce RTX 4090"
  cloud_type  = "SECURE"
  start_ssh   = true
}

Arguments

Argument	Type	Required	Description
`image_name`	string	Optional*	Docker image name. Required if `template_id` is not set.
`template_id`	string	Optional*	Pod template ID. Required if `image_name` is not set.
`machine_id`	string	Optional	Machine ID to deploy on.
`gpu_type_id`	string	Optional	GPU type ID. Auto-selected if omitted.
`gpu_count`	number	Optional	Number of GPUs. Default: `1`.
`cloud_type`	string	Optional	`COMMUNITY`, `SECURE`, or `ALL`. Default: `SECURE`.
`name`	string	Optional	Pod name.
`docker_args`	string	Optional	Docker arguments.
`env`	list(string)	Optional	Environment variables as `["KEY=VALUE", ...]`.
`port`	number	Optional	Main port for the pod.
`ports`	string	Optional	Port configuration string (e.g. `"8080/http,22/tcp"`).
`volume_in_gb`	number	Optional	Persistent volume size in GB.
`volume_mount_path`	string	Optional	Path to mount the volume inside the container.
`volume_key`	string	Optional	Volume encryption key (sensitive).
`container_disk_in_gb`	number	Optional	Container disk size in GB.
`start_ssh`	bool	Optional	Start SSH on boot. Default: `false`.
`start_jupyter`	bool	Optional	Start Jupyter notebook on boot. Default: `false`.
`bid_per_gpu`	number	Optional	Bid price per GPU for interruptible (spot) pods.
`stop_after`	string	Optional	Auto-stop timestamp in ISO 8601 format.
`terminate_after`	string	Optional	Auto-terminate timestamp in ISO 8601 format.

Attributes (read-only)

Attribute	Description
`id`	Pod ID assigned after creation.
`status`	Current pod status.
`cost_per_hr`	Cost per hour.
`memory_in_gb`	Memory allocated in GB.
`vcpu_count`	Virtual CPU count.
`cluster_ip`	Cluster IP address.
`created_at`	Creation timestamp.
`locked`	Whether the pod is locked.

`runpod_pod_action`

Performs an action on an existing pod. Use this to stop, resume, terminate, or reset a pod without destroying and recreating it.

resource "runpod_pod_action" "stop" {
  pod_id = runpod_pod.example.id
  action = "stop"
}

Arguments

Argument	Type	Required	Description
`pod_id`	string	Required	ID of the pod to act on.
`action`	string	Required	Action to perform: `stop`, `resume`, `terminate`, or `reset`.

Attributes (read-only)

Attribute	Description
`status`	Pod status after the action completes.

`runpod_template`

Creates and manages a reusable pod template. Templates let you define a standard configuration (image, environment variables, disk, ports) once and reuse it across multiple pods or endpoints.

resource "runpod_template" "my_template" {
  name       = "my-vllm-template"
  image_name = "runpod/worker-vllm:stable-cuda12.1.0"

  env = {
    MODEL_NAME = "meta-llama/Llama-3.1-8B-Instruct"
  }

  container_disk_in_gb = 20
  is_serverless        = true
}

Arguments

Argument	Type	Required	Description
`name`	string	Required	Template name.
`image_name`	string	Required	Docker image name.
`category`	string	Optional	`NVIDIA`, `AMD`, or `CPU`.
`container_disk_in_gb`	number	Optional	Container disk size in GB.
`container_registry_auth_id`	string	Optional	Registry auth ID for private images.
`docker_entrypoint`	list(string)	Optional	Docker entrypoint array.
`docker_start_cmd`	list(string)	Optional	Docker start command array.
`env`	map(string)	Optional	Environment variables as a key-value map.
`is_public`	bool	Optional	Make the template publicly visible.
`is_serverless`	bool	Optional	Mark template as serverless.
`ports`	list(string)	Optional	Ports array.
`volume_in_gb`	number	Optional	Volume size in GB.
`volume_mount_path`	string	Optional	Volume mount path.
`readme`	string	Optional	Template documentation.

Attributes (read-only)

Attribute	Description
`id`	Template ID.
`is_runpod`	Whether it’s an official Runpod template.
`earned`	Credits earned from template usage.
`runtime_in_min`	Runtime in minutes.

`runpod_endpoint`

Creates and manages a serverless endpoint. Endpoints auto-scale workers based on demand.

resource "runpod_endpoint" "my_endpoint" {
  template_id  = runpod_template.my_template.id
  name         = "my-llm-endpoint"
  workers_min  = 0
  workers_max  = 3
  idle_timeout = 5
  gpu_count    = 1

  env = {
    MODEL_NAME = "meta-llama/Llama-3.1-8B-Instruct"
  }
}

Arguments

Argument	Type	Required	Description
`template_id`	string	Required	Template ID for the endpoint.
`name`	string	Optional	Endpoint name.
`workers_min`	number	Optional	Minimum number of workers (0 = scale to zero).
`workers_max`	number	Optional	Maximum number of workers.
`idle_timeout`	number	Optional	Idle timeout in minutes before scaling down.
`gpu_count`	number	Optional	Number of GPUs per worker.
`compute_type`	string	Optional	`GPU` or `CPU`.
`network_volume_id`	string	Optional	Single network volume ID to attach.
`network_volume_ids`	list(string)	Optional	Multiple network volume IDs to attach.
`env`	map(string)	Optional	Environment variables as a key-value map.
`data_center_ids`	list(string)	Optional	Restrict workers to specific data center IDs.

Attributes (read-only)

Attribute	Description
`id`	Endpoint ID.
`created_at`	Creation timestamp.
`version`	Endpoint version.
`template_version`	Template version in use.
`users`	User IDs with access to this endpoint.
`workers`	List of active workers (id, pod_id, status, uptime_ms, start_time, last_busy_ms).

`runpod_machine`

Manages a machine listing. Primarily used by host providers to list machines and set pricing.

resource "runpod_machine" "my_machine" {
  gpu_type_id        = "NVIDIA GeForce RTX 4090"
  gpu_count          = 1
  secure_cloud       = true
  listed             = true
  host_price_per_gpu = 0.39
}

Arguments

Argument	Type	Required	Description
`gpu_type_id`	string	Required	GPU type ID.
`name`	string	Optional	Machine name.
`gpu_count`	number	Optional	Number of GPUs. Default: `1`.
`cpu_count`	number	Optional	Number of CPUs.
`memory_in_gb`	number	Optional	Memory in GB.
`disk_in_gb`	number	Optional	Disk size in GB.
`data_center_id`	string	Optional	Data center ID.
`location`	string	Optional	Location/country code.
`secure_cloud`	bool	Optional	Use Secure Cloud. Default: `false`.
`listed`	bool	Optional	List machine for others to use. Default: `true`.
`host_price_per_gpu`	number	Optional	Your host price per GPU.
`bid_price_per_gpu`	number	Optional	Bid price per GPU.

Attributes (read-only)

Attribute	Description
`id`	Machine ID.
`verified`	Whether the machine is verified.
`maintenance_mode`	Whether the machine is in maintenance mode.

Data sources

`runpod_gpu_types`

Lists all available GPU types with pricing information.

data "runpod_gpu_types" "available" {}

output "gpus" {
  value = data.runpod_gpu_types.available
}

Attributes

Attribute	Description
`id`	GPU type ID.
`display_name`	GPU display name (e.g. `NVIDIA GeForce RTX 4090`).
`manufacturer`	GPU manufacturer.
`memory_in_gb`	VRAM in GB.
`cuda_cores`	CUDA core count.
`secure_cloud`	Whether available in Secure Cloud.
`secure_price`	Secure Cloud price per hour.
`community_price`	Community Cloud price per hour.

`runpod_data_centers`

Lists all available data centers.

data "runpod_data_centers" "all" {}

Attributes

Attribute	Description
`id`	Data center ID (e.g. `US-TX-3`).
`name`	Data center name.
`location`	Geographic location.
`global_network`	Whether global network is enabled.

`runpod_pod`

Retrieves information about an existing pod by ID.

data "runpod_pod" "existing" {
  id = "abc123"
}

Arguments

Argument	Type	Required	Description
`id`	string	Required	Pod ID to look up.

`runpod_machine`

Retrieves information about a specific machine by ID.

data "runpod_machine" "host" {
  id = "machine-id"
}

Arguments

Argument	Type	Required	Description
`id`	string	Required	Machine ID to look up.

`runpod_machines`

Lists machines, optionally filtered by listed status.

data "runpod_machines" "listed" {
  listed = true
}

Arguments

Argument	Type	Required	Description
`listed`	bool	Optional	Filter by listed status.

`runpod_template`

Retrieves information about a template by ID.

data "runpod_template" "vllm" {
  id = "template-id"
}

Arguments

Argument	Type	Required	Description
`id`	string	Required	Template ID to look up.

`runpod_user`

Retrieves information about the authenticated user.

data "runpod_user" "me" {}

output "ssh_key" {
  value = data.runpod_user.me.pub_key
}

Complete example: serverless endpoint

This example creates a template and a serverless endpoint for a vLLM worker, then outputs the endpoint ID.

terraform {
  required_providers {
    runpod = {
      source  = "runpod/runpod"
      version = "~> 1.0"
    }
  }
}

provider "runpod" {
  api_key = var.runpod_api_key
}

variable "runpod_api_key" {
  type      = string
  sensitive = true
}

resource "runpod_template" "vllm" {
  name       = "llama-vllm"
  image_name = "runpod/worker-vllm:stable-cuda12.1.0"

  env = {
    MODEL_NAME      = "meta-llama/Llama-3.1-8B-Instruct"
    HF_TOKEN        = var.hf_token
    MAX_MODEL_LEN   = "8192"
  }

  container_disk_in_gb = 20
  is_serverless        = true
}

variable "hf_token" {
  type      = string
  sensitive = true
}

resource "runpod_endpoint" "llm" {
  template_id  = runpod_template.vllm.id
  name         = "llama-3-1-8b"
  workers_min  = 0
  workers_max  = 5
  idle_timeout = 5
  gpu_count    = 1
}

output "endpoint_id" {
  value       = runpod_endpoint.llm.id
  description = "Endpoint ID — use in API requests as /v2/{endpoint_id}/run"
}

Run it:

terraform apply \
  -var="runpod_api_key=$RUNPOD_API_KEY" \
  -var="hf_token=$HF_TOKEN"

​Prerequisites

​Install and configure

​Add the provider to your configuration

​Set your API key

​Initialize and apply

​Quick example: create a pod

​Resources

​runpod_pod

​runpod_pod_action

​runpod_template

​runpod_endpoint

​runpod_machine

​Data sources

​runpod_gpu_types

​runpod_data_centers

​runpod_pod

​runpod_machine

​runpod_machines

​runpod_template

​runpod_user

​Complete example: serverless endpoint

Prerequisites

Install and configure

Add the provider to your configuration

Set your API key

Initialize and apply

Quick example: create a pod

Resources

`runpod_pod`

`runpod_pod_action`

`runpod_template`

`runpod_endpoint`

`runpod_machine`

Data sources

`runpod_gpu_types`

`runpod_data_centers`

`runpod_pod`

`runpod_machine`

`runpod_machines`

`runpod_template`

`runpod_user`

Complete example: serverless endpoint