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

Manage the bucket lifecycle declaratively without exposing credentials or accidentally deleting stored objects.

​
Prerequisites

  • The StackShift Terraform provider installed
  • Encrypted Terraform state with restricted access
  • A StackShift API token configured for the provider

​
Workflow

1
Declare stackshift_bucket with a stable name and signing region.
2
Keep force_destroy false for production unless object deletion is explicitly intended.
3
Select encryption_mode; use sse-kms when the bucket requires platform-managed KMS envelope encryption.
4
Apply once and move the sensitive secret output into the workload secret manager.
5
Use the computed endpoint and access key ID when configuring the S3 client.
6
Import existing buckets by control-plane UUID when Terraform did not create them.

​
Bucket resource

​
Lifecycle behavior

  • name, region, visibility, project_id, and access_key_label replace the bucket when changed.
  • force_destroy is a Terraform-side deletion choice and can change without replacing the bucket.
  • versioning_enabled, quotas, retention, tiering, website settings, encryption_mode, and custom_domain_id update in place.
  • kms_key_id is computed. For sse-kms, StackShift returns the platform-managed key identifier after the settings update.
  • If platform KMS is unavailable, enabling sse-kms fails closed instead of silently falling back to another mode.
  • Destroy refuses a non-empty bucket by default. Enabling force destroy asks S2 to remove contained objects before deleting the bucket.
  • Read refreshes object count, size, endpoint, and timestamps without trying to read the one-time secret again.

​
Import

Run terraform plan after import and supply the bucket configuration in HCL. Imported state cannot contain a secret the API no longer returns.

​
Expected result

Terraform owns the bucket configuration and deletion policy while secret material remains protected as sensitive state.

​
Common failures

  • Publishing state files or plan artifacts. Sensitive values are redacted in normal output but still exist in state.
  • Expecting import to recover an existing secret access key. Create a new bucket key after import when credentials are needed.
  • Changing name, region, visibility, project, or initial key label without reviewing the planned replacement.
  • Supplying AWS credentials or a KMS ARN. Terraform selects sse-kms; StackShift owns and returns the platform key identifier.
  • Setting force_destroy = true without accepting that destroy will remove every object in the bucket.

Terraform and OpenTofu provider

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

Provider resources and imports

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

Access keys, encryption, isolation, and quotas

Operate S2 credentials, encryption, visibility, tenant isolation, request limits, and customer-plan quotas safely.