Terraform Provider for StoneBranch

A community-developed Terraform provider for managing resources in StoneBranch Universal Controller.

Disclaimer: This is an independent, community-driven project and is not affiliated with, endorsed by, or sponsored by Stonebranch GmbH. "Stonebranch", "Universal Controller", "Universal Automation Center", and related product names are trademarks or registered trademarks of Stonebranch GmbH. All trademarks are the property of their respective owners.

Requirements

Terraform >= 1.0
A StoneBranch Universal Controller instance with API access
A valid API token with appropriate permissions

Installation

Download the latest release from GitHub Releases and install to your Terraform plugins directory.

macOS (Apple Silicon)

VERSION=0.4.0
curl -LO "https://github.com/OptionMetrics/terraform-provider-stonebranch/releases/download/v${VERSION}/terraform-provider-stonebranch_${VERSION}_darwin_arm64.zip"
unzip terraform-provider-stonebranch_${VERSION}_darwin_arm64.zip
mkdir -p ~/.terraform.d/plugins/registry.terraform.io/stonebranch/stonebranch/${VERSION}/darwin_arm64
mv terraform-provider-stonebranch_v${VERSION} ~/.terraform.d/plugins/registry.terraform.io/stonebranch/stonebranch/${VERSION}/darwin_arm64/
rm terraform-provider-stonebranch_${VERSION}_darwin_arm64.zip

macOS (Intel)

VERSION=0.4.0
curl -LO "https://github.com/OptionMetrics/terraform-provider-stonebranch/releases/download/v${VERSION}/terraform-provider-stonebranch_${VERSION}_darwin_amd64.zip"
unzip terraform-provider-stonebranch_${VERSION}_darwin_amd64.zip
mkdir -p ~/.terraform.d/plugins/registry.terraform.io/stonebranch/stonebranch/${VERSION}/darwin_amd64
mv terraform-provider-stonebranch_v${VERSION} ~/.terraform.d/plugins/registry.terraform.io/stonebranch/stonebranch/${VERSION}/darwin_amd64/
rm terraform-provider-stonebranch_${VERSION}_darwin_amd64.zip

Linux (x86_64)

VERSION=0.4.0
curl -LO "https://github.com/OptionMetrics/terraform-provider-stonebranch/releases/download/v${VERSION}/terraform-provider-stonebranch_${VERSION}_linux_amd64.zip"
unzip terraform-provider-stonebranch_${VERSION}_linux_amd64.zip
mkdir -p ~/.terraform.d/plugins/registry.terraform.io/stonebranch/stonebranch/${VERSION}/linux_amd64
mv terraform-provider-stonebranch_v${VERSION} ~/.terraform.d/plugins/registry.terraform.io/stonebranch/stonebranch/${VERSION}/linux_amd64/
rm terraform-provider-stonebranch_${VERSION}_linux_amd64.zip

Configure Terraform to Use Local Provider

After installing the provider binary, create or edit ~/.terraformrc to tell Terraform to use the local filesystem mirror:

provider_installation {
  filesystem_mirror {
    path    = "/Users/YOUR_USERNAME/.terraform.d/plugins"
    include = ["stonebranch/stonebranch"]
  }
  direct {
    exclude = ["stonebranch/stonebranch"]
  }
}

Replace YOUR_USERNAME with your actual username, or use the full path from echo $HOME.

For Linux, use:

provider_installation {
  filesystem_mirror {
    path    = "/home/YOUR_USERNAME/.terraform.d/plugins"
    include = ["stonebranch/stonebranch"]
  }
  direct {
    exclude = ["stonebranch/stonebranch"]
  }
}

Then in your Terraform configuration, reference the provider:

terraform {
  required_providers {
    stonebranch = {
      source  = "stonebranch/stonebranch"
      version = "0.4.0"
    }
  }
}

Run terraform init to verify the provider is found.

Building from Source

Requires Go >= 1.24.

git clone https://github.com/OptionMetrics/terraform-provider-stonebranch.git
cd terraform-provider-stonebranch
make build

