Install the Chronosphere Terraform provider

To use the Chronosphere Terraform provider, you must first install Terraform. For details, see the Terraform documentation (opens in a new tab).

Use the following steps to install the Chronosphere Terraform provider for your use:

  1. Install the Terraform provider.
  2. Authenticate to Chronosphere.
  3. Bootstrap your Terraform configuration.

Install the provider

As of v1.0.0, the Chronosphere Terraform provider is open-source (opens in a new tab) and available from the Hashicorp Terraform Registry (opens in a new tab).

terraform {
  required_providers {
    chronosphere = {
      source = "chronosphereio/chronosphere"
      version = "1.0.0"

Versions 1.0.0 and newer remove several deprecated and unsupported features from the provider. For details on those changes, see the Terraform release notes.

Install versions prior to v1.0.0

Chronosphere hosts older versions of the Terraform provider in a custom registry. Chronosphere doesn't support these older versions, which include deprecated features removed in v1.0.0.

To install and use these unsupported versions, configure your provider using the following code:

terraform {
  required_providers {
    chronosphere = {
      version = "${versions.terraform}"
      source  = ""

Replace ${versions.terraform} with "0.46.0".

Authenticate to Chronosphere

The Terraform provider requires an API token generated from an unrestricted service account with the SysAdmin role to authenticate with the Chronosphere API. If you need to create a new service account, you must use an account that belongs to a team with the SysAdmin role.


Store the API token in a secure location. If you lose your token, you must create a new service account.

After you have the API token, you can use it to grant Terraform permission to modify Chronosphere resources:

  1. In the shell environment where you plan to run Terraform, set the CHRONOSPHERE_API_TOKEN environment variable:


    Replace API_TOKEN_VALUE with the service account's API token.

  2. Add your organization to the provider configuration in your Terraform file:

    provider "chronosphere" {
      org = "MY_ORG"

    Replace MY_ORG with your Chronosphere subdomain name, such as

  3. Run terraform init to set up the local data necessary to run Terraform with a new provider.

Bootstrap your Terraform configuration

You can use Terraform to manage new or existing supported resources. The chronotf tool generates Terraform configurations from existing resources and imports them into the Terraform state.

Install chronotf

Use curl (opens in a new tab) to download the latest version of chronotf, which is available for Linux and macOS.

  1. Download the darwin_amd64 build of chronotf:

    curl -LO {chronotfMacOSIntelLink}
  2. Make the chronotf binary executable.

    chmod +x {chronotfMacOSIntel}
  3. Move the binary into your PATH:

    sudo mv {chronotfMacOSIntel} /usr/local/bin/chronotf

    If you don't have permission to install to /usr/local/bin, replace it with another directory in your PATH.

  4. Test the chronotf installation by running it:

    chronotf version

Run chronotf

Terraform keeps local state to determine how to reconcile Terraform files with real resources.

If you created some of your Terraform resources outside of Terraform, import them into the Terraform state with the chronotf import-state command before running terraform apply.

  1. Create Terraform configuration for existing resources.

    Use the following command to export existing resources to a Terraform file:

    ./chronotf export-config -o --api-token API_TOKEN --org MY_ORG

    Replace the following:

    • API_TOKEN: a Chronosphere API token, such as from a service account.
    • MY_ORG: your Chronosphere subdomain name, such as
  2. Preview what Terraform adds when bootstrapping its state with the --dry-run flag.

    From the directory with the Terraform files and state, run:

    chronotf import-state --dry-run
  3. Bootstrap the Terraform state.

    From the directory with the Terraform files and state, run:

    chronotf import-state