Vast.ai Terraform provider
Categories:
Languages:
Statuses:
This project implements a Terraform Plugin Framework provider for the
Vast.ai REST API.
The provider type is vastai; the source address is
registry.terraform.io/alwaldend/vastai. This is a development provider;
no Terraform Registry release is published by this project setup.
The shared API client is generated offline from the official OpenAPI 3.1 schema, pinned by commit and SHA-256. The repository’s pinned OpenAPI Generator produces Go source directly into Bazel outputs. The adapter retains endpoint validation and a few operations omitted from the schema.
Coverage
vastai_offerssearches GPU offers using a JSON object query and returnsoffersin API order:id,gpu_name,num_gpus,gpu_ram_mb, andhourly_price. An empty search produces an empty list.vastai_templatereads exactly one template byhash_id, returning its resolvedimageandenvironment_onlyclassification. Only literal Docker environment assignments qualify; port mappings, unknown flags, and malformed quoting do not. Template environment values are not stored in Terraform state. Application code and provisioning scripts still require operator review.vastai_instancerents an offer withoffer_id, Dockerimage, and positivedisk_gb. Optional creation settings areruntype(defaultssh), sensitiveonstart(default empty), andtemplate_hash_id(default empty). A template hash selects inherited defaults; explicit image, launch, and startup settings override scalars, while template environment and port options remain inherited. Usevastai_templateto inspect them first. Supported launch modes aressh,ssh_proxy,ssh_direct,jupyter,jupyter_proxy, andjupyter_direct. Changing creation settings replaces the instance. Refresh normalizes compound API modes and retains a compatible configured value; imports select a supported mode. Missing or unsupported modes produce a read error and retain state.compress_onstart(default false) enables gzip transport for compatible images providing/bin/bash,base64,gzip,mktempandrm. The provider compresses the complete script when that reduces its size and enforces Vast’s 16,384-byte startup command limit before creation. The decoded script runs from a private temporary file that is removed on exit. Terraform retains the original sensitive script, and refresh recognizes its encoded API representation without drift. Changing this creation setting replaces the instance. Oversized commands fail without a rental request or disclosure of script content.label(default empty) andstate(runningorstopped, defaultrunning) update in place. Refresh reads drift, observedactual_status,ssh_host,ssh_port, andpublic_ip. Destroy terminates the contract; HTTP 404 during refresh or deletion, or an explicitinstances: nullin a successful refresh response, means it is already absent. Missing instance objects, invalid image/disk/launch metadata, mismatched IDs, and API failures remain errors and preserve state.
Apply acknowledges the rental or update request. It does not wait for boot,
power-state convergence, or SSH readiness. Connection fields are initially
null; use terraform apply -refresh-only to observe them after provisioning.
Offers can disappear between plan and apply. Stopped instances continue to
incur storage charges. Spot bids, template management, volumes, and
membership management are outside the supported surface.
Non-compute resources
vastai_ssh_key: requiredpublic_key, computed numeric-stringid. Updates change public material in place; import uses the key ID. The provider never generates or stores private keys. Vast.ai may propagate registered keys to existing instances in the account. SSH keys require personal account context; Vast.ai rejects them in teams.vastai_environment_variable: required uppercasenameand sensitivevalue;idequals the name. Values update in place; changing the name requires replacement. Import uses the uppercase name. Values remain in state, so use a secure backend. Masked API reads preserve the stored value and cannot detect external value changes. After importing a masked variable, configure its value for the next apply.vastai_team_role: requirednameand requested JSON-objectpermissions, computedid(role name), numericrole_id, andeffective_permissionsincluding Vast.ai’s baseline grants. Permissions update in place; changing the name requires replacement. Import uses the role name. The resource does not assign or invite members. Names containing a forward slash are retained as one encoded API path segment. Refresh compares effective permissions with their previous observed value to detect drift while preserving configured permission categories. Imported roles may require an apply to establish that configured representation.
vastai_team creates a separate team with zero credit transfer and generates
an independent management key in sensitive state. vastai_api_key generates
a project key using its configured provider, name, and JSON permissions;
its computed key is sensitive. Key name, permission, and team-binding changes
require replacement. Optional team_api_key is reserved for a management key
generated during the same bootstrap apply. Ordinary resources omit it. Removing
that override verifies key visibility through the provider and updates only
state metadata, preserving the generated key ID and value. A new explicit
bootstrap issuer retains replacement behavior because it can select another team.
An empty permission string omits the permission field and requests default
full access; {} is not equivalent. Optional team_id resolves an existing
owned team’s owner context, retains the new key in state, and attempts binding
only on that generated key. It requires empty permissions for explicit full
access and rejects scoped input before key creation. Computed bindings may require
read-only team refresh before validation. The issuer is never switched. Binding failure
fails apply before downstream Vault storage and leaves the key recoverable by
destruction. Offline fixtures verify this behavior; the live alwaldend attempt
created a key but received HTTP 400 from context selection, so that binding
has not passed live acceptance. The failed key was revoked through its root.
Their generated credentials cannot be recovered through import. API-key
imports remain unsupported. Use a secure backend and pass generated keys
directly to your secret manager rather than Terraform outputs.
An existing owned team can be imported by numeric account ID. Import and
refresh read the personal account’s owner-context metadata without generating
keys or changing credential context. Imported teams have null api_key and
management_key_id; project keys can instead use the configured provider and
the imported team ID.
Their destruction is refused while they remain in state; use prevent_destroy
in their configuration and an explicit state-removal workflow to detach them.
Confirmed external absence removes an imported identity without key cleanup.
Import failures and refresh errors preserve account resources.
terraform import vastai_team.existing 846045
Team deletion requires a private record of confirmed creation and uses the captured account ID. Failed creation never adopts an existing team with the same name. If a team is deleted externally, refresh retains its management key and plans replacement; apply revokes that key before creating another team. Failed key revocation retains state for an explicit retry.
The account root owns team creation and account defaults. The separate alwaldend root uses its operator-provided team key as provider authentication and creates full-access project keys directly in that context. Rentals use an independent root and state.
The former isolated live test root and test team are retired. Its test key, environment marker and role were destroyed through their original state before revoking the team’s credential. Offline Terraform CLI acceptance fixtures continue to exercise non-compute resources, team bootstrap and cleanup.
Build and develop
bazel build //projects/vastai_terraform_provider
Use a private Terraform CLI configuration with a development override pointing
at the directory containing the built terraform-provider-vastai executable:
provider_installation {
dev_overrides {
"registry.terraform.io/alwaldend/vastai" = "/absolute/path/to/provider/directory"
}
direct {}
}
Set TF_CLI_CONFIG_FILE to that private file. With a development override,
run terraform validate, plan, and apply directly; terraform init would
attempt Registry resolution for this unreleased provider. In configurations
with other providers, initialize those separately as Terraform requires.
The provider uses protocol 6 and requires Terraform 1.0 or newer.
Inject the API credential as VAST_API_KEY from your secret manager. The
optional sensitive provider attribute api_key overrides it; avoid literal
credentials in configuration. endpoint defaults to
https://console.vast.ai/api/v0. Custom endpoints require HTTPS, except
literal loopback HTTP for fixture testing. Requests have a 60-second timeout
and an 8 MiB response limit, reject redirects, and do not retry mutations.
Inspect the account after an ambiguous creation failure before retrying.
Sensitive attributes are hidden from normal CLI display but remain in state. Secure Terraform state and saved plans. API response bodies and returned instance credentials are never copied into diagnostics or persisted state.
terraform {
required_providers {
vastai = { source = "alwaldend/vastai" }
}
}
provider "vastai" {}
resource "vastai_instance" "worker" {
offer_id = 123456 # Select a currently available on-demand offer.
image = "ubuntu:24.04"
disk_gb = 20
label = "terraform-worker"
}
The checked-in example separates offer discovery from explicit offer selection so refreshing volatile search results does not replace an existing rental.
Import
terraform import vastai_instance.worker 12345678
Import accepts a canonical positive decimal contract ID. The API does not
return the original offer ID. Before applying imported resources, supply a
placeholder positive offer_id and add
lifecycle { ignore_changes = [offer_id] }. Reconcile image, disk_gb,
runtype, onstart, label, and state with the imported state. Review the
plan carefully; creation-only differences require replacement. When replacing
an imported instance deliberately, remove the ignore rule and select a valid
current offer first.
Validation and ownership
bazel test //projects/vastai_terraform_provider/test/acceptance:acceptance_test
The acceptance suite runs the repository-pinned Terraform CLI and built
provider against a loopback fixture. It exercises the full lifecycle,
replacement plans, import, drift, remote disappearance, failure diagnostics,
and credential-safe redirect handling. lifecycle.json in test undeclared
outputs records the observed non-sensitive API operations. It requires no
Vast.ai account, network access outside loopback, or paid instances; live
compute compatibility remains unverified.
The configured image-generation case packages every public model profile
through its real module and compressed startup transport. It compares staged
workflow contents and model destinations and enforces the 16 KiB API limit,
emitting one configured-imagegen-startup-<profile>.json artifact per profile.
It downloads no weights and establishes no model inference or image quality.
On 2026-11-04, the authorized live deployment applied the project AppRole, team/token bootstrap, and the three-resource team test root. Both Vast.ai Terraform roots then produced no-change plans using their own credentials. No compute was rented or credit transferred; the personal bootstrap context remained unchanged.
cmd/terraform-provider-vastai owns plugin startup. internal/provider owns
provider configuration and registration; internal/resources owns resource
schemas, plans, state, and imports; internal/datasources owns offer queries.
internal/providerdata defines the shared Data payload and checks it during
resource and data-source configuration. The shared internal/vastai_sdk owns generated endpoint operations,
bounded transport, and API response contracts.
openspec contains the maintained implementation record.
Instance networking options
vastai_instance.docker_options supplies creation-only Docker environment and
port options, merged with the selected template. It is sensitive in normal
Terraform output but retained in state; changes replace the instance. The
provider never reads API-returned environment contents. Computed mapped_ports
returns observed host ports keyed by container port/protocol, such as 7860/tcp.
Connection details remain null before refresh; ambiguous or invalid bindings
fail refresh while retaining prior state.