This creates the terraform-provider-stonebranch binary in the project root.

See RELEASE.md for the full release process.

sb2tf - Export Existing Resources to Terraform (Experimental)

Note: sb2tf is an experimental utility shipped separately from the provider. It may have incomplete support for some resource types, and its output may require manual adjustments. Use at your own risk.

The sb2tf utility exports existing StoneBranch resources to Terraform configuration files. Use it to bootstrap a new Terraform project from existing resources or migrate manually-created resources to Infrastructure as Code.

Installation

Download from GitHub Releases or build from source:

make build-sb2tf
# Binary created at ./bin/sb2tf

Authentication

export STONEBRANCH_API_TOKEN="your-token"
export STONEBRANCH_BASE_URL="https://your-instance.stonebranch.cloud"

Usage Examples

# List available resource types
sb2tf list

# List all tasks (shows name, type, summary)
sb2tf list tasks

# List tasks matching a pattern (supports * and ? wildcards)
sb2tf list tasks --filter "prod-*"

# Export a single resource
sb2tf export task_unix my_task

# Export a workflow with all its tasks, vertices, and edges
sb2tf export task_workflow my_workflow

# Export all tasks matching a pattern
sb2tf export tasks --all --filter "prod-*"

# Export to a directory (creates main.tf)
sb2tf export tasks --all --output ./terraform/

# Show what would be exported without writing files
sb2tf export tasks --all --dry-run

Workflow Export

When exporting workflows, sb2tf automatically includes:

The workflow definition
All tasks contained in the workflow
Workflow vertices (task instances)
Workflow edges (task dependencies)

The output is organized logically with proper Terraform references:

# Workflow definition
resource "stonebranch_task_workflow" "task_workflow_001" {
  name = "My Workflow"
  ...
}

# Tasks in the workflow
resource "stonebranch_task_unix" "task_unix_001" {
  name = "Task A"
  ...
}

# Vertices
resource "stonebranch_workflow_vertex" "workflow_vertex_001" {
  workflow_name = "My Workflow"
  task_name     = "Task A"
}

# Edges with proper vertex references
resource "stonebranch_workflow_edge" "workflow_edge_001" {
  workflow_name = "My Workflow"
  source_id     = stonebranch_workflow_vertex.workflow_vertex_001.vertex_id
  target_id     = stonebranch_workflow_vertex.workflow_vertex_002.vertex_id
}

Local Development Setup

1. Configure Development Overrides

Create or edit ~/.terraformrc to point Terraform to your local build:

provider_installation {
  dev_overrides {
    "registry.terraform.io/stonebranch/stonebranch" = "/path/to/terraform-provider-stonebranch"
  }
  direct {}
}

Or use the provided dev config:

export TF_CLI_CONFIG_FILE=/path/to/terraform-provider-stonebranch/examples/dev.tfrc

2. Set Environment Variables

export STONEBRANCH_API_TOKEN="your-bearer-token"
export STONEBRANCH_BASE_URL="https://your-instance.stonebranch.cloud"  # optional

3. Build and Test

# Build the provider
make build

# Navigate to example directory
cd examples/provider

# IMPORTANT: Skip "terraform init" when using dev overrides!
# Just run plan/apply directly:

# Plan changes
terraform plan

# Apply changes
terraform apply

Provider Configuration

terraform {
  required_providers {
    stonebranch = {
      source = "registry.terraform.io/stonebranch/stonebranch"
    }
  }
}

provider "stonebranch" {
  # API token for authentication (required)
  # Can also use STONEBRANCH_API_TOKEN environment variable
  api_token = var.stonebranch_token

  # Base URL for the StoneBranch API (required)
  # Can also use STONEBRANCH_BASE_URL environment variable
  base_url = "https://your-instance.stonebranch.cloud"
}

Authentication

The provider uses Bearer token authentication. Obtain your token from the StoneBranch Universal Controller:

Log into your StoneBranch instance
Navigate to user settings or API token management
Generate or copy your API token

