Aiven Terraform Provider v4: What's new

Terraform is a powerful infrastructure as code (IaC) tool that allows developers and operators to manage infrastructure as if it were software. The importance of Terraform lies in its ability to help organizations automate and manage their infrastructure at scale, reducing the risk of human error, and ensuring consistency across environments. Recently, Aiven released version 4.0.0 of the Aiven Terraform Provider and there are some important changes that make it easier than ever to manage your data infrastructure using Terraform. In this blog post, we'll take a closer look at what's new in Aiven Terraform Provider version 4.X.

The path from Terraform SDKv2 to Terraform Plugin Framework

Terraform has released the new Terraform Plugin Framework as a replacement for the older Terraform Plugin SDKv2.

With Aiven Terraform Provider 4.X we have started migrating from the SDKv2 to the new framework. To facilitate the change, we’re using Terraform’s portability wrapper around Terraform Plugin SDKv2 to add support for the Terraform Plugin Framework.

Using strict types instead of strings

The biggest change in this release is that we have started to make schema fields use strict types instead of strings. In all previous versions of Aiven Terraform Provider, no matter what the actual type of the fields, we provided string interfaces to them.

For instance, public_access.prometheus was 1 (string) before and now it’s true (boolean). For up to date information on resource (or data source) types, please check the Aiven Terraform Provider docs.

Auto-upgrading of existing Terraform state

We’ve added functionality (the Aiven stateupgrader package) to this release which assists with upgrading resources from v3.x to v4.0.0. Starting from Aiven Terraform Provider v3.5.0, we’re generating user config types with fields, documentations, and so on, for new values. These user configs come with auto-completion support in your favorite code editor.

However, what happens to the existing values in your state files that were generated using previous versions of the provider? We couldn’t introduce this change to version 3.X as it would be a breaking change.

All of these values were strings, whereas from version 4.0.0 Aiven Terraform Provider expects all field values to have their actual API type. The stateupgrader package seamlessly upgrades the state of your Terraform program to convert string types into these types.

ip_filter, namespaces (for M3DB) and other deprecations

Terraform has a gradual process of deprecating any resource. In order to deprecate a resource, we need to mark it as deprecated on the next major release and then we can drop it completely on the major release after. For example, the aiven_database resource was marked as deprecated in version 3.X and is now dropped in version 4.X.

As part of using schema fields to use strict types, we marked ip_filter and namespaces (for M3DB) as deprecated in v4.X, and created aliases for them – ip_filter_string and namespaces_string respectively. In v5.X we will completely remove the ip_filter and namespaces fields, so we advise to move to the new ones now.

This change is made because those fields have been accepting multiple types in our API for a long while, and yet we still had no support for it on our side due to the way Terraform enforces strict types. Now, you can use ip_filter_object and namespaces_object instead, which allow for more granular customization of your resources. While the old fields are marked as deprecated, they still exist, and will only be replaced completely in version 5.X of Aiven Terraform Provider. Users will get a warning about resources that are marked as deprecated when trying to use them.

The following data sources and resources were marked as deprecated in version 3.X and are now removed:

• aiven_database, aiven_service_user, aiven_vpc_peering_connection
• aiven_flink_table and aiven_flink_job

What does this mean for our customers?

Aiven Terraform Provider is now compatible with Protocol Version 6 which is the latest protocol version. While the change will be transparent to you as a user, this allows us to provide long-term stability and will allow a faster bug fix cycle.

Let’s look at the following example. With Aiven Terraform Provider 3.X, you could assign "foo" (string) to an integer USER CONFIG option field. The resulting error from the Aiven Terraform Provider backend after you applied that manifest would require the Terraform client to make an API call to the Aiven platform. When we get to 5.X, the Terraform client itself will be able to produce the error.

With all these changes going on, it’s important to keep your Aiven Terraform Provider version up to date; at least for the major releases. For example, if you waited to upgrade directly from Aiven Terraform Provider v3.X to v5.X, the transition would not be as smooth or, worse case, might not even work at all. Remember to keep Aiven Terraform Provider updated to the latest version :)

What’s next?

At present, our engineers are updating resources to take advantage of the new Terraform Plugin Framework on the way to the next version of Aiven Terraform Provider. This will complete the shift away from Terraform Plugin SDK. In the Terraform Plugin SDK universe, a resource cannot have a null value – either the resource has a value or it’s empty – which means we have to do a lot of custom checks to determine the correct state of a resource. In the future, when we build Aiven Terraform Provider using the Terraform Plugin Framework, you will be able to define a null value for resources’ parameters, which means that we can get rid of hundreds of lines of existing code from the Aiven Terraform Provider core that were checking for null or empty values.

We cannot wait for you to build and manage your data infrastructure using Aiven Terraform Provider. Head over to the Terraform public registry to get started and take a look at the Aiven Terraform Cookbook for commonly used solutions. If you have any questions or feedback, don’t hesitate to reach out.