The Octopus Deploy Terraform Provider has officially reached version 1.0. This release introduces expanded capabilities, fixes long-standing bugs, and provides improved documentation.
In this post, I take you through the key updates and features included in this release.
Expanded Terraform Provider capabilities
Version 1.0 brings substantial improvements to managing Octopus Deploy resources through Terraform. Earlier versions of the Provider lacked support for creating all resource types available in the Octopus UI. We addressed this limitation, enabling comprehensive resource management directly from Terraform. While we support most resources now, there are still a few exclusions. These are intentional and thoroughly documented for transparency.
Clearer documentation with practical examples
For a better user experience, we updated the documentation to include detailed examples and best practices for using the Terraform Provider effectively. We outlined 5 key scenarios to guide you. The documentation found at the Terraform registry now also has examples for all data sources and resources.
Bug fixes and improvements
We resolved several long-standing bugs in this release. This improves the Provider and ensures a more stable and reliable experience.
- New deployment process resource: We made it easier to define and manage deployment processes by making each step its own resource. We also introduced a step order resource so you can easily manage the deployment process step order. You can find out more info on how it works in the official docs.
- Migration to Terraform framework: Transitioning from the Terraform SDK to the framework has improved safety, reliability, and adaptability for future updates.
- Adoption of semantic versioning (SemVer): The Provider now adheres strictly to SemVer principles. This helps you manage version changes more predictably.
Migration guidance
As this is a major version release, some breaking changes may require updates to existing configurations. To help with this transition, we have a comprehensive migration guide. Please review it carefully before upgrading your environments.
Provider migrated to Octopus Deploy repository
The Terraform Provider has always lived in our OctopusDeployLabs repository, which signalled that it was an experimental integration. We decided to move it to our official repository, elevating it as a core integration.
Version-controlled projects and the Terraform Provider
In the past, we have seen customers running into trouble when they tried to manage version-controlled Octopus Projects and Runbooks using Terraform.
Terraform’s paradigm of desired state doesn’t align well with the multiple states that can be represented in Git. It is difficult, for example, to effectively represent Git branches in Terraform configuration. Versions prior to 1.0 didn’t account for version-controlled Projects, and we saw customers running into difficult-to-understand error states as Git and Terraform clashed.
We believe that when version-controlling your configuration, there should be one authoritative source-of-truth: Terraform HCL, or Octopus OCL - but not both. From version 1.0 onwards, version-controlled elements of Octopus cannot be directly manipulated using the Terraform Provider. For example, if you attempt to change the Process of a version-controlled Project, the Provider will return an error. You can still manage non-version-controlled aspects such as the Project’s name, its Git repository settings, etc. But we will block attempts to make changes to anything OCL-backed via the Terraform Provider. You can read more in our Design Decisions section of the Provider documentation.
Conclusion
The v1.0 release solidifies the Octopus Deploy Terraform Provider as a robust tool for managing your Octopus instance as code. By simplifying resource management and improving documentation, teams can work more efficiently with the Terraform provider.
For detailed information on all changes and enhancements, please read the docs or visit the Terraform registry page for the Provider.
Happy deployments!
