Skip to main content

Dedicated OpenBao OpenTofu/Terraform Provider

Summary​

With the compatibility of OpenBao comes the option of using the HashiCorp Vault OpenTofu/Terraform provider. While this provider still works for most tasks, there has been increased friction with using it to configure an OpenBao instance. This is shown in issues like #339, hashicorp/terraform-provider-vault#2869 and discussions like #637.

This RFC aims to define a path to creating a dedicated provider for OpenBao.

Problem Statement​

With the divergence in features, fixes and settings of OpenBao from Vault, the HashiCorp-maintained Vault provider is starting to show this incompatibility as well. The profile/workflows system has no resources or datasources, the auth_login_aws isn't working (#339 (comment)) and fixes (hashicorp/terraform-provider-vault#2870) for similar issues (hashicorp/terraform-provider-vault#2869) don't get merged. This forces the user to adopt workarounds that lead to unwanted complexity and instability.

User-facing description​

OpenBao will provide a dedicated OpenTofu/Terraform provider as a soft-fork of the Vault provider that implements OpenBao-specific features and fixes, as well as upstream fixes that have not been merged yet.

The primary focus of this fork will not be to provide long term support for HashiCorp Vault, but instead give a way to migrate your state to OpenBao and its native provider.

Technical Description​

Partially taken from this comment by dc-tec, the provider should be a low-divergence soft fork from the Vault provider. The focus would be on providing a compatible provider that has a simple migration path from the Vault provider, while providing the missing features and fixes. The compatibility of upstream changes will be verified by acceptance tests against the current OpenBao release. Where applicable fixes for non-OpenBao specific issues should be send to the upstream provider.

The soft fork will be maintained as follows:

  1. Fork the upstream terraform-provider-vault repository into the openbao/ GitHub organization.
  2. After each upstream release, review and cherry-pick relevant patches into the fork. This process will start out manual and could be supported by automatic testing.

The provider will be released to the OpenTofu registry as well as the Terraform registry.

Migration Path​

As long as the fork stays low-divergence and keeps existing resource and data source names, migrating from the Vault provider requires no changes to individual resources in state:

  1. Update required_providers to point at the new provider source and version constraint.
  2. Run tofu init -upgrade.
  3. Run tofu state replace-provider registry.terraform.io/hashicorp/vault registry.opentofu.org/openbao/vault (illustrative address, exact registry namespace TBD) to rewrite the provider reference recorded in state, without touching the resources themselves.

This simple migration path only holds while the fork stays low-divergence. If a feature or fix eventually forces the fork to diverge in resource names or schemas, a migration path from hashicorp/vault to openbao/vault v1 (without the divergence and a simple migration path) to openbao/vault v2 (with the divergence and a possible more complex migration path) will need to be defined at that point, likely using moved blocks or tofu state mv for any resource addresses that change.

Rationale and alternatives​

The main rationale is to create a viable alternative to the Vault provider for configuring a OpenBao instance via OpenTofu/Terraform. Especially with keeping a simple migration path, this would improve the experience of people switching from the Vault provider to the dedicated provider.

Alternatives would be to stay with the status quo of having no dedicated TF provider.

Downsides​

  • Additional component that needs maintenance

Unresolved Questions​

Should we stay with the model of a low-divergence soft fork indefinitely?

#339 & #637