Terraform Provider

Use the Terraform provider to manage control plane resources.

Provider source: s2-streamstore/s2
GitHub: s2-streamstore/terraform-provider-s2
Registry: registry.terraform.io/providers/s2-streamstore/s2

The provider supports:

Resources
- s2_basin
- s2_stream
- s2_access_token
Data sources
- s2_basin
- s2_stream

resource blocks are managed by Terraform (create/update/delete).
data blocks are read-only lookups for existing resources.

Prerequisites

Terraform >= 1.5.0
An S2 access token (S2_ACCESS_TOKEN)

Quickstart

Set your credentials

export S2_ACCESS_TOKEN="<your access token>"
# Optional (for self-hosted or s2-lite):
# export S2_ACCOUNT_ENDPOINT="a.s2.dev"

Create a Terraform config

terraform {
  required_providers {
    s2 = {
      source  = "s2-streamstore/s2"
      version = "~> 0.2"
    }
  }
}

provider "s2" {}

resource "s2_basin" "main" {
  name = "my-example-basin"
}

resource "s2_stream" "events" {
  basin = s2_basin.main.name
  name  = "events"
}

data "s2_basin" "readback" {
  name = s2_basin.main.name
}

Initialize and apply

terraform init
terraform apply

Authentication and Endpoint Configuration

You can configure credentials in provider config or through environment variables:

provider "s2" {
  # optional if S2_ACCESS_TOKEN is set
  access_token = var.s2_access_token

  # optional
  account_endpoint = var.s2_account_endpoint

  # optional
  basin_endpoint   = var.s2_basin_endpoint
}

Environment variables:

S2_ACCESS_TOKEN
S2_ACCOUNT_ENDPOINT (optional)
S2_BASIN_ENDPOINT (optional, supports {basin} placeholder e.g. {basin}.b.s2.dev)

Resource Examples

Basin with defaults

resource "s2_basin" "analytics" {
  name                    = "analytics-events"
  create_stream_on_append = true
  create_stream_on_read   = false

  default_stream_config {
    storage_class = "standard"

    retention_policy {
      age = 604800
    }

    timestamping {
      mode     = "client-prefer"
      uncapped = false
    }
  }
}

Stream config

resource "s2_stream" "orders" {
  basin = s2_basin.analytics.name
  name  = "orders"

  storage_class = "express"

  retention_policy {
    age = 86400
  }

  timestamping {
    mode = "arrival"
  }
}

Scoped access token

resource "s2_access_token" "consumer" {
  token_id = "consumer-token"

  scope = {
    basins = {
      exact = s2_basin.analytics.name
    }
    streams = {
      prefix = "orders"
    }
    ops = ["read"]
  }
}

The issued token value is marked as sensitive, but still lives in Terraform state.

Import Existing Infrastructure

Import formats:

Basin: <basin-name>
Stream: <basin-name>/<stream-name>
Access token: <token-id>

Examples:

terraform import s2_basin.main my-basin
terraform import s2_stream.events my-basin/events
terraform import s2_access_token.consumer my-token-id

Using with s2-lite

When targeting s2-lite, set the account endpoint:

export S2_ACCOUNT_ENDPOINT="localhost:18080"
export S2_ACCESS_TOKEN="test"

Access-token API is not supported with s2-lite.

Recommended Workflow

Pin a provider version in required_providers.
Commit .terraform.lock.hcl.
Use terraform plan to preview changes before applying.
Use terraform import for existing resources rather than recreating.

​Prerequisites

​Quickstart

​Authentication and Endpoint Configuration

​Resource Examples

​Basin with defaults

​Stream config

​Scoped access token

​Import Existing Infrastructure

​Using with s2-lite

​Recommended Workflow

​Related Docs

Prerequisites

Quickstart

Authentication and Endpoint Configuration

Resource Examples

Basin with defaults

Stream config

Scoped access token

Import Existing Infrastructure

Using with s2-lite

Recommended Workflow

Related Docs