You can provide the token via:

The api_token provider attribute
The STONEBRANCH_API_TOKEN environment variable (recommended for security)

Resources

Tasks

stonebranch_task_unix - Unix/Linux command tasks
stonebranch_task_windows - Windows command tasks
stonebranch_task_file_transfer - File transfer tasks
stonebranch_task_sql - SQL database tasks
stonebranch_task_email - Email notification tasks
stonebranch_task_workflow - Workflow orchestration tasks

Workflows

stonebranch_workflow_vertex - Tasks within workflows
stonebranch_workflow_edge - Task dependencies in workflows

Triggers

stonebranch_trigger_time - Time-based triggers
stonebranch_trigger_cron - Cron expression triggers

Connections

stonebranch_database_connection - Database connections
stonebranch_email_connection - Email server connections

Supporting Resources

stonebranch_script - Reusable scripts
stonebranch_credential - Authentication credentials
stonebranch_variable - Global variables
stonebranch_business_service - Business service groups

stonebranch_task_unix

Manages a StoneBranch Unix/Linux task.

Example Usage

# Simple task with a command
resource "stonebranch_task_unix" "hello" {
  name    = "terraform-hello-world"
  summary = "A simple task managed by Terraform"
  command = "echo 'Hello from Terraform!'"
  agent   = "my-linux-agent"
}

# Task with script content
resource "stonebranch_task_unix" "script" {
  name              = "terraform-script-task"
  summary           = "Task that runs a script"
  command_or_script = "Script"
  script            = <<-EOT
    #!/bin/bash
    echo "Starting..."
    date
    echo "Done"
  EOT
  agent = "my-linux-agent"
}

# Task with retry configuration
resource "stonebranch_task_unix" "with_retry" {
  name           = "terraform-retry-task"
  command        = "/opt/scripts/job.sh"
  agent          = "my-linux-agent"
  retry_maximum  = 3
  retry_interval = 300
}

Argument Reference

Attribute	Type	Required	Description
`name`	string	Yes	Unique name of the task
`summary`	string	No	Description of the task
`agent`	string	No*	Agent to run the task on
`agent_cluster`	string	No*	Agent cluster to run the task on
`command`	string	No	Command to execute
`command_or_script`	string	No	`Command` or `Script`
`script`	string	No	Script content (when `command_or_script = "Script"`)
`runtime_dir`	string	No	Working directory
`parameters`	string	No	Parameters to pass
`credentials`	string	No	Credentials to use
`exit_codes`	string	No	Success exit codes (e.g., `"0"` or `"0,1,2"`)
`exit_code_processing`	string	No	`Success Exitcode Range` or `Failure Exitcode Range`
`retry_maximum`	int	No	Max retry attempts
`retry_interval`	int	No	Seconds between retries
`retry_indefinitely`	bool	No	Retry forever
`run_as_sudo`	bool	No	Run with sudo
`opswise_groups`	list	No	Business service names

*One of agent or agent_cluster is required by the API.

Attribute Reference

Attribute	Description
`sys_id`	System ID assigned by StoneBranch
`version`	Version number for optimistic locking

Import

Tasks can be imported using the task name:

terraform import stonebranch_task_unix.example "task-name"

stonebranch_task_windows

Manages a StoneBranch Windows task.

Example Usage

# Simple Windows task with a command
resource "stonebranch_task_windows" "hello" {
  name    = "terraform-windows-hello"
  summary = "A simple Windows task managed by Terraform"
  command = "echo Hello from Terraform!"
  agent   = "my-windows-agent"
}

# Windows task with elevated privileges
resource "stonebranch_task_windows" "admin_task" {
  name         = "terraform-admin-task"
  command      = "net user"
  agent        = "my-windows-agent"
  elevate_user = true
}

Argument Reference

