|
| 1 | +# Terraform Import SignalFx Dashboards |
| 2 | + |
| 3 | +This folder contains helper scripts for importing SignalFx dashboard groups. along with their linked dashboards and charts, into Terraform code. This tool enables users to create dashboards in the SignalFx UI and then convert them into infrastructure-as-code for better version control and automation. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +This script, given dashboard group ids, will generate mostly usable terraform code for dashboard groups, and any associated dashboards/charts. |
| 8 | + |
| 9 | +### Building the Docker Image |
| 10 | + |
| 11 | +To build docker image with the script binary and terraform installed, run the following command: |
| 12 | + |
| 13 | +```sh |
| 14 | +make build |
| 15 | +``` |
| 16 | + |
| 17 | +It is recommeded to pull the latest version of the repo and run build cmd before running the script. |
| 18 | + |
| 19 | +### Cleaning up the Docker Image |
| 20 | + |
| 21 | +To clean up the docker image, run the following command: |
| 22 | + |
| 23 | +```sh |
| 24 | +make clean |
| 25 | +``` |
| 26 | + |
| 27 | +### Viewing Options |
| 28 | + |
| 29 | +To look at the options for the script, run the following command: |
| 30 | + |
| 31 | +```sh |
| 32 | +docker run import-tf-script --help |
| 33 | +``` |
| 34 | + |
| 35 | +### Quick Start |
| 36 | + |
| 37 | +For a quick start cmd to generate terraform code for dashboard group, run the following make command: |
| 38 | + |
| 39 | +```sh |
| 40 | +SIGNALFX_AUTH_TOKEN=<SIGNALFX API TOKEN> GROUP_IDS=<ID1,ID2> RELATIVE_DIR_PATH=resources/Synthetics-Dashboards make import-dashboard-group |
| 41 | +``` |
| 42 | + |
| 43 | +This will generate a bunch of `.tf` files. There will be a file for each dashboard group, and a different file for dashboards in the groups. The dashboard file will have the dashboard and chart resources. |
| 44 | + |
| 45 | +### Example to run with custom options |
| 46 | + |
| 47 | +```sh |
| 48 | +cd ${REPO_ROOT} |
| 49 | +docker run -v $(pwd):/app import-tf-script \ |
| 50 | +--auth-token <TOKEN> \ |
| 51 | +--api-url <API URL> \ |
| 52 | +--group-ids <ID1,ID2> \ |
| 53 | +--dir /app/resources/APM \ |
| 54 | +--allow-chart-name-conflict |
| 55 | +``` |
| 56 | + |
| 57 | +### Additional Notes |
| 58 | + |
| 59 | +- The resource type and name must be unique within a TF module. Changing the resource name will be treated as a recreate by TF, which means dashboard/chart urls will be updated if their corresponding resource name is changed. We derive the TF resource name from the SignalFx object names. It is recommended to clean-up sfx names before the first import to avoid recreates when rerunning the script to import updates to dashboards. The resource names generated for the different resource types are explained below. The names will have non-alphanumeric characters replaced with `_`: |
| 60 | + - `signalfx_dashboard_group`: `<dashboard group name>` |
| 61 | + - `signalfx_dashboard`: `<dashboard group resource name>_<dashboard name>` |
| 62 | + - `signalfx_*_chart`: `<dashboard resource name>_<chart name>` |
| 63 | + - In case of duplicate chart type and name combos in a dashboards, the script will append a number to the chart's name attribute and the chart resource name to make it unique if the option `--allow-chart-name-conflict` is provided. The additional index in the conflicting chart name on the first run of the script, will ensure the re-runs of the script does not cause TF to recreate chart resource, keeping the url same. If the option is not provided, the script will exit with an error on encountering conflicts. It is recommended to rename charts to make them unique before running the script. |
| 64 | + - For `text` charts, the script will fallback to the chart description to generate chart resource name if the chart name is empty. This is useful for Text charts which usually are untitled. Users are recommended to update their text charts to add some small unique description. We recommend using descriptions for text chart since titles for text charts might not be desirable in the UI. |
| 65 | +- The `dashboard_group` will only have READ permissions for the org, and the dashboard resource will inherit the group's permission. You can edit the `signalfx_dashboard_group` resource to add more permission blocks. Make sure you update the permissions when you create these for the first time since a session token of an administrator is needed to update write permissions of existing groups. |
| 66 | +- The script will overwrite any existing files in the directory with same names. If you want to keep the existing files, move them to a different directory before running the script. |
| 67 | +- Charts with detector links will have their `program_text` updated to replace the detector_id with terraform resource reference to the detector. The reference is in the format `signalfx_detector.<detector resource name>.id`. The detector resource name is generated by replacing non-alphanumeric characters with `_` in the detector name. If this resource is not found, plan will fail with an error. You can update the detector resource reference in the chart resource to fix the error. |
| 68 | +- The script orders the resources alphabetically by their resource type and name in the final terraform file. This is to ensure the order of resources is kind of deterministic and does not change between reruns of import script generating unnecessary diffs in the PRs. |
0 commit comments