Terraform
Migrating schema
This page explains how to migrate schema from SDKv2 to the framework.
Refer to Schemas in the framework documentation for more details about implementing schema in the framework.
Background
Providers, resources, and data sources all use schema to define their attributes and behavior. Schemas specify the constraints of Terraform configuration blocks and how the provider, resource, or data source behaves.
Migrating schema structs
In SDKv2, resources and data sources use the same schema.Resource
struct,
while providers use the provider.Schema
struct.
In SDKv2, resources and data sources use the same schema.Resource
struct,
while providers use the provider.Schema
struct.
SDKv2 uses schema.Schema
structs to define the structure, type, and behavior
of values drawn from configuration, state, or plan data. The same
schema.Schema
struct type is used for providers, resources, and data sources.
The schema struct is returned by the function that creates the provider,
resource, or data source in question. As you migrate a given provider, resource,
or data source to the framework, refer to Migrate attributes and
blocks to learn how to migrate the attributes
and blocks defined by your schema.
The framework uses its own
schema.Schema
structs for providers, resources, and data sources. The schema struct is
returned by Schema()
functions you define for your provider and each resource
type and data source type. This function is required by the
provider.Provider
,
resource.Resource
,
and
datasource.DataSource
interfaces, respectively.
The following code blocks show basic implementations using schema.Schema
structs to define schemas for providers, resources, and data sources with SDKv2.
This example defines a provider schema in SDKv2:
SDKv2
func New() *schema.Provider {
return &schema.Provider{
Schema: map[string]*schema.Schema{},
/* ... */
}
}
This example defines a resource schema in SDKv2:
SDKv2
func resourceExample() *schema.Resource {
return &schema.Resource{
Schema: map[string]*schema.Schema{},
/* ... */
}
}
The following example defines a data source schema in SDKv2:
SDKv2
func dataSourceExample() *schema.Resource {
return &schema.Resource{
Schema: map[string]*schema.Schema{},
/* ... */
}
}
SDKv2 defines the schema.Schema
struct as follows.
SDKv2
type Schema struct {
Type ValueType
ConfigMode SchemaConfigMode
Required bool
Optional bool
Computed bool
ForceNew bool
DiffSuppressFunc SchemaDiffSuppressFunc
DiffSuppressOnRefresh bool
Default interface{}
DefaultFunc SchemaDefaultFunc
Description string
StateFunc SchemaStateFunc
Elem interface{}
MaxItems int
MinItems int
Set SchemaSetFunc
ConflictsWith []string
ExactlyOneOf []string
AtLeastOneOf []string
RequiredWith []string
Deprecated string
ValidateFunc SchemaValidateFunc
ValidateDiagFunc SchemaValidateDiagFunc
Sensitive bool
}
The following code blocks show the same section of provider, resource, and data source code after migration.
The following example defines a provider schema in the framework:
Framework
func (p *ExampleCloudProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
resp.Schema = schema.Schema{/* ... */}
}
The following example defines a resource schema in the framework:
Framework
func (r *resourceExample) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
resp.Schema = schema.Schema{/* ... */}
}
The following example defines a data source schema in the framework:
Framework
func (r *dataSourceExample) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
resp.Schema = schema.Schema{/* ... */}
}
Use the Attributes
schema field to define attributes for your provider,
resources, and data sources. Use the Blocks
field to define named blocks.
Migration notes
Remember the following differences between SDKv2 and the framework when completing the migration.
- SDKv2 uses
schema.Schema
structs to define the provider, resources, and data sources. The framework uses concept-specificschema.Schema
structs instead. - In SDKv2, schema structs are returned when a provider, resource, or data type
is created. In the framework, the provider and each resource and data type
have a
Schema
method that returns the schema. - In SDKv2, schema structs have a
Set
field which can be populated with aSchemaSetFunc
which is used for hashing. In the framework, this is not required and does not need to be migrated. - The
schema.Schema
struct includes fields that you use to define attributes and blocks for your provider and each resource and data source. - When you populate the
Version
field inschema.Schema
for a resource or data source when migrating to the framework, copy theVersion
field inschema.Schema
from the SDKv2 version of that resource.
Migrating attributes and blocks
Each provider, resource, and data source schema defines the attributes and blocks they support. Refer to the following pages in this migration guide to migrate the attributes and blocks defined by your schema:
- Attributes are defined by their schema.
- Each attribute has an attribute type. An attribute's type defines its expected data structure and syntax.
- Attribute
fields define
optional behaviors of the attribute, such as
Required
,Optional
,Computed
, andSensitive
. - Attribute defaults define a default value for the attribute.
- Some attributes require that a resource be replaced when their value changes. Use a ForceNew trigger to force replacement of the resource when the value is updated.
- Providers may implement attribute validation to define required syntax, constraints, or encoding for the attribute's value. Implement attribute validation with a predefined validator or a custom validator.
- Attributes can include blocks and computed blocks to define structural configuration sections of data, typically with nested attributes or further blocks.