Manage Runpod infrastructure with Terraform

The Runpod Terraform provider lets you manage Runpod infrastructure as code. You declare Pods, Serverless endpoints, templates, network and global volumes, Instant Clusters, and registry credentials in HCL files, and Terraform creates, updates, and removes them to match. This page covers the 2.0.0 provider. If you already manage Runpod resources with a 1.x version of the provider, read Migrate the Runpod Terraform provider from 1.x to 2.0.0 before you upgrade, because 2.0.0 is a breaking release.

Requirements

Terraform 1.6 or later.
A Runpod account with a Runpod API key.

Install the provider

Create a directory for your configuration and add a main.tf file that declares the Runpod provider:

main.tf

terraform {
  required_version = ">= 1.6"

  required_providers {
    runpod = {
      source  = "runpod/runpod"
      version = "~> 2.0"
    }
  }
}

provider "runpod" {}

~> 2.0 installs 2.0.0 and any later 2.x release, and blocks an automatic move to 3.0. Download the provider into your working directory:

terraform init

Terraform records the selected provider version in .terraform.lock.hcl. Commit that file so everyone on your team uses the same version. To move to a newer release within your constraint, run terraform init -upgrade.

Authenticate

The provider needs a Runpod API key. It reads the key from the api_key argument first, then falls back to the RUNPOD_API_KEY environment variable. If neither is set, Terraform stops with an error when it configures the provider.

Use an environment variable

Setting the key as an environment variable keeps it out of your configuration files and state. This is the recommended method:

export RUNPOD_API_KEY="YOUR_API_KEY"

With the variable set, leave the provider block empty: provider "runpod" {}.

Use a provider argument

To pass the key through Terraform instead, declare a sensitive variable and reference it in the provider block:

main.tf

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

provider "runpod" {
  api_key = var.runpod_api_key
}

Supply the value at run time, for example with terraform apply -var="runpod_api_key=YOUR_API_KEY" or a TF_VAR_runpod_api_key environment variable. Never commit the key to a .tfvars file in version control.

The provider sends requests to the production Runpod API by default. To target a different host, set the base_url argument or the RUNPOD_API_BASE_URL environment variable. Most users never need this setting. The deprecated GraphQL shims use a separate graphql_url setting. See Which Runpod APIs the provider uses.

Deploy a Pod

This example creates a single GPU Pod running PyTorch and outputs its ID and status.

Add the Pod to your configuration

Add the following resource and outputs to main.tf, below the provider block:

main.tf

resource "runpod_pod" "example" {
  name        = "terraform-example"
  image       = "runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04"
  gpu_type_id = "NVIDIA GeForce RTX 4090"
  gpu_count   = 1
  cloud       = "SECURE"
  disk        = 20
  ports       = ["8888/http", "22/tcp"]

  start_ssh     = true
  start_jupyter = true
}

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

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

name, image, and a GPU or CPU type are the minimum a Pod needs. ports is a list of PORT/PROTOCOL strings. start_jupyter starts JupyterLab and generates a password, and needs 8888/http in ports. start_ssh needs an SSH key registered on your account. To set environment variables, add an env map.

Review the plan

Preview what Terraform will create:

terraform plan

The plan should show one runpod_pod to add and nothing to change or destroy.

Apply the configuration

Create the Pod:

terraform apply

Type yes when prompted. When the apply finishes, Terraform prints the pod_id and pod_status outputs. The Pod also appears on the Pods page of the Runpod console.

Clean up

When you’re done, remove the Pod so it stops billing:

terraform destroy

A running Pod bills for every minute it exists, whether or not you use it. Run terraform destroy when you finish testing, or set desired_state = "EXITED" on the Pod to stop it while keeping it in your configuration.

What the provider manages

The 2.0.0 provider covers these resources:

Pods, including CPU Pods, with runpod_pod, and one-off Pod actions such as a restart with runpod_pod_action.
Serverless endpoints with runpod_serverless_endpoint.
Templates with runpod_template.
Network volumes with runpod_network_volume.
Global volumes with runpod_global_volume.
Container registry credentials and Amazon ECR delegations with runpod_registry and runpod_registry_delegation.
Instant Clusters with runpod_cluster.
Account SSH keys with runpod_account_ssh_keys.
Host machines with runpod_machine. This is a deprecated GraphQL shim for Runpod hosts and needs a host account.

Data sources read the GPU, CPU, and data center catalogs, existing Pods, templates, Serverless endpoints, network and global volumes, endpoint workers, builds, releases, logs, and billing. For every argument and attribute, see the provider reference on the Terraform Registry. The reference is generated from the provider schema, so it always matches the release you install.

Which Runpod APIs the provider uses

The 2.0.0 provider is generated from the Runpod REST API v2, and nearly every resource and data source talks only to https://api.runpod.io/v2. A few deprecated resources, data sources, and attributes still call the GraphQL API because REST v2 has no route for them yet:

The runpod_machine resource, the runpod_machine and runpod_machines data sources, and the runpod_user data source.
A few deprecated attributes on runpod_pod, runpod_template, and runpod_serverless_endpoint, such as machine_id on Pods and readme on templates.
Parts of the three 1.x billing data sources (runpod_billing_pod, runpod_billing_network_volume, and runpod_billing_endpoint), which otherwise read the v2 billing routes.

Terraform prints a warning on every plan that touches one, and each is removed once REST v2 adds the matching route. Use the v2 billing data sources (runpod_pod_billing, runpod_serverless_billing, and runpod_network_volume_billing) for new configuration. The provider makes no REST API v1 calls, so the REST v1 retirement on November 15, 2026 doesn’t affect it. The graphql_url argument (fallback RUNPOD_GRAPHQL_URL) applies only to the GraphQL shims. Leave it unset unless you target a non-production environment. The rest_v1_url argument from the 2.0.0 release candidates is deprecated and ignored. The registries[].username field on runpod_registries is deprecated and always null.

Next steps

Migrate from the 1.x provider if you have existing 1.x configuration and state.
Browse the provider reference for every resource and data source.
Learn about Pod configuration options that map to runpod_pod arguments.
Deploy a Serverless endpoint and manage it with runpod_serverless_endpoint.

Get started

Runpod SDK (Beta)

Flash

Serverless

Pods

Storage

Public Endpoints

Instant Clusters

Accounts and billing

Organizations (Beta)

Integrations

Hub

Reference

Manage Runpod infrastructure with Terraform

Requirements

Install the provider

Authenticate

Use an environment variable

Use a provider argument

Deploy a Pod

What the provider manages

Which Runpod APIs the provider uses

Next steps

​Requirements

​Install the provider

​Authenticate

​Use an environment variable

​Use a provider argument

​Deploy a Pod

​What the provider manages

​Which Runpod APIs the provider uses

​Next steps

Requirements

Install the provider

Authenticate

Use an environment variable

Use a provider argument

Deploy a Pod

What the provider manages

Which Runpod APIs the provider uses

Next steps