Skip to main content

Getting Started

This guide walks through installing the Onehouse provider, authenticating, and applying your first resource.

Prerequisites​

  • Terraform 1.6 or newer
  • An Onehouse account with API credentials (Project UID, API key, API secret, Link UID — all available in your Onehouse console → Profile)
  • A Terraform Cloud token shared by your Onehouse administrator (used to authenticate to the private registry)

Install the provider​

The Onehouse provider is published to a private registry on HCP Terraform at app.terraform.io/Onehouse/onehouse.

Step 1 — log in to HCP Terraform​

In your terminal:

terraform login app.terraform.io

When prompted, paste the Terraform Cloud token your Onehouse admin shared with you. This stores the credential in ~/.terraform.d/credentials.tfrc.json so future terraform init calls can authenticate.

Step 2 — reference the provider in your .tf file​

terraform {
  required_providers {
    onehouse = {
      source  = "app.terraform.io/Onehouse/onehouse"
      version = ">= 1.0.1"
    }
  }
}

provider "onehouse" {}

The provider block can be empty for most uses. Two settings are supported:

SettingDefaultPurpose
onehouse_control_plane"aws"Which Onehouse control plane to talk to. One of "aws" (→ https://api.onehouse.ai) or "gcp" (→ https://api-gcp.onehouse.ai).
timeout"30m"How long to wait on long-running operations (cluster create, etc.). Go duration string ("45m", "1h").
# Defaults — most users
provider "onehouse" {}

# Onehouse on GCP
provider "onehouse" {
  onehouse_control_plane = "gcp"
}

# Longer timeout for slow cluster provisions
provider "onehouse" {
  timeout = "1h"
}

Step 3 — set authentication environment variables​

The provider reads all secret and identifier values from environment variables; they cannot be set in .tf files. See Authentication for the full list. Minimum required:

export ONEHOUSE_PROJECT_UID=...
export ONEHOUSE_API_KEY=...
export ONEHOUSE_API_SECRET=...
export ONEHOUSE_LINK_UID=...
export ONEHOUSE_REGION=us-west-2

Step 4 — initialize and apply​

terraform init
# Should report:
#   Installed app.terraform.io/Onehouse/onehouse vX.Y.Z (signed by Onehouse...)

terraform plan
terraform apply

A complete first example​

Create a small compute cluster:

terraform {
  required_providers {
    onehouse = {
      source  = "app.terraform.io/Onehouse/onehouse"
      version = ">= 1.0.1"
    }
  }
}

provider "onehouse" {}

resource "onehouse_cluster" "first" {
  name        = "tf-first-cluster"
  type        = "Managed"
  min_ocu     = 2
  max_ocu     = 4
  worker_type = "oh-general-4"
}

output "cluster_id" {
  value = onehouse_cluster.first.id
}

output "cluster_status" {
  value = onehouse_cluster.first.status
}
terraform init
terraform apply
# Cluster provisioning takes ~7 minutes.

When complete, the cluster appears in the Onehouse console under Clusters, and terraform output cluster_status prints COMPUTE_CLUSTER_STATUS_RUNNING.

To tear it down:

terraform destroy
# Cluster deletion takes ~5 minutes.

Next steps​