elastic / elastic/terraform-provider-elasticstack

[FEATURE] Add support for Kibana Dashboards API **Search** endpoint to enable `terraform query` / bulk import for dashboards

Open
#2,008 1 comment 1 reaction 0 assignees View on GitHub
needs-research triaged
Dominant language
Go
Stars
209
Forks
150
Avg merge
22h 58m
Merged PRs (30d)
172

Description

### Name of the resource

elasticstack_kibana_dashboard

### Describe new functionality

## Summary
Terraform v1.14 introduced `terraform query` and `list` blocks to **discover unmanaged resources** and optionally **generate `resource` + `import` blocks** for bulk import ([Terraform “Import existing resources in bulk” docs](https://developer.hashicorp.com/terraform/language/v1.14.x/import/bulk?page=import&page=bulk)).

To support this workflow for Kibana dashboards (`elasticstack_kibana_dashboard`), the provider needs a way to **enumerate dashboards** in a space. Kibana’s Dashboards API `GET /api/dashboards` (space-aware via `/s/{space_id}/api/dashboards`) is the natural endpoint to back a provider `list` implementation.

## Why this is needed
- **Bulk onboarding**: Many users start with existing Kibana content and want to bring it under Terraform management. Manually collecting dashboard IDs and writing dozens/hundreds of `import` blocks is tedious and error-prone.
- **Terraform-native workflow**: With `terraform query -generate-config-out=generated.tf`, Terraform can generate importable configuration *if the provider can list resources and return identities*.
- **Dashboards require a search/list API**: The provider can already CRUD a dashboard once you know its ID, but without a Search endpoint there’s no straightforward way to discover “all dashboards in space X”, filter by title, or filter by tags.
- **Configuration generation requires optional full reads**: When `include_resource = true` is set in a `list` block, Terraform expects the provider to return resource attributes as well as identities so it can generate more complete `resource` blocks.

## What I built as a PoC (reference)
I have a [PoC draft PR](https://github.com/elastic/terraform-provider-elasticstack/pull/2007) on my fork that demonstrates the intended UX:
- a `list "elasticstack_kibana_dashboard" "all" { ... }` query that pages through dashboards using the Dashboards Search endpoint
- optional `include_resource = true` that fetches full dashboard details for config generation
- composite identity format: `/`
- **note** this PoC currently uses the POST /api/dashboards/search endpoint which is [being replaced by the GET /api/dashboards endpoint](https://github.com/elastic/kibana/pull/258025). After https://github.com/elastic/kibana/pull/258025 is merged, I can update the PoC.

## Proposed change
Add provider support for the Kibana Dashboards API Search endpoint and wire it into Terraform’s `list`/`query` workflow.

High-level implementation notes:
- **Endpoint**: `GET /api/dashboards` (and `/s/{space_id}/api/dashboards` for non-default spaces)
- **Paging**: use `page` and `per_page` to iterate until fewer than `per_page` results are returned; respect Terraform’s `limit`
- **Filters**: `query` (simple_query_string over title/description), `tags`, `excluded_tags`
- **Request requirements**: Kibana currently appears to require `x-elastic-internal-origin: Kibana` and query params like `apiVersion=1` (and possibly `allowUnmappedKeys=true`) for Dashboard API calls
- **Identity**: return a stable identity compatible with existing import semantics (`/`)

## Acceptance criteria
- [ ] The generated Kibana client (`kbapi`) includes the Dashboards Search API (`GET /api/dashboards`) and response types.
- [ ] The provider exposes a `list` implementation for `elasticstack_kibana_dashboard` that:
- [ ] returns identities for discovered dashboards
- [ ] supports paging and respects Terraform `limit`
- [ ] optionally returns full resource data when `include_resource = true` (for `-generate-config-out`)
- [ ] Add an example `.tfquery.hcl` showing how to run:
- [ ] `terraform query`
- [ ] `terraform query -generate-config-out=generated.tf`
- [ ] Add basic tests for identity schema / list behavior

## User impact / outcome
Once implemented, users can:
- run `terraform query` to discover existing dashboards in a space
- run `terraform query -generate-config-out=generated.tf` to bootstrap a local Terraform configuration
- users can use the `generated.tf` file to migrate and manage their dashboards using Terraform.

This makes onboarding existing Kibana dashboards to Terraform **fast, repeatable, and Terraform-native**.

### Version Introduced

9.4.0

### Anything else?

_No response_

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the generated kbapi client and the existing elasticstack_kibana_dashboard CRUD behavior, then review the linked PoC draft PR. Confirm the GET /api/dashboards API details and implement the list workflow with paging, filters, identities, optional full resource data, tests, and a .tfquery.hcl example; done means all listed acceptance criteria pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.