Improve the Terraform MR error messages
Summary
There are potential failures that we can have when trying to parse the Terraform JSON file. Currently our error messages do not help the user understand what went wrong and how they can solve the problem.
There a lot of reasons why the report can fail to generate. Currently, we can identify
- The api request failed
- The customer submitted a JSON file, but the file was formatted incorrectly. Example, a file should contain
{ create: <num>, update: <num>, delete: <num> }
, but instead contains{ differences: [...] }
- The customer submitted bad JSON. Example, the customer submitted a
.tf
file instead of submitting a.json
file. Attempting to read the JSON file fails. - Other unknown errors
Steps to reproduce
In a .gitlab-ci.yml
file add,
artifacts:
name: plan
reports:
terraform: <a-bad-plan-file>
Example Project
What is the current bug behavior?
Customers receive a flash error message, and changes display as Changes are unknown
They do not receive any information about what went wrong.
What is the expected correct behavior?
@mvrachni To propose error messages
Relevant logs and/or screenshots
Output of checks
(If you are reporting a bug on GitLab.com, write: This bug happens on GitLab.com)
Results of GitLab environment info
Expand for output related to GitLab environment info
(For installations with omnibus-gitlab package run and paste the output of: `sudo gitlab-rake gitlab:env:info`) (For installations from source run and paste the output of: `sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production`)
Results of GitLab application Check
Expand for output related to the GitLab application check
(For installations with omnibus-gitlab package run and paste the output of:
sudo gitlab-rake gitlab:check SANITIZE=true
)(For installations from source run and paste the output of:
sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production SANITIZE=true
)(we will only investigate if the tests are passing)
Possible fixes
- Update the way errors are surfaced (eg. replace the banner with in situ messaging).
- Update the text in the errors to make them more informative.
- Provide a link to documentation so that the users can easily find out how to fix the problem.
- Include a troubleshooting section for Terraform in the Terraform page in the docs.
Proposal
Case 1: Successful plan validation
A Terraform report was generated in your pipelines.
Reported Resource changes: [num] to add, [num] to change, [num] to delete.
Mock
Case 2: API request failed
@emilyring @mattkasa I need some help here figuring out the error and the proposed solution. Can you help me fill the text in red?
Mock
Case 3: JSON not found
A Terraform report was generated in your pipelines.
Reported resource changes: Unable to find Terraform Report. JSON file not found.
Expanded message
JSON file not found
Make sure that your JSON file extension is set to .json.
Go to documentation for help on setting up your Terraform report.
Mock
Case 4: Invalid JSON
A Terraform report was generated in your pipelines.
Reported resource changes: Unable to read Terraform Report. Invalid JSON format.
Expanded message
Invalid JSON format
Your JSON file should include { create: <number>, update: <number>, delete: <number> }
Go to documentation for help on setting up your Terraform report.
Mock
Case 5: Unknown Error
A Terraform report was generated in your pipelines.
Reported resource changes: Unable to retrieve data from the Terraform Report.
Expanded message
Unknown Error
Ensure that you have configured everything correctly [what could have gone wrong?]
Go to documentation for help on (what could have gone wrong, where to find it in docs?) (Would be good to have a Troubleshooting section).
Mock
/cc @emilyring @aqualls @nagyv-gitlab
This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.