Attribute	Type	Required	Description
`name`	string	Yes	Unique name of the task
`summary`	string	No	Description of the task
`agent`	string	No*	Agent to run the task on
`agent_cluster`	string	No*	Agent cluster to run the task on
`command`	string	No	Command to execute
`command_or_script`	string	No	`Command` or `Script`
`script`	string	No	Script resource name (when `command_or_script = "Script"`)
`runtime_dir`	string	No	Working directory
`parameters`	string	No	Parameters to pass
`credentials`	string	No	Credentials to use
`exit_codes`	string	No	Success exit codes (e.g., `"0"` or `"0,1,2"`)
`exit_code_processing`	string	No	`Success Exitcode Range` or `Failure Exitcode Range`
`retry_maximum`	int	No	Max retry attempts
`retry_interval`	int	No	Seconds between retries
`retry_indefinitely`	bool	No	Retry forever
`elevate_user`	bool	No	Run with administrator privileges
`desktop_interact`	bool	No	Allow desktop interaction
`create_console`	bool	No	Create console window
`opswise_groups`	list	No	Business service names

*One of agent or agent_cluster is required by the API.

Attribute Reference

Attribute	Description
`sys_id`	System ID assigned by StoneBranch
`version`	Version number for optimistic locking

Import

Tasks can be imported using the task name:

terraform import stonebranch_task_windows.example "task-name"

stonebranch_script

Manages a reusable script resource that can be referenced by tasks.

Example Usage

resource "stonebranch_script" "backup" {
  name    = "backup-script"
  content = <<-EOT
    #!/bin/bash
    tar -czf /backup/data.tar.gz /data
  EOT
}

# Reference the script in a task
resource "stonebranch_task_unix" "backup_job" {
  name              = "backup-job"
  command_or_script = "Script"
  script            = stonebranch_script.backup.name
  agent             = "my-linux-agent"
}

stonebranch_trigger_time

Manages a time-based trigger for scheduling task execution.

Example Usage

resource "stonebranch_trigger_time" "daily" {
  name      = "daily-trigger"
  tasks     = [stonebranch_task_unix.my_task.name]
  time      = "08:00"
  time_zone = "America/New_York"
}

stonebranch_credential

Manages authentication credentials for task execution.

Example Usage

resource "stonebranch_credential" "service_account" {
  name             = "service-account-creds"
  runtime_user     = "svc_user"
  runtime_password = var.service_password
}

stonebranch_variable

Manages global variables that can be referenced by tasks and triggers.

Example Usage

resource "stonebranch_variable" "environment" {
  name        = "APP_ENVIRONMENT"
  value       = "production"
  description = "Current application environment"
}

stonebranch_business_service

Manages business service groups for organizing resources.

Example Usage

resource "stonebranch_business_service" "production" {
  name        = "Production Services"
  description = "Business service for production workloads"
}

# Reference in other resources via opswise_groups
resource "stonebranch_variable" "app_env" {
  name           = "APP_ENVIRONMENT"
  value          = "production"
  opswise_groups = [stonebranch_business_service.production.name]
}

Argument Reference

Attribute	Type	Required	Description
`name`	string	Yes	Unique name of the business service
`description`	string	No	Description of the business service

Attribute Reference

Attribute	Description
`sys_id`	System ID assigned by StoneBranch
`version`	Version number for optimistic locking

Import

Business services can be imported using the name:

terraform import stonebranch_business_service.example "service-name"

Development

Project Structure

terraform-provider-stonebranch/
├── main.go                          # Provider entry point
├── cmd/
│   └── sb2tf/                       # sb2tf CLI utility
│       ├── main.go                  # CLI entry point
│       ├── cli/                     # Command implementations
│       │   ├── root.go              # Root command, global flags
│       │   ├── list.go              # List resources command
│       │   └── export.go            # Export resources command
│       └── generator/               # HCL generation
│           ├── generator.go         # Core generation logic
│           ├── resources.go         # Resource type registry
│           └── templates.go         # HCL templates
├── internal/
│   ├── provider/
│   │   ├── provider.go              # Provider configuration and schema
│   │   ├── resources/               # Resource implementations
│   │   └── data_sources/            # Data source implementations
│   ├── acctest/
│   │   └── acctest.go               # Acceptance test helpers
│   └── client/
│       └── client.go                # StoneBranch API HTTP client
├── examples/
│   ├── dev.tfrc                     # Development override config
│   └── provider/
│       └── main.tf                  # Example Terraform configuration
├── docs/                            # Generated documentation
├── Makefile                         # Build automation
└── openapi.yaml                     # StoneBranch API specification

