How to Import Existing ilert Resources into Terraform

Welcome to our detailed guide, which will help you incorporate your current ilert configurations for incident management into Terraform. Here, you will find a step-by-step tutorial to import your existing ilert resources to the Infrastructure as Code project and recommendations from our engineering team on best practices to maintain consistency across your infrastructure and incident management processes.

‍

If you are yet to start incorporating IaC practices in your organization, we recommend beginning with this ilert Terraform provider overview.

What problem do we solve?

The most common case is when users start their journey with the ilert incident management platform through the user interface and incorporate their established setup into Infrastructure as Code practices later. The ilert UI is typically more user-friendly and intuitive, making it quicker for engineers to create and configure resources like alert policies or on-call schedules. For instance, when experimenting with different settings or making quick changes, using the UI is faster and more straightforward than writing and applying Terraform code. On the other hand, once a resource configuration is stable and well-understood, engineers might prefer to codify it in Terraform for better consistency, version control, and automation across different environments.

‍

Even companies utilizing ilert with IaC practices for years might use a combination of ilert UI and Terraform based on factors like ease of use, the immediacy of needs, the complexity of resource management, and the team's experience level with Terraform. The hybrid approach allows flexibility during initial setup phases or when manual intervention is necessary, while Terraform is favored for long-term consistency and automation.

‍

So, it's perfectly fine that not all your ilert resources are already a part of your Terraform project. However, importing existing resources into an IaC project might be a bit tricky. Common problems are duplicates (newly created resources) in Terraform instead of the import of existing ones or errors like

‍

Error: Bad request: api respond with status code: 400, error code: ERROR, message: The email '[example@example.com]' is already used by user 1234567

‍

Let's see how to import existing ilert resources smoothly and avoid these issues.

Step 1: Identify an ilert resource ID you want to import

Let's see how to import an alert source created in the ilert interface into Terraform. Start with identifying a unique ID. You can do it directly in the UI or by using the API. 

Method 1: Via ilert UI

1. Log into your ilert account and navigate Alert sources in the top menu.
2. Find the alert source you want to import from the list or use a search field.  
3. Click on the alert source's name to view its details. Then navigate the URL: https://example.ilert.com/source/view?id=1234567. Copy the numbers at the end; this is the ID you need.

Method 2: Via API

1. Ensure you have an API key that can be generated from your ilert account settings under the API section.
2. Make a GET request to the ilert API:
   GET https://api.ilert.com/api/v1/alert-sources‍
3. The API response will be in JSON format and include all alert sources' details, including their IDs. Look for the "id" field.

Step 2: Setup a Terraform block

In Terraform, a "block" refers to a section of code that defines a specific piece of configuration. Blocks are the building units in Terraform configuration files. Each block usually starts with a keyword that specifies what type of resource or setting you are configuring, followed by the details of that configuration enclosed in curly braces {}.

‍

In your Terraform configuration file (e.g., main.tf), you would define a resource block for the alert source. 

‍

resource "ilert_alert_source" "example_alert_source" {
  name        = "Critical Server Alerts"
  integration_type = "API"
  escalation_policy_id = 1234  # Replace with the actual escalation policy ID
  auto_resolve_timeout = 900   # Time in seconds before automatically resolving the alert

  email_notification {
    email = "alerts@example.com"
  }

  sms_notification {
    phone_number = "+1234567890"
  }

}

Step 3: Execute the Terraform Import

In your terminal or command line, navigate to the directory containing your Terraform configuration files. Then, execute the following command:

‍

terraform import ilert_alert_source.example_alert_source <ALERT_SOURCE_ID>

‍

"ilert_alert_source.example_alert_source" refers to the Terraform resource you defined in your ".tf" file. Replace <ALERT_SOURCE_ID> with the actual ID of the alert source from ilert that you noted earlier.

‍

Note that while in 99% of the cases, the import keys (identifiers) are the same as the entity’s ID, they sometimes might differ. You can find the import description at the bottom of each resource in the ilert Terraform provider's documentation.

Step 4: Complete the Configuration

After importing, Terraform knows about the existing alert source. However, the configuration file itself might not have all the details yet.

‍

Execute a "terraform plan" to see what Terraform recognizes about the imported resource. This command will show you the current state of the resource compared to your configuration.

‍

Based on the output of a terraform plan, update the resource block in your .tf file with the appropriate configurations. 

‍

Following these steps, you successfully import an existing ilert alert source into Terraform, enabling you to manage it as part of your Infrastructure as Code (IaC) setup. This process helps maintain consistency, allows easier updates, and integrates the alert source into your version-controlled infrastructure management.

Best practices and recommendations

Should I generate all the ilert entities via Terraform? How do other teams automate setting up and configuring their incident management workflows within IaC practices? We addressed these questions to ilert's CTO, Christian.

‍

‍"It largely depends on the company structure.
‍
If you have a centralized Ops team that handles tasks such as user and team synchronization (via Terraform, API, SSO provisioning, etc.), then you could theoretically also consider having that team manage all other resources, especially policies, alert sources and alert actions.

However, we advise against this if there are independent responder teams. In our opinion, it’s best practice for team-relevant resources to be managed by the team members themselves. In larger organizations, we also see teams with DevOps skills who manage this individually through their own Terraform configurations, but some teams exclusively use the ilert UI.

In cases with responders who do not directly interact with the resources and only deal with alerts and incidents or in organizations where the number of alert sources remains manageable, we also see customers using complete Terraform configurations for all account resources.

There are even setups where Ops teams have fully automated the ilert onboarding, starting with assigning the correct escalation policy to alert sources based on, for example, Prometheus labels. Another example is DevOps teams submitting pull requests to the Terraform repository to provision themselves independently via GitHub actions.

Personally, I believe that centralized Ops teams also benefit when responders take responsibility for their own alert sources and services because this leads to greater engagement with the platform, which in turn results in better workflows and faster response times."