# Terraform

The Altertable Terraform provider manages Altertable resources from configuration: environments, storage buckets, catalogs, service accounts, organization members, lakehouse credentials, and role grants. Use it to review platform changes as plans, keep environments reproducible, and provision access for automation alongside the rest of your infrastructure. It works with Terraform `1.0+` and OpenTofu.

Use Terraform for declarative infrastructure state. Use the [CLI](/docs/developer-tooling/cli.md) for interactive checks, one-off operations, and scripts that need to inspect or act on existing Altertable resources.

## Setup

Add the provider to `required_providers` and configure it with a management API key:

```terraform
terraform {
  required_version = ">= 1.0"
  required_providers {
    altertable = {
      source = "altertable-ai/altertable"
    }
  }
}

provider "altertable" {
  api_key = var.altertable_management_api_key
}
```

Issue a management API key from **Organization settings → Management API keys**, then pass it as `api_key` or set the `ALTERTABLE_API_KEY` environment variable.

## Resources

| Resource                     | Manages                                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `altertable_environment`     | Environments and their cloud provider                                                                               |
| `altertable_bucket`          | Object-storage buckets connected to an environment, backing lakehouse catalogs                                      |
| `altertable_catalog`         | Native databases (`engine = "altertable"`) and external connections such as Postgres, MySQL, BigQuery, or Snowflake |
| `altertable_service_account` | Service accounts for automation                                                                                     |
| `altertable_user`            | Organization members, invited by email                                                                              |
| `altertable_credential`      | Lakehouse credentials for a user or service account in an environment                                               |
| `altertable_role_set`        | The complete set of role grants for one principal                                                                   |

Similarly, data sources exist for buckets, catalogs, credentials, environments, service accounts, and users. A special `altertable_whoami` data source looks up the identity behind the configured key.

Full argument reference for every resource and data source lives on the [Terraform Registry](https://registry.terraform.io/providers/altertable-ai/altertable/latest/docs).

## Example

A complete setup: an environment with a native and an external catalog, and a service account with scoped roles and a lakehouse credential for CI.

```terraform
resource "altertable_environment" "production" {
  name           = "Production"
  cloud_provider = "aws"
  cloud_provider_region = "us-east-1"
}

resource "altertable_catalog" "warehouse" {
  environment_id = altertable_environment.production.id
  engine         = "altertable"
  name           = "Warehouse"
}

resource "altertable_catalog" "analytics" {
  environment_id = altertable_environment.production.id
  engine         = "postgres"
  name           = "Analytics"

  postgres_config = {
    host     = "db.example.com"
    port     = 5432
    database = "analytics"
    username = "altertable"
    password = var.pg_password
  }
}

resource "altertable_user" "teammate" {
  email = "teammate@example.com"
}

resource "altertable_role_set" "teammate" {
  user_id = altertable_user.teammate.id

  roles = [
    { role = "organization:member" },
    { role = "environment:writer", resource_id = altertable_environment.production.id },
  ]
}

resource "altertable_service_account" "ci" {
  label = "CI Deploy"
}

resource "altertable_role_set" "ci" {
  service_account_id = altertable_service_account.ci.id

  roles = [
    { role = "organization:member" },
    { role = "environment:writer", resource_id = altertable_environment.production.id },
  ]
}

resource "altertable_credential" "ci" {
  principal_type = "service_account"
  principal_id   = altertable_service_account.ci.id
  environment_id = altertable_environment.production.id
  label          = "CI"
}

output "ci_password" {
  value     = altertable_credential.ci.password
  sensitive = true
}
```

A role set declares the complete set of grants for a single principal: one `altertable_role_set` per user or service account, mixing organization-wide roles with roles scoped to a `resource_id`. See [Access control](/docs/governance/access-control.md) for the available roles.

## Import existing resources

Bring resources created in the app under Terraform with `import` blocks (Terraform `1.12+`) and resource identities:

```terraform
import {
  to = altertable_environment.production
  identity = {
    id = "7d3e1b9a-2c4f-4a6b-9e8d-5f0a1b2c3d4e"
  }
}
```

Environments, buckets, catalogs, service accounts, credentials, and users support identity import. Nested resources use composite identities — a catalog, for example, is identified by its `environment_id` and `id`. A user is imported by its raw `user_id`.

## Source code

The provider is published on the [Terraform Registry](https://registry.terraform.io/providers/altertable-ai/altertable), and its source code is available at [github.com/altertable-ai/terraform-provider-altertable](https://github.com/altertable-ai/terraform-provider-altertable).