Migrate to Flexible Boards

Flexible Boards introduce a new structure for organizing and displaying queries and Service Level Objectives (SLOs) in Honeycomb. This guide walks you through how to migrate your existing Boards to the Flexible Boards format using the Honeycomb UI, API, or Terraform.

Warning

On August 15, 2025, the Honeycomb API will stop supporting legacy Boards. Any Board API calls that use "type": "classic" or omit the type field will fail.

By August 29, 2025, Honeycomb will automatically migrate any remaining legacy Boards to the Flexible Boards format. During this process, query captions will move into the corresponding query’s description field.

Migration Methods

Choose the method that matches how you currently manage your Boards:

Use the Honeycomb UI to migrate Boards individually.
Update your Honeycomb API payload for Boards managed via the Honeycomb API.
Modify your Terraform configurations to use the honeycombio_flexible_board resource.

Migrate an Individual Board in the UI

The UI is the easiest option if you manage Boards manually. To migrate a Board using the Honeycomb UI:

Open the Board in the Honeycomb UI.
Select Preview as Flexible Board in the banner to review the updated layout.
If the preview looks correct, select Migrate board now to complete the migration.

Important

If your Board is managed via Terraform or the Honeycomb API, you must also update your API payload or Terraform configuration to use the Flexible Board format.

Migrate Boards Using the Honeycomb API

If you usee the API to create or update Boards, you need to update your request payload to match the Flexible Board format.

The Flexible Board format introduces two key changes:

The panels field replaces the queries and slos fields. To learn more about the panels field, visit the Honeycomb API documentation.
The type field, which represents the Board type, must be set to flexible. To learn more about the type field, visit the Honeycomb API documentation.

Warning

On August 15, 2025, the Honeycomb API will stop supporting legacy Boards. Any Board API calls that use "type": "classic" or omit the type field will fail.

To migrate a Create Board or Update Board request:

Set type:flexible in your request payload.
Remove these deprecated fields:
- column_layout
- style
Replace queries and slos fields with panels.

Example: Convert a Legacy Board Payload to Flexible Format

In this example, we show you how to migrate a legacy Board API payload containing the queries and slos fields to a Flexible Board payload.

The example legacy Board payload is as follows:

{
    "queries": [
      {
        "query_style": "graph",
        "dataset": "My Dataset",
        "query_id": "abc1234e",
        "query_annotation_id": "e4c24a35",
        "visualization_settings": {
          "hide_compare": false,
          "hide_hovers": false,
          "hide_markers": false,
          "utc_xaxis": false,
          "overlaid_charts": false,
          "charts": [
            {
              "chart_index": 0,
              "chart_type": "default",
              "log_scale": false,
              "omit_missing_values": false
            }
          ]
        }
      }
    ],
    "slos": [
      "BGfyxhFto",
      "dF1URaPGL"
    ]
  }

To convert the legacy Board payload:

Start with an empty panels array:
```
{
  "panels": []
}
```

Add your SLOs as panels. Each slo maps to a panel, so each SLO requires its own panel:

{
  "panels": [
    {
      "type": "slo",
      "slo_panel": {
        "slo_id": "BGfyxhFto"
      },
    },
    {
      "type": "slo",
      "slo_panel": {
        "slo_id": "dF1URaPGL"
      },
    },
  ]
}

Add your queries as panels. Each query also requires its own panel:

{
  "panels": [
    {
      "type": "slo",
      "slo_panel": {
        "slo_id": "BGfyxhFto"
      },
    },
    {
      "type": "slo",
      "slo_panel": {
        "slo_id": "dF1URaPGL"
      },
    },
    {
      "type": "query",
      "query_panel": {
        "query_id": "abc1234e",
        "query_annotation_id": "e4c24a35",
        "query_style": "graph",
        "visualization_settings": {
          "hide_compare": false,
          "hide_hovers": false,
          "hide_markers": false,
          "utc_xaxis": false,
          "overlaid_charts": false,
          "charts": [
            {
              "chart_index": 0,
              "chart_type": "default",
              "log_scale": false,
              "omit_missing_values": false
            }
          ]
        }
      }
    }
  ]
}

Once you update your API requests using this structure, you are ready to create and update Flexible Boards.

Migrate Boards Managed by HashiCorp Terraform

To migrate Boards defined in Terraform, update your Terraform configuration:

Upgrade to v0.35.0 or later of the Honeycomb.io Terraform provider.
Replace honeycombio_board blocks with honeycombio_flexible_board blocks.
Convert query and slo blocks to panel blocks.

