Provider resources and imports

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

Choose the resource that matches the StackShift object you want Terraform to own.

Use normal terraform apply for new resources.

Use terraform import for existing resources, matching the import ID format for each resource.

Run terraform plan immediately after import to reconcile missing config or server-computed fields.

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_bucket owns an S2 bucket, its initial access key state, and the choice to reject or allow destruction while non-empty.
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_byoc_provider_connection owns one scoped or federated cloud identity and validates it during apply.
stackshift_byoc_node owns durable provider provisioning and provider-confirmed safe deletion.
stackshift_byoc_volume, stackshift_byoc_snapshot, and stackshift_byoc_static_ip own node-scoped provider add-ons.
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.
stackshift_workload_external_dependency declares one exact external hostname, port, protocol, purpose, and TLS requirement.
stackshift_workload_egress_grant requests scoped, expiring access; it cannot approve its own request.

Hosted workload security resources

Use stackshift_workload_external_dependency to declare an exact non-web service before deployment. Use stackshift_workload_egress_grant to request the matching destination and expiry. An authorized StackShift operator still approves or rejects the request outside Terraform. These records are durable security evidence. Removing either resource from configuration removes it from Terraform state but does not revoke or delete the server-side declaration or request.

resource "stackshift_workload_external_dependency" "postgres" {
  project_id   = stackshift_project.api.id
  environment  = "production"
  hostname     = "ep-example.eu-central-1.aws.neon.tech"
  port         = 5432
  protocol     = "tls"
  purpose      = "Primary PostgreSQL database"
  tls_required = true
}

S2 bucket resources

Protect Terraform state because stackshift_bucket stores the one-time S3 secret returned during creation. Import by bucket UUID reads bucket configuration but cannot reconstruct a secret that S2 no longer returns.

Import a bucket with terraform import stackshift_bucket.uploads <bucket_id>.
Name, region, visibility, project, and initial key label changes replace the bucket.
Destroy rejects a non-empty bucket unless force_destroy is explicitly true.

resource "stackshift_bucket" "uploads" {
  name             = "example-customer-uploads"
  region           = "global"
  visibility       = "private"
  access_key_label = "terraform-production"
  force_destroy    = false
}

BYOCloud resources

Hetzner and DigitalOcean connections accept only scoped tokens. AWS accepts role_arn and region and returns a server-generated external_id for the trust policy. Azure accepts tenant, subscription, and client IDs for workload federation; AWS access keys and Azure client secrets have no Terraform attributes. Protect Terraform state because provider token inputs are sensitive state values. Node and add-on resources derive idempotency keys from immutable resource identity, persist them, and wait for provider-confirmed terminal state. A structured deletion blocker stops terraform destroy instead of orphaning dependencies.

Import provider connections and nodes with their UUID.
Import volumes and snapshots with NODE_ID:RESOURCE_ID.
Import a stable IP resource with its node UUID.
Imported provider connections can be read without credentials, but credentials must be supplied before changing or revalidating them.

BYOCloud node and storage

resource "stackshift_byoc_provider_connection" "hetzner" {
  provider     = "hetzner"
  display_name = "Production Hetzner project"
  token        = var.hetzner_token
}

resource "stackshift_byoc_node" "app" {
  provider_connection_id = stackshift_byoc_provider_connection.hetzner.id
  provider                = "hetzner"
  region                  = "fsn1"
  tier_slug               = "growth"
  name                    = "production-app-1"
}

resource "stackshift_byoc_volume" "data" {
  node_id    = stackshift_byoc_node.app.id
  name       = "production-app-data"
  size_gb    = 80
  mount_path = "/var/lib/stackshift-data"
  filesystem = "ext4"
}

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_bucket.uploads <bucket_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@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

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_bucket calls DELETE /buckets/{bucketID}; force_destroy = true adds explicit recursive object deletion.
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.
Importing stackshift_bucket and expecting Terraform to recover the existing secret access key. Issue a new key when imported infrastructure needs credentials.
Treating a workload dependency or egress request as self-approved network access. Security approval remains an operator action.
Removing a workload security resource from Terraform and expecting the durable request to be revoked. Delete removes Terraform state only.

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

Use stable connection details, TLS, public-access policy, and pooler endpoints without relying on physical runtime addresses.

​Goal

​Prerequisites

​Workflow

​Resource ownership

​Hosted workload security resources

​S2 bucket resources

​BYOCloud resources

​Managed server projects

​Import commands

​Action resources

​Project source patterns

​Domain and DNS examples

​Delete behavior

​Expected result

​Common failures

​Related guides

Terraform and OpenTofu provider

DNS records and project connection

Credentials, pooling, and usage expectations

Goal

Prerequisites

Workflow

Resource ownership

Hosted workload security resources

S2 bucket resources

BYOCloud resources

Managed server projects

Import commands

Action resources

Project source patterns

Domain and DNS examples

Delete behavior

Expected result

Common failures

Related guides