> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bronto.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Bronto with OpenTofu

> Use the official Bronto provider with OpenTofu to manage resources, import existing configuration, and automate changes.

The official Bronto provider works with OpenTofu, so you can version, review, and deploy Bronto configuration alongside the rest of your infrastructure.

Use this guide to configure the provider, export existing Bronto resources, and manage your first resource as code.

> **[OpenTofu Registry](https://search.opentofu.org/provider/brontoio/bronto/latest)**
>
> Browse the provider, resource, and data source reference.

> **[GitHub repository](https://github.com/brontoio/terraform-provider-bronto)**
>
> View the provider source, examples, and release history.

> [!NOTE]
>
> Use the latest provider release. The examples on this page require `v0.4.0` or later; run `tofu init -upgrade` to update the version selected in your dependency lock file.

## What you can manage

The OpenTofu provider supports Bronto users, dashboards, widgets, metric definitions, monitors, Slack integrations, and webhook integrations. It also includes data sources for datasets, Slack workspaces, and users.

For the current schemas and examples, see the [Bronto provider in the OpenTofu Registry](https://search.opentofu.org/provider/brontoio/bronto/latest).

## Prerequisites

Before you begin, you need:

* A current OpenTofu release
* A Bronto API endpoint, such as `https://api.eu.bronto.io`
* A Bronto API key with write permission for the resources you want to manage

For an initial evaluation of the full provider, use an Admin API key. For ongoing use, create a dedicated key with only the permissions required by your configuration. See [API Keys](https://docs.bronto.io/Account-Management/API-Keys.md) for instructions.

## Configure the provider

**1. Declare the provider**

Create an OpenTofu configuration that uses the latest provider release. OpenTofu uses the standard `terraform` block for provider requirements:

```hcl main.tf theme={"dark"}
terraform {
  required_providers {
    bronto = {
      source  = "brontoio/bronto"
      version = ">= 0.4.0"
    }
  }
}

variable "bronto_endpoint" {
  description = "Base URL for the Bronto API"
  type        = string
  default     = "https://api.eu.bronto.io"
}

variable "bronto_api_key" {
  description = "API key used to manage Bronto resources"
  type        = string
  sensitive   = true
}

provider "bronto" {
  endpoint = var.bronto_endpoint
  api_key  = var.bronto_api_key

  default_tags = {
    managed_by = "opentofu"
  }
}
```

Change `bronto_endpoint` if your organisation uses another Bronto region or environment. `default_tags` are merged into every taggable `bronto_user`, `bronto_dashboard`, and `bronto_widget`; tags set directly on a resource take precedence.

**2. Provide the API key securely**

Pass the API key through an environment variable rather than writing it into a committed `.tf` or `.tfvars` file:

```bash theme={"dark"}
export TF_VAR_bronto_api_key="<YOUR_API_KEY>"
```

The provider also supports the `BRONTO_ENDPOINT` and `BRONTO_API_KEY` environment variables. In CI, inject credentials from your platform's secret store.

**3. Declare a Bronto resource**

Add a user resource to the configuration:

```hcl main.tf theme={"dark"}
resource "bronto_user" "example" {
  first_name = "Jane"
  last_name  = "Doe"
  email      = "jane.doe@example.com"
  roles      = ["Standard"]
}
```

> [!WARNING]
>
> Applying this example creates a real Bronto user and may send an invitation email. Replace the example address with an address you control.

**4. Review and apply the change**

Initialise OpenTofu, validate the configuration, and review the plan before applying it:

```bash theme={"dark"}
tofu init
tofu fmt
tofu validate
tofu plan
tofu apply
```

Commit the generated `.terraform.lock.hcl` file so every environment uses the same provider build.

## Export existing resources from Bronto

Bronto can generate HCL and an `import` block for existing dashboards, monitors, users, Slack integrations, and webhook integrations. Although the UI labels the format **Terraform (HCL)**, the generated `.tf` file works with OpenTofu.

**1. Export the resource**

Open the resource's actions menu and select **Export**. Review the generated resource and `import` blocks. Dashboard exports include their widgets; enable **Include referenced metrics** when you also want the referenced metric definitions.

**2. Add the HCL to your project**

Select **Copy** or **Download Terraform**, then add the generated configuration to your OpenTofu project.

**3. Plan the import**

Run `tofu plan` and inspect the proposed import and resource state before applying it. The import adopts the existing Bronto resource; it does not create another one.

## Manage multiple organisations

Declare an aliased provider for each organisation and add `provider = bronto.<alias>` to each resource. Users belong to the root organisation, so manage `bronto_user` resources with the root provider. The HCL pattern is the same as the [Terraform multi-organisation example](https://docs.bronto.io/automation/terraform.md#manage-multiple-organisations).

## Recommended workflow

* Run `tofu fmt` and `tofu validate` on every change.
* Run `tofu plan` in pull requests and require review before applying.
* Run `tofu init -upgrade`, then review and commit the updated `.terraform.lock.hcl`, when adopting a newer provider release.
* Use separate state and API keys for development, staging, and production.
* Avoid editing an OpenTofu-managed resource in both the Bronto UI and your HCL configuration, because the next apply can replace the manual change.
* Review a destroy plan carefully. Removing a resource from configuration can delete the corresponding resource in Bronto.
* Refer to the [OpenTofu Registry](https://search.opentofu.org/provider/brontoio/bronto/latest) for current schemas and examples.

## Troubleshooting

### Authentication fails

Confirm that the API key is active and has permission to read and write every resource in the configuration. Check that the key and endpoint belong to the same Bronto region and organisation.

### OpenTofu manages the wrong organisation

When you use provider aliases, add `provider = bronto.<alias>` to each resource. OpenTofu otherwise uses the default, unaliased provider configuration.

### A plan shows unexpected changes

Check whether the resource was changed in the Bronto UI after the last apply. Review the generated plan before reconciling the configuration or applying the change.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.