Example: Convert Legacy Board to Flexible Board in Terraform

In this example, we show you how to update a Terraform configuration file to convert a legacy Board to a Flexible Board.

The example legacy Board Terraform configuration file is as follows:

data "honeycombio_query_specification" "latency_by_userid" {
  time_range = 86400
  breakdowns = ["app.user_id"]

  calculation {
    op     = "HEATMAP"
    column = "duration_ms"
  }

  calculation {
    op     = "P99"
    column = "duration_ms"
  }

  filter {
    column = "trace.parent_id"
    op     = "does-not-exist"
  }

  order {
    column = "duration_ms"
    op     = "P99"
    order  = "descending"
  }
}

resource "honeycombio_query" "latency_by_userid" {
  dataset    = var.dataset
  query_json = data.honeycombio_query_specification.latency_by_userid.json
}

resource "honeycombio_query_annotation" "latency_by_userid" {
  dataset     = var.dataset
  query_id    = honeycombio_query.latency_by_userid.id
  name        = "Latency by User"
  description = "A breakdown of trace latency by User over the last 24 hours"
}

resource "honeycombio_board" "overview" {
  name        = "Service Overview"
  description = "Information about Service Overview"

  query {
    caption             = "Latency by User"
    query_id            = honeycombio_query.latency_by_userid.id
    query_annotation_id = honeycombio_query_annotation.latency_by_userid.id

    graph_settings {
      utc_xaxis = true
    }
  }

  slo {
    id = var.slo_id
  }
}

To convert the example configuration file:

Create a honeycombio_flexible_board resource:

resource "honeycombio_flexible_board" "overview" {

  }

Add your Board’s name and description to your new resource:

Tip

The column_layout and style fields are not supported in teh honeycombio_flexible_board resource.

resource "honeycombio_flexible_board" "overview" {
    name        = "Service Overview"
    description = "Information about Service Overview"
}

Add SLO panels. For each of your slo blocks in honeycombio_board resource, create an equivalent panel block:

resource "honeycombio_flexible_board" "overview" {
  panel {
    type = "slo"
    slo_panel {
      slo_id = var.slo_id
    }
  }
}

Add query panels. For each of your query blocks in the honeycombio_board resource:

Create an equivalent panel block
Replace graph_settings blocks with visualization_settings blocks

Tip

The honeycomb_board legacy resource uses utc_xaxis while the honeycomb_flexible_board resource uses use_utc_xaxis.

To learn more about these changes, visit the Honeycomb Terraform Flexible Boards documentation.

resource "honeycombio_flexible_board" "overview" {
  panel {
    type = "slo"
    slo_panel {
      slo_id = var.slo_id
    }
  }
  panel {
    type = "query"
    query_panel {
      query_id = honeycombio_query.latency_by_userid.id
      query_annotation_id = honeycombio_query_annotation.latency_by_userid.id

      visualization_settings {
        use_utc_xaxis = true
      }
    }
  }
}

Replace your old honeycombio_board block with your new honeycombio_flexible_board block. Your final configuration should look similar to:

data "honeycombio_query_specification" "latency_by_userid" {
  time_range = 86400
  breakdowns = ["app.user_id"]

  calculation {
    op     = "HEATMAP"
    column = "duration_ms"
  }

  calculation {
    op     = "P99"
    column = "duration_ms"
  }

  filter {
    column = "trace.parent_id"
    op     = "does-not-exist"
  }

  order {
    column = "duration_ms"
    op     = "P99"
    order  = "descending"
  }
}

resource "honeycombio_query" "latency_by_userid" {
  dataset    = var.dataset
  query_json = data.honeycombio_query_specification.latency_by_userid.json
}

resource "honeycombio_query_annotation" "latency_by_userid" {
  dataset     = var.dataset
  query_id    = honeycombio_query.latency_by_userid.id
  name        = "Latency by User"
  description = "A breakdown of trace latency by User over the last 24 hours"
}

resource "honeycombio_flexible_board" "overview" {
  name        = "Service Overview"
  description = "Information about Service Overview"
  panel {
    type = "slo"
    slo_panel {
      slo_id = var.slo_id
    }
  }
  panel {
    type = "query"
    query_panel {
      query_id = honeycombio_query.latency_by_userid.id
      query_annotation_id = honeycombio_query_annotation.latency_by_userid.id

      visualization_settings {
        use_utc_xaxis = true
      }
    }
  }
}