Manage Runpod as code with Terraform provider 2.0

Terraform lets you describe infrastructure as code, preview the changes and apply them. Our provider connects Terraform to Runpod, so you can manage Runpod alongside your other clouds. You declare Pods, Serverless endpoints, templates, volumes, Instant Clusters and registry credentials in HCL and Terraform creates, updates and removes them to match.

Version 1.x mixed several backends, so attribute names varied and some attributes were accepted but ignored by the service. Provider 2.0, available since October, is generated from our REST v2 API, so every attribute maps to a documented v2 field. If you are on 1.x, read the migration section first: 2.0 is a breaking release, and the 1.x provider sends its REST requests to REST v1, which we are retiring.

Use Terraform when you want every change reviewed as a plan before anything bills and kept in version control. For an agent that operates Runpod interactively, the MCP server in Set up Runpod from any coding agent in one step is the faster path, and the same agent can still write the Terraform plan while you approve it.

Install and authenticate

Terraform 1.6 or later is required. The provider reads the api_key argument first, then falls back to the RUNPOD_API_KEY environment variable. The environment variable keeps the key out of your configuration files and state, so we recommend it. If you pass api_key instead, declare the variable with sensitive = true, supply the value at run time with TF_VAR_runpod_api_key, and never put it in a .tfvars file that you commit. In CI (continuous integration), store the key as a secret and expose it as RUNPOD_API_KEY, as shown in the CI section of the setup post. Declare the provider and pin the 2.x series:

terraform {  required_version = ">= 1.6"   required_providers {    runpod = {      source  = "runpod/runpod"      version = "~> 2.0"    }  }} provider "runpod" {}

Set the key in your shell, then download the provider:

export RUNPOD_API_KEY="<your key>"terraform init

Deploy your first Pod

Add this resource and these outputs to main.tf, below the provider block. It creates one GPU Pod running PyTorch and prints its ID and status.

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}

start_ssh needs an SSH key registered on your account, and start_jupyter needs 8888/http in ports. Run terraform plan, which should show one runpod_pod to add, then terraform apply.

Here is what a successful apply looks like.

terraform init, plan and apply create a Pod and print its ID and status. The recording used an NVIDIA RTX PRO 6000 Blackwell MIG, the GPU available at the time.

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

Let an agent write the plan

The provider includes a guide for running it from an AI agent. Point your agent at the guide and describe the infrastructure:

Read the Runpod Terraform agent guide. Write a plan for one podwith a volume, then run terraform plan and show me the output.

Review the plan yourself before you approve terraform apply, because apply creates billable resources. Keep RUNPOD_API_KEY in the environment the agent starts from, so the key never appears in the prompt or the plan.

Migrating from 1.x

Provider 2.0.0 ships no state upgraders, so a 1.x state entry whose attributes changed can’t be decoded. Every resource needs a configuration edit and a state action before it plans cleanly. In this guide, 1.x means 1.0.8, the last 1.x release that worked end to end.

• Pin the new version with version = "~> 2.0" and run terraform init -upgrade.
• Record your resource ids with terraform state list and terraform show -json while the 1.x provider is still in the lock file.
• Rewrite the configuration resource by resource, using the mapping tables in the migration guide. Three resource types changed name: runpod_endpoint is now runpod_serverless_endpoint, runpod_container_registry_auth is now runpod_registry, and runpod_ecr_delegation is now runpod_registry_delegation. Remove any base_url setting, because in 2.0 it points at the REST v2 host, not REST v1.
• Remove and re-import each affected resource. Registry credentials and delegations can’t be imported: remove the old address and let Terraform create the new resource, which gets a new id, so update every registry reference on Pods and endpoints.
• Run terraform plan and read every planned replacement before you apply. A Pod you want to keep can be replaced after an import, because the v2 Pod read does not return eight create-time attributes. Replacement deletes the Pod permanently, along with anything not on a network volume. Either leave a running 1.x Pod on 1.x until you recreate it, or adopt it with ignore_changes before the first apply. The migration guide shows both.

The migration guide maps every 1.x attribute to its 2.0.0 equivalent and gives the REST v1 retirement date. Provider 2.0 makes no REST v1 calls, so the retirement doesn’t affect it.

Next steps

New to the provider? Follow the Terraform quickstart.

Curious how the MCP server and skills keep agents accurate? Read How Runpod’s agent skills and MCP server work together.

Want everything else we shipped this month? Read From setup to deployment: what’s new in Runpod for Agents.