> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Terraform and OpenTofu provider
> Use the StackShift provider implementation to declare StackShift resources and run explicit StackShift actions from Terraform or OpenTofu.
**Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
## Goal
Understand the implemented provider surface while registry publishing and broader acceptance coverage are still pending.
## Prerequisites
* Terraform or OpenTofu installed locally or in CI
* A StackShift API token with the sspat\_ prefix
* Access to the StackShift API endpoint you want to manage
## Workflow
Build or install the StackShift provider binary.
Configure Terraform to load the provider, using a local dev override until registry publishing is available.
Export STACKSHIFT\_API\_TOKEN or set api\_token in provider configuration.
Declare StackShift resources in HCL.
Run terraform plan, terraform apply, terraform destroy, or terraform import as needed.
## What the provider is
The provider is being implemented as a Terraform plugin that runs on the user machine or CI runner. It teaches Terraform how to talk to StackShift. It does not execute Terraform remotely, store Terraform state, or replace Terraform Cloud.
The provider maps resources to existing StackShift REST endpoints. It sends Authorization: Bearer requests, decodes the standard API envelope, and maps 404 responses into Terraform drift handling.
## Implemented operations resources
Builds, deployment actions, runbooks, agency client assignments, and compute/VM operations are implemented as explicit provider resources instead of being hidden inside unrelated project diffs.
Action resources trigger work when Terraform creates the resource. Removing one from Terraform removes it from state, but does not undo the operational action that already ran.
* stackshift\_build\_action triggers a project build.
* stackshift\_deployment\_action triggers deployment-style actions such as redeploys and rollbacks.
* stackshift\_runbook and stackshift\_runbook\_execution manage runbook definitions and executions.
* stackshift\_agency\_client and stackshift\_agency\_resource\_assignment manage agency clients and resource assignments.
* stackshift\_compute\_instance and stackshift\_compute\_action manage VM/VPS provisioning and compute actions.
## Managed placement and node IDs
Normal StackShift-managed app projects do not require an explicit node ID. The stackshift\_project resource intentionally omits node placement, so StackShift keeps choosing managed placement through the API.
target\_node\_id is optional only where explicit placement is exposed, such as stackshift\_database. stackshift\_compute\_instance is a separate VM/VPS resource, not the node selector for a managed project deployment.
## Supported resources
* stackshift\_project manages projects through /api/v1/projects.
* stackshift\_project\_env owns the full env-var set for one project environment through /api/v1/projects/\{projectID}/env.
* stackshift\_database manages project databases through /api/v1/projects/\{projectID}/databases and reads through /api/v1/databases/\{databaseID}.
* stackshift\_domain maps project domains through /api/v1/projects/\{projectID}/domains.
* stackshift\_dns\_record manages registered-domain DNS records through /api/v1/domains/\{domainID}/dns.
* stackshift\_build\_action and stackshift\_deployment\_action trigger build and deployment operations.
* stackshift\_compute\_instance and stackshift\_compute\_action manage VM/VPS resources and actions.
* stackshift\_agency\_client and stackshift\_agency\_resource\_assignment manage agency client resources.
* stackshift\_runbook and stackshift\_runbook\_execution manage operational runbooks.
## Local install
Until the provider is published to a registry, install it with Terraform dev overrides. The override points Terraform at the local provider build directory.
```bash Build the provider theme={null}
cd /Users/jessejosiah/Startup/terraform-provider-stackshift
go build -o terraform-provider-stackshift
```
```hcl ~/.terraformrc theme={null}
provider_installation {
dev_overrides {
"registry.terraform.io/stackshiftCloud/stackshift" = "/Users/jessejosiah/Startup/terraform-provider-stackshift"
}
direct {}
}
```
## Provider configuration
The provider defaults to [https://api.stackshift.cloud](https://api.stackshift.cloud). Use STACKSHIFT\_ENDPOINT or endpoint when targeting staging or local development.
```hcl Provider block theme={null}
terraform {
required_providers {
stackshift = {
source = "stackshiftCloud/stackshift"
}
}
}
provider "stackshift" {
endpoint = "https://api.stackshift.cloud"
api_token = var.stackshift_api_token
}
```
```bash Environment variables theme={null}
export STACKSHIFT_API_TOKEN="sspat_..."
export STACKSHIFT_ENDPOINT="https://dev-api.stackshift.cloud"
```
## Minimal project example
```hcl theme={null}
resource "stackshift_project" "api" {
name = "example-api"
runtime = "node"
region = "us-east"
port = 3000
}
resource "stackshift_project_env" "production" {
project_id = stackshift_project.api.id
environment = "production"
variables = {
NODE_ENV = "production"
API_KEY = var.api_key
}
}
```
## Databases and credentials
The database resource does not expose passwords in resource state. Use the credentials data source when wiring a database into project env vars.
```hcl theme={null}
resource "stackshift_database" "postgres" {
project_id = stackshift_project.api.id
name = "example-postgres"
type = "postgres"
version = "16"
size_gb = 10
}
data "stackshift_database_credentials" "postgres" {
database_id = stackshift_database.postgres.id
}
resource "stackshift_project_env" "production" {
project_id = stackshift_project.api.id
variables = {
DATABASE_URL = data.stackshift_database_credentials.postgres.connection_string
}
}
```
## Token scopes
Current StackShift API tokens store arbitrary scopes and default to \* when no scopes are supplied. Until finer-grained provider scopes exist, use a full-access token for Terraform automation.
## Expected result
You can model the supported declarative resources and explicit action flows without treating pending registry release work as done.
## Common failures
* Missing STACKSHIFT\_API\_TOKEN or api\_token provider setting.
* Using the frontend URL instead of the API URL. The production endpoint is [https://api.stackshift.cloud](https://api.stackshift.cloud).
* Expecting a node ID for normal StackShift-managed project deployments. Managed app projects omit node placement.
* Trying to manage one env var at a time. The current env resource owns the whole environment variable set for a project environment.
* Changing database size, type, version, project, or target node and expecting an in-place update. The current API exposes no resize/update endpoint, so Terraform replaces the resource.
## Related guides
Implementation reference for StackShift provider resources, import IDs, action semantics, and caveats.
Run a raw container image through the project flow when you already have an image and need runtime configuration, resource sizing, storage, domains, and placement.
Configure the project surfaces that most often decide whether a deployment works after it builds, including runtime shape, domains, previews, and storage.
Provision a managed database and understand the minimum runtime and recovery expectations around it.