Skip to main content
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

1
Build or install the StackShift provider binary.
2
Configure Terraform to load the provider, using a local dev override until registry publishing is available.
3
Export STACKSHIFT_API_TOKEN or set api_token in provider configuration.
4
Declare StackShift resources in HCL.
5
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.
Build the provider
cd /Users/jessejosiah/Startup/terraform-provider-stackshift
go build -o terraform-provider-stackshift
~/.terraformrc
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. Use STACKSHIFT_ENDPOINT or endpoint when targeting staging or local development.
Provider block
terraform {
  required_providers {
    stackshift = {
      source = "stackshiftCloud/stackshift"
    }
  }
}

provider "stackshift" {
  endpoint  = "https://api.stackshift.cloud"
  api_token = var.stackshift_api_token
}
Environment variables
export STACKSHIFT_API_TOKEN="sspat_..."
export STACKSHIFT_ENDPOINT="https://dev-api.stackshift.cloud"

​
Minimal project example

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. 
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.
  • 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.

Provider resources and imports

Implementation reference for StackShift provider resources, import IDs, action semantics, and caveats.

Deploy a Docker image

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.

Project environment, domains, and previews

Configure the project surfaces that most often decide whether a deployment works after it builds, including runtime shape, domains, previews, and storage.

Create a database

Provision a managed database and understand the minimum runtime and recovery expectations around it.