Useful Commands

# Provider
make build            # Build the provider binary
make test             # Run tests
make testacc          # Run acceptance tests (requires API credentials)
make fmt              # Format Go code
make clean            # Remove built binaries
make docs             # Generate provider documentation

# sb2tf utility
make build-sb2tf      # Build the sb2tf binary
make install-sb2tf    # Install sb2tf to $GOPATH/bin

# Releases
make release-snapshot # Build release artifacts (no tag required)
make publish          # Build and publish to GitHub Releases

Generating Documentation

Documentation is auto-generated from provider schemas using tfplugindocs.

# Generate/update documentation
make docs

The generated docs are written to docs/ and include:

Provider overview (docs/index.md)
Resource documentation (docs/resources/*.md)
Data source documentation (docs/data-sources/*.md)

Examples are pulled from examples/resources/*/resource.tf and examples/data-sources/*/data-source.tf.

Always regenerate docs after schema changes:

# After modifying resource schemas
make docs
git add docs/
git commit -m "Update generated documentation"

Releasing

See RELEASE.md for the complete release and publishing process.

Running Tests

# Unit tests
make test

# Acceptance tests (requires valid credentials)
export STONEBRANCH_API_TOKEN="your-token"
export STONEBRANCH_BASE_URL="https://your-instance.stonebranch.cloud"
TF_ACC=1 go test -v ./...

Troubleshooting

"Provider not found" error

Ensure your ~/.terraformrc or TF_CLI_CONFIG_FILE points to the correct binary location.

Authentication errors

Verify your token is valid and not expired
Check that the token has appropriate permissions
Ensure the base URL is correct (no trailing slash)

API errors

Enable debug logging:

export TF_LOG=DEBUG
terraform plan

License

This project is licensed under the MIT License.

Trademarks

"Stonebranch", "Universal Controller", "Universal Automation Center", and related product names are trademarks or registered trademarks of Stonebranch GmbH. "Terraform" is a trademark of HashiCorp, Inc. This project is not endorsed by or affiliated with either company.

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.github		.github
cmd/sb2tf		cmd/sb2tf
docs		docs
examples		examples
internal		internal
templates		templates
tools		tools
.env.example		.env.example
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASE.md		RELEASE.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
openapi.yaml		openapi.yaml
terraform-registry-manifest.json		terraform-registry-manifest.json

Folders and files

Latest commit

History

Repository files navigation

Terraform Provider for StoneBranch

Requirements

Installation

macOS (Apple Silicon)

macOS (Intel)

Linux (x86_64)

Configure Terraform to Use Local Provider

Building from Source

sb2tf - Export Existing Resources to Terraform (Experimental)

Installation

Authentication

Usage Examples

Workflow Export

Local Development Setup

1. Configure Development Overrides

2. Set Environment Variables

3. Build and Test

Provider Configuration

Authentication

Resources

Tasks

Workflows

Triggers

Connections

Supporting Resources

stonebranch_task_unix

Example Usage

Argument Reference

Attribute Reference

Import

stonebranch_task_windows

Example Usage

Argument Reference

Attribute Reference

Import

stonebranch_script

Example Usage

stonebranch_trigger_time

Example Usage

stonebranch_credential

Example Usage

stonebranch_variable

Example Usage

stonebranch_business_service

Example Usage

Argument Reference

Attribute Reference

Import

Development

Project Structure

Useful Commands

Generating Documentation

Releasing

Running Tests

Troubleshooting

"Provider not found" error

Authentication errors

API errors

License

Trademarks

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Uh oh!

Contributors

Packages