tfsdk: Migrate data source, provider, and resource types into new Go packages #432
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bflad
added
breaking-change
|
Go documentation for latest commit: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework@v0.10.1-0.20220729031038-a5443541a405 Real world updates to terraform-provider-corner: hashicorp/terraform-provider-corner#79 |
bendbennett
approved these changes
Jul 29, 2022
detro
approved these changes
Jul 29, 2022
There was a problem hiding this comment.
Reviewing every change would be impossible, so thank you so much for the summary of what happened (and why).
I like a lot the tables you provided to quickly reference "what it was" and "what's now".
Also, to seal the deal, I looked at how the new godoc would look like, and I think there is little to no discussion: a massive improvement for the developer to consult.
🚀
bflad
added a commit
that referenced
this pull request
Jul 29, 2022
…packages Reference: #132 Reference: #365 Reference: #366 Since the framework's initial release, the `tfsdk` Go package has been a monolithic collection of various provider concepts, including but not limited to handling of data sources, providers, resources, schemas, schema data (such as `Config`, `Plan`, and `State`), and various other helpers. For framework maintainers, this monolithic package has made implementations difficult for certain enhancements, such as import cycles. For provider developers, this monolithic package has been difficult to navigate in the Go documentation. This change represents the first major provider coding paradigm shift to colocate related concepts into their own Go packages, starting with new top-level `datasource`, `provider`, and `resource` packages. This particular change and method (no deprecation period) was not desired, but it was unavoidable due to the interconnectedness of the `tfsdk` package and due to the amount of effort it would require to attempt to support both the old and new types. This change is necessary to complete before there are additional code compatibility promises added to this Go module, such as a version 1.0.0 release or release candidate. This type of change is not taken lightly, as it is quite disruptive for existing provider codebases. On the surface, this change may look fairly unbeneficial for provider developers other than the easier discoverability and reduced wordiness, however it is required to unblock other future refactoring and enhancement efforts in the framework. It is unclear at the time of writing whether splitting out the other concepts from the `tfsdk` package, such as schemas, will present the same issues. Regardless, any other major changes will be spread across releases. Provider developers should be able to update their code using find and replace operations using the tables below. To reduce framework maintainer review burden, all code migrations were lift and shift operations while most code and documentation updates were find and replace operations. | Prior tfsdk Package Type | New provider Package Type | | --- | --- | | `tfsdk.ConfigureProviderRequest` | `provider.ConfigureRequest` | | `tfsdk.ConfigureProviderResponse` | `provider.ConfigureResponse` | | `tfsdk.Provider` | `provider.Provider` | | `tfsdk.ProviderConfigValidator` | `provider.ConfigValidator` | | `tfsdk.ProviderWithConfigValidators` | `provider.ProviderWithConfigValidators` | | `tfsdk.ProviderWithProviderMeta` | `provider.ProviderWithMetaSchema` (note naming realignment) | | `tfsdk.ProviderWithValidateConfig` | `provider.ProviderWithValidateConfig` | | `tfsdk.ValidateProviderConfigRequest` | `provider.ValidateConfigRequest` | | `tfsdk.ValidateProviderConfigResponse` | `provider.ValidateConfigResponse` | The `DataSourceType` abstraction migrates to the `provider` package since it relates to data that must be populated before the provider is configured as well as being passed the `Provider` interface, which can be converted into a concrete Go type when creating a `DataSource`. Other data source concept types are migrated to a new `datasource` package. | Prior tfsdk Package Type | New provider Package Type | | --- | --- | | `tfsdk.DataSourceType` | `provider.DataSourceType` | | Prior tfsdk Package Type | New datasource Package Type | | --- | --- | | `tfsdk.DataSource` | `datasource.DataSource` | | `tfsdk.DataSourceConfigValidator` | `datasource.ConfigValidator` | | `tfsdk.DataSourceWithConfigValidators` | `datasource.DataSourceWithConfigValidators` | | `tfsdk.DataSourceWithValidateConfig` | `datasource.DataSourceWithValidateConfig` | | `tfsdk.ReadDataSourceRequest` | `datasource.ReadRequest` | | `tfsdk.ReadDataSourceResponse` | `datasource.ReadResponse` | | `tfsdk.ValidateDataSourceConfigRequest` | `datasource.ValidateConfigRequest` | | `tfsdk.ValidateDataSourceConfigResponse` | `datasource.ValidateConfigResponse` | The `ResourceType` abstraction migrates to the `provider` package since it relates to data that must be populated before the provider is configured as well as being passed the `Provider` interface, which can be converted into a concrete Go type when creating a `Resource`. Other resource concept types are migrated to a new `resource` package. Additionally, the `tfsdk.ResourceImportStatePassthroughID()` function has been migrated to `resource.ImportStatePassthroughID()`. | Prior tfsdk Package Type | New provider Package Type | | --- | --- | | `tfsdk.ResourceType` | `provider.ResourceType` | | Prior tfsdk Package Type | New resource Package Type | | --- | --- | | `tfsdk.CreateResourceRequest` | `resource.CreateRequest` | | `tfsdk.CreateResourceResponse` | `resource.CreateResponse` | | `tfsdk.DeleteResourceRequest` | `resource.DeleteRequest` | | `tfsdk.DeleteResourceResponse` | `resource.DeleteResponse` | | `tfsdk.ImportResourceStateRequest` | `resource.ImportStateRequest` | | `tfsdk.ImportResourceStateResponse` | `resource.ImportStateResponse` | | `tfsdk.ModifyResourcePlanRequest` | `resource.ModifyPlanRequest` | | `tfsdk.ModifyResourcePlanResponse` | `resource.ModifyPlanResponse` | | `tfsdk.ReadResourceRequest` | `resource.ReadRequest` | | `tfsdk.ReadResourceResponse` | `resource.ReadResponse` | | `tfsdk.Resource` | `resource.Resource` | | `tfsdk.ResourceConfigValidator` | `resource.ConfigValidator` | | `tfsdk.ResourceWithConfigValidators` | `resource.ResourceWithConfigValidators` | | `tfsdk.ResourceWithImportState` | `resource.ResourceWithImportState` | | `tfsdk.ResourceWithModifyPlan` | `resource.ResourceWithModifyPlan` | | `tfsdk.ResourceWithUpgradeState` | `resource.ResourceWithUpgradeState` | | `tfsdk.ResourceWithValidateConfig` | `resource.ResourceWithValidateConfig` | | `tfsdk.UpdateResourceRequest` | `resource.UpdateRequest` | | `tfsdk.UpdateResourceResponse` | `resource.UpdateResponse` | | `tfsdk.UpgradeResourceStateRequest` | `resource.UpgradeStateRequest` | | `tfsdk.UpgradeResourceStateResponse` | `resource.UpgradeStateResponse` | | `tfsdk.ValidateResourceConfigRequest` | `resource.ValidateConfigRequest` | | `tfsdk.ValidateResourceConfigResponse` | `resource.ValidateConfigResponse` |
bflad
force-pushed
the
bflad/dspr-refactoring
branch
from
144f4ba to
d56ea09
Compare
|
Overall this LGTM to me 🚀. |
|
Discussed with other internal stakeholders and merging so we can continue other efforts. |
bflad
added a commit
that referenced
this pull request
Aug 2, 2022
…ateForUnknown()` plan modifier functions to the `resource` package Reference: #132 Reference: #365 Reference: #366 Reference: #432 Plan modification in the framework is a concept that only applies to managed resources via the protocol `PlanResourceChange` RPC. Following the migration of other `tfsdk` package types into separate `datasource`, `provider`, and `resource` packages, this change migrates the `RequiresReplace()`, `RequiresReplaceIf()` and `UseStateForUnknown()` plan modifier functions into the `resource` package. This change should be bundled in the same release as the package refactoring since it is similar in nature. This change has two immediate benefits: - Aligning the Go package placement tof these functions o hint to provider developers that these are only intended for managed resources. - For future refactoring this removes additional schema-based code imports from the `tfsdk` package, which could enable refactoring the schema logic into internal packages with potentially less breaking changes for provider developers by removing a source of import cycles. Provider developers should be able to update their code using find and replace operations using the table below: | Prior tfsdk Package Function | New resource Package Function | | --- | --- | | `tfsdk.RequiresReplace` | `resource.RequiresReplace` | | `tfsdk.RequiresReplaceIf` | `resource.RequiresReplaceIf` | | `tfsdk.UseStateForUnknown` | `resource.UseStateForUnknown` | To reduce framework maintainer review burden, this code migrations was primarily a lift and shift operation while most code and documentation updates were find and replace operations. The modifier types were unexported as exposing them should not be beneficial for provider developers and should help reduce the Go documentation surface area. The plan modifier unit testing was updated to use a `_test` package so it is verifying only exported functionality.
bflad
added a commit
that referenced
this pull request
Aug 2, 2022
…ateForUnknown()` plan modifier functions to the `resource` package (#434) Reference: #132 Reference: #365 Reference: #366 Reference: #432 Plan modification in the framework is a concept that only applies to managed resources via the protocol `PlanResourceChange` RPC. Following the migration of other `tfsdk` package types into separate `datasource`, `provider`, and `resource` packages, this change migrates the `RequiresReplace()`, `RequiresReplaceIf()` and `UseStateForUnknown()` plan modifier functions into the `resource` package. This change should be bundled in the same release as the package refactoring since it is similar in nature. This change has two immediate benefits: - Aligning the Go package placement tof these functions o hint to provider developers that these are only intended for managed resources. - For future refactoring this removes additional schema-based code imports from the `tfsdk` package, which could enable refactoring the schema logic into internal packages with potentially less breaking changes for provider developers by removing a source of import cycles. Provider developers should be able to update their code using find and replace operations using the table below: | Prior tfsdk Package Function | New resource Package Function | | --- | --- | | `tfsdk.RequiresReplace` | `resource.RequiresReplace` | | `tfsdk.RequiresReplaceIf` | `resource.RequiresReplaceIf` | | `tfsdk.UseStateForUnknown` | `resource.UseStateForUnknown` | To reduce framework maintainer review burden, this code migrations was primarily a lift and shift operation while most code and documentation updates were find and replace operations. The modifier types were unexported as exposing them should not be beneficial for provider developers and should help reduce the Go documentation surface area. The plan modifier unit testing was updated to use a `_test` package so it is verifying only exported functionality.
bflad
added a commit
that referenced
this pull request
Aug 2, 2022
…resource package migration Reference: #432
gonzolino
added a commit
to gonzolino/terraform-provider-tado
that referenced
this pull request
Aug 16, 2022
See [1] for more information on these changes. [1]: hashicorp/terraform-plugin-framework#432
gonzolino
added a commit
to gonzolino/terraform-provider-tado
that referenced
this pull request
Aug 16, 2022
See [1] for more information on these changes. [1]: hashicorp/terraform-plugin-framework#432
gonzolino
added a commit
to gonzolino/terraform-provider-powerdns
that referenced
this pull request
Aug 17, 2022
See [1] for more information on these changes. [1]: hashicorp/terraform-plugin-framework#432
ewbankkit
added a commit
to hashicorp/terraform-provider-aws
that referenced
this pull request
Aug 17, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-aws
that referenced
this pull request
Aug 17, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
ewbankkit
added a commit
to hashicorp/terraform-provider-awscc
that referenced
this pull request
Aug 18, 2022
|
I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Reference: #132
Reference: #365
Reference: #366
Since the framework's initial release, the
tfsdkGo package has been a monolithic collection of various provider concepts, including but not limited to handling of data sources, providers, resources, schemas, schema data (such asConfig,Plan, andState), and various other helpers. For framework maintainers, this monolithic package has made implementations difficult for certain enhancements, such as import cycles. For provider developers, this monolithic package has been difficult to navigate in the Go documentation. This change represents the first major provider coding paradigm shift to colocate related concepts into their own Go packages, starting with new top-leveldatasource,provider, andresourcepackages.This particular change and method (no deprecation period) was not desired, but it was unavoidable due to the interconnectedness of the
tfsdkpackage and due to the amount of effort it would require to attempt to support both the old and new types. This change is necessary to complete before there are additional code compatibility promises added to this Go module, such as a version 1.0.0 release or release candidate.This type of change is not taken lightly, as it is quite disruptive for existing provider codebases. On the surface, this change may look fairly unbeneficial for provider developers other than the easier discoverability and reduced wordiness, however it is required to unblock other future refactoring and enhancement efforts in the framework. It is unclear at the time of writing whether splitting out the other concepts from the
tfsdkpackage, such as schemas, will present the same issues. Regardless, any other major changes will be spread across releases.Provider developers should be able to update their code using find and replace operations using the tables below.
To reduce framework maintainer review burden, all code migrations were lift and shift operations while most code and documentation updates were find and replace operations.
tfsdk.ConfigureProviderRequestprovider.ConfigureRequesttfsdk.ConfigureProviderResponseprovider.ConfigureResponsetfsdk.Providerprovider.Providertfsdk.ProviderConfigValidatorprovider.ConfigValidatortfsdk.ProviderWithConfigValidatorsprovider.ProviderWithConfigValidatorstfsdk.ProviderWithProviderMetaprovider.ProviderWithMetaSchema(note naming realignment)tfsdk.ProviderWithValidateConfigprovider.ProviderWithValidateConfigtfsdk.ValidateProviderConfigRequestprovider.ValidateConfigRequesttfsdk.ValidateProviderConfigResponseprovider.ValidateConfigResponseThe
DataSourceTypeabstraction migrates to theproviderpackage since it relates to data that must be populated before the provider is configured as well as being passed theProviderinterface, which can be converted into a concrete Go type when creating aDataSource. Other data source concept types are migrated to a newdatasourcepackage.tfsdk.DataSourceTypeprovider.DataSourceTypetfsdk.DataSourcedatasource.DataSourcetfsdk.DataSourceConfigValidatordatasource.ConfigValidatortfsdk.DataSourceWithConfigValidatorsdatasource.DataSourceWithConfigValidatorstfsdk.DataSourceWithValidateConfigdatasource.DataSourceWithValidateConfigtfsdk.ReadDataSourceRequestdatasource.ReadRequesttfsdk.ReadDataSourceResponsedatasource.ReadResponsetfsdk.ValidateDataSourceConfigRequestdatasource.ValidateConfigRequesttfsdk.ValidateDataSourceConfigResponsedatasource.ValidateConfigResponseThe
ResourceTypeabstraction migrates to theproviderpackage since it relates to data that must be populated before the provider is configured as well as being passed theProviderinterface, which can be converted into a concrete Go type when creating aResource. Other resource concept types are migrated to a newresourcepackage.Additionally, the
tfsdk.ResourceImportStatePassthroughID()function has been migrated toresource.ImportStatePassthroughID().tfsdk.ResourceTypeprovider.ResourceTypetfsdk.CreateResourceRequestresource.CreateRequesttfsdk.CreateResourceResponseresource.CreateResponsetfsdk.DeleteResourceRequestresource.DeleteRequesttfsdk.DeleteResourceResponseresource.DeleteResponsetfsdk.ImportResourceStateRequestresource.ImportStateRequesttfsdk.ImportResourceStateResponseresource.ImportStateResponsetfsdk.ModifyResourcePlanRequestresource.ModifyPlanRequesttfsdk.ModifyResourcePlanResponseresource.ModifyPlanResponsetfsdk.ReadResourceRequestresource.ReadRequesttfsdk.ReadResourceResponseresource.ReadResponsetfsdk.Resourceresource.Resourcetfsdk.ResourceConfigValidatorresource.ConfigValidatortfsdk.ResourceWithConfigValidatorsresource.ResourceWithConfigValidatorstfsdk.ResourceWithImportStateresource.ResourceWithImportStatetfsdk.ResourceWithModifyPlanresource.ResourceWithModifyPlantfsdk.ResourceWithUpgradeStateresource.ResourceWithUpgradeStatetfsdk.ResourceWithValidateConfigresource.ResourceWithValidateConfigtfsdk.UpdateResourceRequestresource.UpdateRequesttfsdk.UpdateResourceResponseresource.UpdateResponsetfsdk.UpgradeResourceStateRequestresource.UpgradeStateRequesttfsdk.UpgradeResourceStateResponseresource.UpgradeStateResponsetfsdk.ValidateResourceConfigRequestresource.ValidateConfigRequesttfsdk.ValidateResourceConfigResponseresource.ValidateConfigResponse