Getting Started with the ChaosSearch Terraform Provider

Follow these general steps to get started with the setup and use of the Terraform environment.

These steps are described in more detail in the following sections.

  1. Install Terraform.
  2. Specify the ChaosSearch Terraform Provider Details.
  3. Specify the ChaosSearch Resources.
  4. Run terraform init to initialize the Terraform environment on your workstation/server.
  5. Run terraform plan to process the .tf resource files and review for any errors.
  6. Run terraform apply to create or update the resources with the configruation in the .tf files.
  7. Run terraform destroy to remove/delete the Terraform-created or Terraform-updated resources when needed.

Install Terraform

In many customer environments, Terraform might already be installed and configured on user systems per your site policies and setup. If you have Terraform installed, proceed to the next step to define the provider details.

If you have not yet installed Terraform, there are many general internal locations for steps and videos on how to install and set up Terraform. For example, see for steps used by common workstation platforms, or to obtain the Terraform binaries.

After you install Terraform, proceed to the next section to continue setting up the ChaosSearch provider.

Specify the ChaosSearch Terraform Provider Details

The ChaosSearch Terraform provider is available in the Terraform registry at

The registry pages include the provider code and documentation, examples, and readmes for using the provider.

To specify the provider section:

  1. In the source control location that will hold the Terraform configuration (or a local folder if you are testing with a dev cluster), create a folder to hold your configuration and related files.


Manage cluster environments separately

If you have multiple ChaosSearch clusters, it is a good practice to have a separate folder for each site (for example, ~/terraform/\<cluster_name>/…).

  1. Create a main terraform configuration file. In most cases the file is named, and it is a text/ASCII format file.
    If you have more than one .tf file name in the directory, Terraform processes all of the .tf files during an init/apply/destroy operation. If you have multiple .tf files, you can change the suffix (.tf_old) to ignore that file; otherwise, make sure that the separate .tf files do not have any duplicate, overlapping definitions.
  2. Using a text editor, open the .tf file that you created.
  3. In the ChaosSearch Provider registry screen (shown previously), click Use Provider and copy the text for that version of the provider into the .tf file, for example:
terraform {  
  required_providers {  
    chaossearch = {  
      source = "ChaosSearch/chaossearch"  
      version = "1.0.10"  

provider "chaossearch" {
  # Configuration options
  1. In the provider field, define the access information for the ChaosSearch deployment. Typically you specify login credentials using a user/password combination, or an API Key/secret key pair:
For a cluster where you plan to use login credentials to authenticate:For a cluster where you plan to use API keys to authenticate:
provider "chaossearch" { url = "" region = "" parent_user_id = "" login { user_name = "" password = "" } }provider "chaossearch" { url = "" access_key_id = "" secret_access_key = "" region = "" parent_user_id = "" }


There can be only one provider definition.

If you have multiple *.tf files in the same directory, make sure that you have only one provider defined across the set of files.

The fields all have equivalent environment variable default functions.

FieldRequiredEnvironment VariableDescription
urlYesCS_URLThe URL for your ChaosSearch cluster in https\://<domain> format.
access_key_idYes*CS_ACCESS_KEYThe API Key ID. This can be found in Settings > API Keys. This value is required unless you are using root/subaccount authentication.
secret_access_keyYes*CS_SECRET_KEYThe secret key. This value is returned when you create an API key, but it is not displayable later in the API Keys page or through a REST API endpoint. Make sure that you have the secret key for the API key that you are using. This value is required if you specify an access key ID.
regionYesCS_REGIONThe cluster's deploy region. You can obtain the value from the Settings > AWS Credentials page, and by transforming the Region Name (such as US East (N. Virginia)) to the region string (such as us-east-1).
parent_user_idYes*CS_PARENT_USER_IDSpecifies the external ID for the cluster. You can obtain the value from the Settings > AWS Credentials page. This field is required if you authenticate with a subaccount (not the root user) or with API keys.
loginNoSpecifies the optional login block for root/subaccount and password. Required if you do not use API keys.
user_nameYes*CS_USERNAMEThe ChaosSearch user name for root or subaccount authentication.
passwordYes*CS_PASSWORDThe ChaosSearch password for the root or subaccount authentication.
optionsNoA block to specify options for the login. Currently the only supported option is retry_count to specify a limit for the number of times to retry the login to the ChaosSearch cluster. The default is 10.


provider "chaossearch" {  
  url               = "<>"  
  access_key_id     = "ZSQX08KS0A3MTQC12345"  
  secret_access_key = "IuEjpEjmT2zKEoJtdF0doAJGyd0abcd12345"  
  region            = "us-east-1"  
  parent_user_id    = "abc12345-7243-4342-b131-dc83f8c69efd"  
  login {
    user_name = ""
    passsword = ""
  options {
    retry_count = 10

What’s Next

Read about how to create the resource definitions in Terraform