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

Give implementers and early testers enough detail to model supported StackShift resources and action flows safely.

​
Prerequisites

  • The StackShift provider configured in Terraform
  • Existing resource IDs when importing

​
Workflow

1
Choose the resource that matches the StackShift object you want Terraform to own.
2
Use normal terraform apply for new resources.
3
Use terraform import for existing resources, matching the import ID format for each resource.
4
Run terraform plan immediately after import to reconcile missing config or server-computed fields.
5
Avoid mixing Terraform-managed env sets with manual edits in the dashboard.

​
Resource ownership

  • stackshift_project owns project-level declarative fields such as name, runtime, region, port, source details, and command settings.
  • stackshift_project_env owns the entire variable map for one project and environment.
  • stackshift_database owns database creation and deletion. Most shape changes replace the resource.
  • stackshift_domain owns a project domain mapping.
  • stackshift_dns_record owns a DNS record on a registered StackShift-managed domain.
  • stackshift_build_action and stackshift_deployment_action own a single requested operation and its returned status.
  • stackshift_compute_instance owns VM/VPS provisioning. It is separate from normal StackShift-managed project placement.
  • stackshift_compute_action owns a single compute operation such as start, stop, restart, rebuild, or destroy.
  • stackshift_agency_client and stackshift_agency_resource_assignment own agency client records and assignments.
  • stackshift_runbook and stackshift_runbook_execution own runbook definitions and runbook execution requests.

​
Managed server projects

Projects deployed on StackShift managed servers do not need a node ID in Terraform. Use stackshift_project without node placement fields; StackShift keeps selecting the managed target on the server side. Only use explicit placement fields where a resource exposes them. For example, stackshift_database has optional target_node_id for explicit database placement, and leaving it unset keeps the managed/default path.

​
Import commands

terraform import stackshift_project.api <project_id>
terraform import stackshift_project_env.production <project_id>:production
terraform import stackshift_database.postgres <database_id>
terraform import stackshift_domain.api <project_id>:<domain_id>
terraform import stackshift_dns_record.www <domain_id>:<record_id>

​
Action resources

Action resources are intentionally explicit. Creating the resource requests the operation once and stores the returned action state. Deleting the Terraform resource only removes Terraform state for that action record.
Build and deployment actions
resource "stackshift_build_action" "api_build" {
  project_id = stackshift_project.api.id
  branch     = "main"
}

resource "stackshift_deployment_action" "api_redeploy" {
  project_id = stackshift_project.api.id
  action     = "redeploy"
  reason     = "roll forward after config change"
}
Runbook execution
resource "stackshift_runbook" "restart_api" {
  name        = "restart-api"
  description = "Restart API after a maintenance window"
  steps       = jsonencode([{ action = "restart", target = "api" }])
}

resource "stackshift_runbook_execution" "restart_api" {
  runbook_id = stackshift_runbook.restart_api.id
  reason     = "maintenance window complete"
}

​
Project source patterns

Projects can be created as empty projects, GitHub-backed projects, or image-backed projects. GitHub-backed projects need repository identity fields if you want StackShift to connect the source to an installed GitHub app.
GitHub-backed project
resource "stackshift_project" "api" {
  name    = "example-api"
  runtime = "node"
  region  = "us-east"
  port    = 3000

  github_repo_url        = "https://github.com/example/example-api"
  github_repo_id         = 123456789
  github_installation_id = 987654321
  github_branch          = "main"

  build_command = "npm run build"
  start_command = "npm start"
}
Docker image project
resource "stackshift_project" "worker" {
  name             = "example-worker"
  runtime          = "docker"
  region           = "us-east"
  source_type      = "docker_image"
  docker_image_uri = "ghcr.io/example/worker:latest"
}

​
Domain and DNS examples

Project domain mapping
resource "stackshift_domain" "api" {
  project_id       = stackshift_project.api.id
  domain           = "api.example.com"
  verify_on_create = true
}
Registered-domain DNS record
resource "stackshift_dns_record" "www" {
  domain_id = "registered-domain-uuid"
  type      = "CNAME"
  name      = "www"
  value     = "example.stackshift.cloud"
  ttl       = 3600
}

​
Delete behavior

  • Deleting stackshift_project calls DELETE /projects/{projectID}.
  • Deleting stackshift_project_env writes an empty variable set for that project environment.
  • Deleting stackshift_database calls DELETE /projects/{projectID}/databases/{databaseID}.
  • Deleting stackshift_domain removes the project domain mapping.
  • Deleting stackshift_dns_record removes the record from the registered domain DNS zone.

​
Expected result

The provider resources have clear ownership boundaries while registry publishing and full acceptance coverage are still pending.

​
Common failures

  • Importing stackshift_project_env without the environment suffix. Use <project_id>:<environment>.
  • Importing stackshift_domain with only the domain ID. Use <project_id>:<domain_id>.
  • Importing stackshift_dns_record with only the record ID. Use <domain_id>:<record_id>.
  • Treating action resources like reversible desired state. They trigger operations on create and do not roll those operations back on delete.
  • Expecting stackshift_bucket to exist in Terraform. It is intentionally unregistered until S3-compatible store endpoints ship.

Terraform and OpenTofu provider

Use the StackShift provider implementation to declare StackShift resources and run explicit StackShift actions from Terraform or OpenTofu.

DNS records and project connection

Manage DNS records and connect domains to projects or other runtime surfaces.

Credentials, pooling, and usage expectations

Understand how to consume database connection details and what to assume about pooling and access patterns.