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

# Install the Chronosphere Terraform provider

export const ApiToken = () => <>
    Replace <em><code>API_TOKEN</code></em> with the API token generated from your <a href="/administer/accounts-teams/service-accounts">service account</a>. Chronosphere recommends storing your API token in a separate file or Kubernetes Secret and calling it using an environment variable, such as <code>$API_TOKEN</code>.
  </>;

<Note>
  To use the Chronosphere Terraform provider, you must first install Terraform. For
  details, see the
  [Terraform documentation](https://developer.hashicorp.com/terraform/downloads).
</Note>

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

1. [Install the Terraform provider](#install-the-provider).
2. [Authenticate to Chronosphere](#authenticate-to-chronosphere).
3. [Bootstrap your Terraform configuration](#bootstrap-your-terraform-configuration).

## Install the provider

As of v1.0.0, the Chronosphere Terraform provider is
[open source](https://github.com/chronosphereio/terraform-provider-chronosphere)
and available from the
[HashiCorp Terraform Registry](https://registry.terraform.io/providers/chronosphereio/chronosphere/latest).

```terraform theme={null}
terraform {
  required_providers {
    chronosphere = {
      source  = "chronosphereio/chronosphere"
      version = "1.32.0"
    }
  }
}
```

Versions 1.0.0 and newer remove several deprecated and unsupported features from the
provider. For details about those changes, see the
[Terraform release notes](/tooling/infrastructure/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 theme={null}
terraform {
  required_providers {
    chronosphere = {
      source  = "tf-registry.chronosphere.io/chronosphere/chronosphere"
      version = "0.46.0"
    }
  }
}
```

## Authenticate to Chronosphere

The Terraform provider requires an API token generated from an unrestricted
[service account](/administer/accounts-teams/service-accounts) 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.

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

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:

   ```shell /API_TOKEN_VALUE/ theme={null}
   export CHRONOSPHERE_API_TOKEN=API_TOKEN_VALUE
   ```

   <ApiToken />

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

   ```terraform /MY_ORG/ theme={null}
   provider "chronosphere" {
     org = "MY_ORG"
   }
   ```

   Replace *`MY_ORG`* with your Chronosphere subdomain name, such as
   `MY_ORG.chronosphere.io`.

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`](https://curl.se) to download the latest version of `chronotf`, which is available for
Linux and macOS.

<Tabs>
  <Tab title="macOS (Intel)" id="install-chronotf-macos-amd64">
    1. Download the `darwin_amd64` build of `chronotf`:

       ```shell theme={null}
       curl -LO https://storage.googleapis.com/chronosphere-terraform/1.32.0/chronotf_1.32.0_darwin_amd64
       ```

    2. Make the `chronotf` binary executable.

       ```shell theme={null}
       chmod +x chronotf_1.32.0_darwin_amd64
       ```

    3. Move the binary into your `PATH`:

       ```shell theme={null}
       sudo mv chronotf_1.32.0_darwin_amd64 /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:

       ```shell theme={null}
       chronotf version
       ```
  </Tab>

  <Tab title="macOS (M-series)" id="install-chronotf-macos-arm64">
    1. Download the `darwin_arm64` build of `chronotf`:

       ```shell theme={null}
       curl -LO https://storage.googleapis.com/chronosphere-terraform/1.32.0/chronotf_1.32.0_darwin_arm64
       ```

    2. Make the `chronotf` binary executable:

       ```shell theme={null}
       chmod +x chronotf_1.32.0_darwin_arm64
       ```

    3. Move the binary into your `PATH`:

       ```shell theme={null}
       sudo mv chronotf_1.32.0_darwin_arm64 /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:

       ```shell theme={null}
       chronotf version
       ```
  </Tab>

  <Tab title="Linux" id="installing-chronotf-linux">
    1. Download the `linux_amd64` build of `chronotf`:

       ```shell theme={null}
       curl -LO https://storage.googleapis.com/chronosphere-terraform/1.32.0/chronotf_1.32.0_linux_amd64
       ```

    2. Make the `chronotf` binary executable:

       ```shell theme={null}
       chmod +x chronotf_1.32.0_linux_amd64
       ```

    3. Move the binary into your `PATH`:

       ```shell theme={null}
       mv chronotf_1.32.0_linux_amd64 /usr/local/bin/chronotf
       ```

    4. Test the `chronotf` installation by running it:

       ```shell theme={null}
       chronotf version
       ```
  </Tab>
</Tabs>

### 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 `main.tf` Terraform
   file:

   ```shell /API_TOKEN/ /MY_ORG/ theme={null}
   ./chronotf export-config -o main.tf --api-token API_TOKEN --org MY_ORG
   ```

   Replace the following:

   * *`API_TOKEN`*: A Chronosphere API token, such as from a
     [service account](/administer/accounts-teams/service-accounts).
   * *`MY_ORG`*: Your Chronosphere subdomain name, such as `MY_ORG.chronosphere.io`.

1) Preview what Terraform adds when bootstrapping its state with the `--dry-run` flag.

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

   ```shell theme={null}
   chronotf import-state --dry-run
   ```

2) Bootstrap the Terraform state.

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

   ```shell theme={null}
   chronotf import-state
   ```