Manage IAM keys with Terraform
This topic describes how to use the Imply Lumi Terraform provider to manage IAM keys. IAM keys authenticate clients, such as Splunk forwarders and search heads, to send and search events. With Terraform, you can define keys and their integration settings in configuration files and track their changes in version control.
For example, as you send more types of events to Lumi, you might map additional Splunk Common Information Model (CIM) data models, such as Authentication or Network Traffic, on your IAM key. Version control lets you review these mapping changes before you apply them and roll them back if searches return unexpected results.
Don't confuse the IAM keys you manage in Terraform with the IAM key that authenticates the provider to Lumi.
The IAM key token that authenticates the provider is stored in LUMI_IAM_KEY_TOKEN.
The authenticating key only has access to its own managed keys, not other keys created in the Lumi UI or managed by a different provider key.
Prerequisites
Before you proceed, complete the steps in Install the Lumi Terraform provider.
The provider requires you to set app_endpoint or the environment variable LUMI_APP_ENDPOINT.
See Provider configuration for details.
Manage IAM keys
The resource lumi_iam_key manages an IAM key, including its integrations and integration attributes.
Example
The following resource creates an IAM key that enables Splunk federated search with the spl integration.
The integration block contains the data model attribute datamodels, which maps Splunk data model fields to Lumi event fields.
resource "lumi_iam_key" "search_head" {
name = "search-head-1"
description = "SPL access for the primary search head"
spl = {
index_allow_list = ["web", "auth"]
datamodels = {
Web = {
Web = {
filter = "index=web"
fields = { dest = "host", status = "status", http_method = "method" }
}
}
Authentication = {
Authentication = {
filter = "index=auth"
fields = { user = "user", src = "src_ip", action = "action" }
child_datasets = {
Failed_Authentication = { filter = "action=failure", fields = {} }
}
}
}
}
}
}
output "search_head_token" {
value = lumi_iam_key.search_head.token
sensitive = true
}
Resource schema
| Name | Type | Description |
|---|---|---|
| Required | ||
name | String | Name of the IAM key. |
| Optional | ||
description | String | Description of the IAM key. Omit for no description. Can't be an empty string. |
Integration name, such as spl | Object | Integration to enable on the IAM key, with its attributes. See Integration schema. |
| Read-only | ||
id | String | Lumi ID for the IAM key. |
token | String | Secret token for the IAM key. Lumi returns the token only when it creates the key, and Terraform stores it in state. Mark any output that uses it as sensitive, and treat the state file as a credential store. |
managed_by | String | ID of the IAM key that authenticates the provider. |
created_on | String | When Lumi created the IAM key. |
last_modified_on | String | When the IAM key was last changed. |
Integration schema
You can define one or more objects to enable integrations on the managed IAM key:
hec: Splunk HECs2s: Splunktcpoutandhttpouts3: Splunk S3 ingest actionss3_pull: S3 pullspl: Splunk federated searchotel: OpenTelemetry protocolmcp: Model Context Protocoljdbc: Tableauloki: Grafana Loki
The s3, otel, mcp, and jdbc integrations have no attributes.
To enable one, set it to an empty object, such as otel = {}.
Federated search integration
The spl object enables Splunk federated search and sets its federated search attributes.
All attributes are optional. To use the defaults, set spl = {}.
index_allow_list: Allowed indexes for queries that don't use a data model, such as["web", "auth"].
Omit to allow all indexes, or set to an empty array[]to allow none.pool_id: Virtual compute pool for the key's searches.
Use__defaultfor the default pool.timeout: Query timeout in milliseconds, from300000(5 minutes) to3600000(60 minutes).
The Lumi UI sets this value in minutes.datamodels: Data model field mappings for transparent mode.
Each dataset takesfields(required, can be{}),filter, andchild_datasets.
The Lumi UI uses childDatasets for nested datasets. In Terraform, use child_datasets.
Load definitions from files
Instead of writing data models inline, you can store them in a separate file and reference it from your Terraform configuration.
This keeps your .tf files short and lets you review data model changes on their own.
The datamodels attribute expects an object.
Use jsondecode or yamldecode to load data models from local files.
The following example loads the data model mappings from datamodels.json, in the same directory as your Terraform configuration:
resource "lumi_iam_key" "search_head" {
name = "search-head-1"
spl = {
index_allow_list = ["web", "auth"]
datamodels = jsondecode(file("${path.module}/datamodels.json"))
}
}
Details
Example datamodels.json
This file contains the same mappings as the inline example.
It uses child_datasets, not the childDatasets format from the Lumi UI.{
"Web": {
"Web": {
"filter": "index=web",
"fields": {
"dest": "host",
"status": "status",
"http_method": "method"
}
}
},
"Authentication": {
"Authentication": {
"filter": "index=auth",
"fields": {
"user": "user",
"src": "src_ip",
"action": "action"
},
"child_datasets": {
"Failed_Authentication": {
"filter": "action=failure",
"fields": {}
}
}
}
}
}
Import IAM keys
You can import IAM keys that you previously created using the Terraform provider with the same authenticating key. This applies when you created the key in Terraform, removed it from state, and want to manage it with Terraform again.
To import an existing IAM key:
-
Write an empty resource block to your configuration. For example:
resource "lumi_iam_key" "mykey" {} -
Get the key ID from the Lumi UI:
- Click Keys from the navigation menu.
- Select your key.
- Copy the Key ID value.
-
Run
terraform importwith your resource name and ID. For example:terraform import lumi_iam_key.mykey 55f0a26d-c09c-4b0a-a640-58102824d995 -
Update the resource definition in your Terraform configuration. Set arguments for the
lumi_iam_keyresource to align with the current or intended state of the key.
For more details on importing resources, see the HashiCorp documentation.
Secrets in Terraform state
Lumi only returns an IAM key token only in the response that creates the key.
When you import a key, Terraform can't retrieve its token, so the token attribute is empty in Terraform state.
You can still manage the key with Terraform, but you can't reference its token in outputs or other resources.
To view the token, go to the key's details page in the Lumi UI.
This also applies to an IAM key that enables the S3 pull integration and configures authentication with an access key.
After you import the key, update the s3_pull block to set aws_access_key_secret then apply the change.
Otherwise, the next apply removes the secret from the key.
Delete IAM keys
When you delete an IAM key from Lumi, any client that authenticates with the key immediately loses access to Lumi.
Remove the IAM key block from your configuration, then run terraform apply.
To prevent a production-level key from deletion, add the following block inside the resource:
lifecycle {
prevent_destroy = true
}
When you stop managing an IAM key in Terraform without deleting it from Lumi, the key stays in Lumi, and clients that use it keep their access. Do one of the following:
- Use a
removedblock withdestroy = false. Available in Terraform 1.7 or later. - Run
terraform state rmfor your resource type and name.
Unsupported settings
The following settings can only be configured in the Lumi UI and aren't available as resource arguments:
- System attributes
envandteam - IP allowlist
Learn more
For more information, see the following topics:
- IAM keys to learn about how IAM keys work in Lumi.
- IAM key attribute reference for a list of integration attributes.