Provisioner Documentation: On_failure Spec Missing

by Admin 51 views
Provisioner Documentation Issue: Missing `on_failure` Specification

Hey guys, let's dive into a bit of a documentation snag I've run into regarding HashiCorp Terraform's provisioners. Specifically, the on_failure specification seems to have gone missing in action. For those of you who frequently deal with infrastructure-as-code (IaC), this is probably something you've encountered before. We're talking about the part of the documentation that explains what happens when a provisioner fails. It's a critical piece of information when you're trying to build robust and reliable deployments.

The Core Problem: Where Did on_failure Go?

The heart of the issue is this: the documentation for Terraform provisioners is missing crucial details, particularly concerning the allowed values for on_failure. I found myself scratching my head, trying to recall the exact behaviors and options available. The on_failure parameter is super important. It defines the action Terraform should take if a provisioner fails during the resource creation or modification process. The options available for on_failure determine the overall behavior of the deployment. Should Terraform continue, stop, or something else?

Initially, I was trying to reference older versions of the provisioner page to find the specification for on_failure. I was able to find a good source on the older documentation.

The absence of this information creates a gap in the documentation. Guys, we need to know whether the available options are continue, fail, or anything else. And if we don't know the options, how can we build systems that are resilient to failure? This missing piece impacts our ability to build robust and reliable infrastructure-as-code. It's really hard to know how to react to failures without knowing the failure behavior options.

Deep Dive: The Specific Request and Broader Concerns

The specific request here is clear: we need the allowed values for on_failure documented. But, my concerns are a little bit broader. I've got some overall concerns about the recent changes to the provisioners page. I have a sense that the documentation has been changed and it's not as descriptive as the older versions.

The documentation seems to have been replaced with tutorial-style copy. I don't know about you, but I would prefer documentation that gives me the information I need, in a quick, easily-referenced manner. When I want a tutorial, I'll go to a tutorial. The heading "Perform post-apply operations" instead of the original "Provisioners" title is one example.

Also, the "Provisioners are a last resort" section is incredibly important. This should not be removed and it should remain at the top of the provisioners documentation. We constantly refer back to this section. It's crucial for understanding the recommended practices around Terraform. We don't want to encourage users to use provisioners if there is any other method available. Using provisioners can lead to unpredictable behavior and make your infrastructure harder to manage.

Taking Action and Possible Solutions

I'm thinking about opening a PR to revert this page back to its last good version. This seemed to be around 1.10, but that seems kind of passive aggressive. And it doesn't solve the other pages where we're finding missing information. A revert could at least restore the information that we need. I think that restoring the original document is the most effective approach. This is because the original documentation was really very good. The older documentation clearly states the behavior options.

Another approach, of course, would be to work with the HashiCorp team. And, hopefully, we can resolve the problem, improve the documentation, and keep the community productive and efficient.

Recommendation

To address these issues, I recommend the following:

  1. Restore the original documentation: I think it would be great if the original documentation was restored.
  2. Add on_failure specification: Ensure the on_failure options, and behaviors are clearly documented.
  3. Maintain the "Provisioners are a last resort" section: This should remain at the top of the provisioner documentation.

By following these recommendations, we can improve the quality of the documentation and provide a better experience for Terraform users. This will lead to a better IaC implementation.

Conclusion

In conclusion, the missing on_failure specification in the Terraform provisioner documentation is a significant issue. This gap in the documentation creates challenges for users. By resolving this issue, we can ensure the Terraform documentation is useful, accurate, and easy to navigate. This is important for all of us. And together we can improve the Terraform experience for everyone! I hope the HashiCorp team can fix this documentation issue quickly, so we can continue to benefit from the power of IaC!