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

# Provider resources and imports

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

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## 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

<Steps>
  <Step>
    Choose the resource that matches the StackShift object you want Terraform to own.
  </Step>

  <Step>
    Use normal terraform apply for new resources.
  </Step>

  <Step>
    Use terraform import for existing resources, matching the import ID format for each resource.
  </Step>

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

  <Step>
    Avoid mixing Terraform-managed env sets with manual edits in the dashboard.
  </Step>
</Steps>

## 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

```bash theme={null}
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.

```hcl Build and deployment actions theme={null}
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"
}
```

```hcl Runbook execution theme={null}
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.

```hcl GitHub-backed project theme={null}
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"
}
```

```hcl Docker image project theme={null}
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

```hcl Project domain mapping theme={null}
resource "stackshift_domain" "api" {
  project_id       = stackshift_project.api.id
  domain           = "api.example.com"
  verify_on_create = true
}
```

```hcl Registered-domain DNS record theme={null}
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

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

## Common failures

<Warning>
  * 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.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Terraform and OpenTofu provider" href="/infrastructure-as-code/terraform-provider">
    Use the StackShift provider implementation to declare StackShift resources and run explicit StackShift actions from Terraform or OpenTofu.
  </Card>

  <Card title="DNS records and project connection" href="/domains-and-email/dns-records-and-project-connection">
    Manage DNS records and connect domains to projects or other runtime surfaces.
  </Card>

  <Card title="Credentials, pooling, and usage expectations" href="/databases/credentials-pooling-and-usage">
    Understand how to consume database connection details and what to assume about pooling and access patterns.
  </Card>
</CardGroup>