Skip to content

Commit d51781c

Browse files
bfladbflad
authored
website: Updates for tfsdk Attribute, Block, and Schema deprecations (#564)
Reference: #132 Reference: #326 Reference: #437 Reference: #491 Reference: #546 Reference: #553 Reference: #558 Reference: #562 Reference: #563
1 parent 4db7ec6 commit d51781c

32 files changed

+613
-796
lines changed

‎website/docs/plugin/framework/acctests.mdx

+6-7
Original file line numberDiff line numberDiff line change
@@ -61,19 +61,18 @@ testing_new.go:53: no "id" found in attributes
6161

6262
To avoid this, add a root level `id` attribute to resource and data source schemas. Ensure the attribute value is appropriately [written to state](/plugin/framework/writing-state). Conventionally, `id` is a computed attribute that contains the identifier for the resource.
6363

64-
For example, in the `GetSchema` method implementation of a [`datasource.DataSource`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSource) or [`resource.Resource`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource):
64+
For example, in the `Schema` method implementation of a [`datasource.DataSource`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSource) or [`resource.Resource`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#Resource):
6565

6666
```go
67-
func (r *ThingResource) GetSchema(ctx context.Context) (tfsdk.Schema, diag.Diagnostics) {
68-
return tfsdk.Schema{
67+
func (r *ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
68+
resp.Schema = schema.Schema{
6969
// ... potentially other schema configuration ...
70-
Attributes: map[string]tfsdk.Attribute{
70+
Attributes: map[string]schema.Attribute{
7171
// ... potentially other schema attributes ...
72-
"id": {
73-
Type: types.StringType,
72+
"id": schema.StringAttribute{
7473
Computed: true,
7574
},
7675
},
77-
}, nil
76+
}
7877
}
7978
```

‎website/docs/plugin/framework/migrating/attributes-blocks/attribute-schema.mdx

+12-31
Original file line numberDiff line numberDiff line change
@@ -39,42 +39,24 @@ func resourceExample() *schema.Resource {
3939
## Framework
4040
4141
In the Framework, you define attributes by setting the `Attributes` field on your provider, resource, or data type's
42-
schema, as returned by the `GetSchema` function. The `tfsdk.Schema` type returned by `GetSchema` includes an
43-
`Attributes` field that maps each attribute name (string) to the attribute's `tfsdk.Attribute` struct.
42+
schema, as returned by the `Schema` method. The `schema.Schema` type returned by `SchemaResponse` includes an
43+
`Attributes` field that maps each attribute name (string) to the attribute's definition.
4444
4545
The following code shows how to define an attribute for a resource with the Framework.
4646
4747
```go
48-
func (d *resourceTypeExample) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
49-
return tfsdk.Schema{
50-
Attributes: map[string]tfsdk.Attribute{
51-
"example": {
52-
/* ... */
48+
func (r *ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
49+
resp.Schema = schema.Schema{
50+
Attributes: map[string]schema.Attribute{
51+
"example": /* ... */
5352
```
5453
55-
The Framework defines the `tfsdk.Attribute` struct as follows.
56-
57-
```go
58-
type Attribute struct {
59-
Type attr.Type
60-
Attributes NestedAttributes
61-
Description string
62-
MarkdownDescription string
63-
Required bool
64-
Optional bool
65-
Computed bool
66-
Sensitive bool
67-
DeprecationMessage string
68-
Validators []AttributeValidator
69-
PlanModifiers AttributePlanModifiers
70-
}
71-
```
7254
## Migration Notes
7355
Remember the following differences between SDKv2 and the Framework when completing the migration.
7456
7557
- In SDKv2, attributes are defined by a map from attribute names to `schema.Schema` structs in the `Schema` field of
76-
your resource's schema. In the Framework, attributes are defined by a map from attribute names to `tfsdk.Attribute`
77-
structs in your resource's schema, which is returned by the `GetSchema` function.
58+
your resource's schema. In the Framework, attributes are defined by a map from attribute names to `schema.Attribute`
59+
implementations in your resource's schema, which is returned by the resource `Schema` method.
7860
- There are several differences between the implementation of attributes in SDKv2 and the Framework. Refer to the other
7961
pages in the Attributes & Blocks section of this migration guide for more details.
8062
@@ -115,13 +97,12 @@ The following shows the same section of provider code after the migration.
11597
This code implements the `url` attribute for the `http` data source with the Framework.
11698
11799
```go
118-
func (d *httpDataSource) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
119-
return tfsdk.Schema{
100+
func (d *httpDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
101+
return schema.Schema{
120102
/* ... */
121-
Attributes: map[string]tfsdk.Attribute{
122-
"url": {
103+
Attributes: map[string]schema.Attribute{
104+
"url": schema.StringAttribute{
123105
Description: "The URL for the request. Supported schemes are `http` and `https`.",
124-
Type: types.StringType,
125106
Required: true,
126107
},
127108
/* ... */

‎website/docs/plugin/framework/migrating/attributes-blocks/blocks-computed.mdx

+23-26
Original file line numberDiff line numberDiff line change
@@ -36,41 +36,39 @@ map[string]*schema.Schema{
3636
3737
## Framework
3838
39-
In the Framework, when working with protocol version 5, computed blocks are implemented using an attribute with a `Type`
40-
of `types.ListType` which has an `ElemType` of `types.ObjectType`.
39+
In the Framework, when working with protocol version 5, computed blocks are implemented using a `ListAttribute` which has an `ElementType` of `types.ObjectType`.
4140
4241
```go
43-
map[string]tfsdk.Attribute{
44-
"example": {
42+
map[string]schema.Attribute{
43+
"example": schema.ListAttribute{
4544
Computed: true,
46-
Type: types.ListType{
47-
ElemType: types.ObjectType{
48-
AttrTypes: map[string]attr.Type{
49-
"nested_example": types.StringType,
50-
/* ... */
45+
ElementType: types.ObjectType{
46+
AttrTypes: map[string]attr.Type{
47+
"nested_example": types.StringType,
48+
/* ... */
5149

5250
```
5351
5452
In the Framework, when working with protocol version 6, we recommend that you define computed blocks using nested
55-
attributes. This example shows usage of `ListNestedAttributes` as this provides configuration references with list index
56-
syntax as is the case when using `schema.TypeList` in SDKv2. `SingleNestedAttributes` is a good choice for single
53+
attributes. This example shows usage of `ListNestedAttribute` as this provides configuration references with list index
54+
syntax as is the case when using `schema.TypeList` in SDKv2. `SingleNestedAttribute` is a good choice for single
5755
underlying objects which results in a breaking change but also allows dropping `[0]` in configuration references.
5856
5957
```go
60-
map[string]tfsdk.Attribute{
61-
"example": {
62-
Computed: true,
63-
Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{
64-
"nested_example": {
65-
Computed: true,
66-
Type: types.StringType,
67-
/* ... */
58+
map[string]schema.Attribute{
59+
"example": schema.ListNestedAttribute{
60+
Computed: true,
61+
NestedObject: schema.NestedAttributeObject{
62+
Attributes: map[string]schema.Attribute{
63+
"nested_example": schema.StringAttribute{
64+
Computed: true,
65+
/* ... */
6866

6967
```
7068
7169
## Migration Notes
7270
73-
- When using protocol version 5 specify `ElemType` as `types.ObjectType` when migrating blocks that are computed from SDKv2 to Framework.
71+
- When using protocol version 5 specify `ElementType` as `types.ObjectType` when migrating blocks that are computed from SDKv2 to Framework.
7472
- When using protocol version 6, use [nested attributes](/plugin/framework/schemas#attributes-1) when migrating blocks that are computed from SDKv2 to Framework.
7573
7674
## Example
@@ -111,12 +109,11 @@ This code defines the `certificates` block as an attribute on the `certificate`
111109
`types.ObjectType` is being used to define the nested block.
112110
113111
```go
114-
map[string]tfsdk.Attribute{
115-
"certificates": {
116-
Type: types.ListType{
117-
ElemType: types.ObjectType{
118-
AttrTypes: map[string]attr.Type{
119-
"signature_algorithm": types.StringType,
112+
map[string]schema.Attribute{
113+
"certificates": schema.ListAttribute{
114+
ElementType: types.ObjectType{
115+
AttrTypes: map[string]attr.Type{
116+
"signature_algorithm": types.StringType,
120117
},
121118
},
122119
Computed: true,

‎website/docs/plugin/framework/migrating/attributes-blocks/blocks.mdx

+29-33
Original file line numberDiff line numberDiff line change
@@ -59,22 +59,20 @@ func resourceExample() *schema.Resource {
5959
## Framework
6060
6161
In the Framework, you implement nested blocks with the `Blocks` field of your provider, resource, or data source's
62-
`tfsdk.Schema`, as returned by the `GetSchema` function. The `Blocks` field maps the name of each block to a
63-
`tfsdk.Block` struct which defines the block's behavior.
62+
schema, as returned by the `Schema` method. The `Blocks` field maps the name of each block to a
63+
`schema.Block` definition.
6464
6565
```go
66-
func (d *resourceTypeExample) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
67-
return tfsdk.Schema{
66+
func (r *ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
67+
return schema.Schema{
6868
/* ... */
69-
Blocks: map[string]tfsdk.Block{
70-
"example": {
71-
NestingMode: tfsdk.BlockNestingModeList,
72-
MaxItems: int,
73-
Attributes: map[string]tfsdk.Attribute{
74-
"nested_example": {
75-
Type: types.StringType,
76-
Optional: bool
77-
/* ... */
69+
Blocks: map[string]schema.Block{
70+
"example": schema.ListNestedBlock{
71+
NestedObject: schema.NestedBlockObject{
72+
Attributes: map[string]schema.Attribute{
73+
"nested_example": schema.StringAttribute{
74+
Optional: bool
75+
/* ... */
7876
```
7977
8078
@@ -122,24 +120,22 @@ The following example from the `resource_cert_request.go` file shows how the nes
122120
`cert_request` resource is defined with the Framework after the migration.
123121
124122
```go
125-
tfsdk.Schema{
126-
Attributes: map[string]tfsdk.Attribute{
127-
"private_key_pem": {
128-
Type: types.StringType,
129-
/* ... */
130-
131-
Blocks: map[string]tfsdk.Block{
132-
"subject": {
133-
NestingMode: tfsdk.BlockNestingModeList,
134-
MinItems: 0,
135-
MaxItems: 1,
136-
Attributes: map[string]tfsdk.Attribute{
137-
"organization": {
138-
Type: types.StringType,
139-
/* ... */
140-
},
141-
"common_name": {
142-
Type: types.StringType,
143-
/* ... */
144-
},
123+
schema.Schema{
124+
Attributes: map[string]schema.Attribute{
125+
"private_key_pem": schema.StringAttribute{
126+
/* ... */
127+
128+
Blocks: map[string]schema.Block{
129+
"subject": schema.ListNestedBlock{
130+
NestedObject: schema.NestedBlockObject{
131+
Attributes: map[string]schema.Attribute{
132+
"organization": schema.StringAttribute{
133+
/* ... */
134+
},
135+
"common_name": schema.StringAttribute{
136+
/* ... */
137+
},
138+
Validators: validator.List{
139+
listvalidator.SizeAtMost(1),
140+
},
145141
```

‎website/docs/plugin/framework/migrating/attributes-blocks/default-values.mdx

+23-24
Original file line numberDiff line numberDiff line change
@@ -39,16 +39,15 @@ func resourceExample() *schema.Resource {
3939
4040
## Framework
4141
42-
In the Framework, you set default values with the `PlanModifiers` field on your attribute's `tfsdk.Attribute`
43-
struct.
42+
In the Framework, you set default values with the `PlanModifiers` field on your attribute's definition.
4443
4544
```go
46-
func (r *resourceExample) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
47-
return tfsdk.Schema{
45+
func (r *resourceExample) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
46+
resp.Schema = schema.Schema{
4847
/* ... */
49-
Attributes: map[string]tfsdk.Attribute{
50-
"attribute_example": {
51-
PlanModifiers: []tfsdk.AttributePlanModifier{
48+
Attributes: map[string]schema.Attribute{
49+
"attribute_example": schema.BoolAttribute{
50+
PlanModifiers: []planmodifier.Bool{
5251
defaultValue(types.BoolValue(true)),
5352
/* ... */
5453
```
@@ -93,12 +92,12 @@ The following shows the same section of code after the migration.
9392
This code implements the `PlanModifiers` field for the `rsa_bits` attribute with the Framework.
9493
9594
```go
96-
func (r *privateKeyResource) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
97-
return tfsdk.Schema{
98-
Attributes: map[string]tfsdk.Attribute{
99-
"rsa_bits": {
100-
PlanModifiers: []tfsdk.AttributePlanModifier{
101-
attribute_plan_modifier.DefaultValue(types.Int64Value(2048)),
95+
func (r *privateKeyResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
96+
resp.Schema = schema.Schema{
97+
Attributes: map[string]schema.Attribute{
98+
"rsa_bits": schema.Int64Attribute{
99+
PlanModifiers: []planmodifier.Int64{
100+
attribute_plan_modifier.Int64DefaultValue(types.Int64Value(2048)),
102101
/* ... */
103102
},
104103
/* ... */
@@ -113,36 +112,36 @@ The following example from the `attribute_plan_modifiers.go` file implements the
113112
that the `rsa_bits` attribute uses.
114113
115114
```go
116-
func DefaultValue(v attr.Value) tfsdk.AttributePlanModifier {
117-
return &defaultValueAttributePlanModifier{v}
115+
func Int64DefaultValue(v types.Int64) planmodifier.Int64 {
116+
return &int64DefaultValuePlanModifier{v}
118117
}
119118

120-
type defaultValueAttributePlanModifier struct {
121-
DefaultValue attr.Value
119+
type int64DefaultValuePlanModifier struct {
120+
DefaultValue types.Int64
122121
}
123122

124-
var _ tfsdk.AttributePlanModifier = (*defaultValueAttributePlanModifier)(nil)
123+
var _ planmodifier.Int64 = (*int64DefaultValuePlanModifier)(nil)
125124

126-
func (apm *defaultValueAttributePlanModifier) Description(ctx context.Context) string {
125+
func (apm *int64DefaultValuePlanModifier) Description(ctx context.Context) string {
127126
/* ... */
128127
}
129128

130-
func (apm *defaultValueAttributePlanModifier) MarkdownDescription(ctx context.Context) string {
129+
func (apm *int64DefaultValuePlanModifier) MarkdownDescription(ctx context.Context) string {
131130
/* ... */
132131
}
133132

134-
func (apm *defaultValueAttributePlanModifier) Modify(ctx context.Context, req tfsdk.ModifyAttributePlanRequest, res *tfsdk.ModifyAttributePlanResponse) {
133+
func (apm *int64DefaultValuePlanModifier) PlanModifyInt64(ctx context.Context, req planmodifier.Int64Request, res *planmodifier.Int64Response) {
135134
// If the attribute configuration is not null, we are done here
136-
if !req.AttributeConfig.IsNull() {
135+
if !req.ConfigValue.IsNull() {
137136
return
138137
}
139138

140139
// If the attribute plan is "known" and "not null", then a previous plan modifier in the sequence
141140
// has already been applied, and we don't want to interfere.
142-
if !req.AttributePlan.IsUnknown() && !req.AttributePlan.IsNull() {
141+
if !req.PlanValue.IsUnknown() && !req.PlanValue.IsNull() {
143142
return
144143
}
145144

146-
res.AttributePlan = apm.DefaultValue
145+
res.PlanValue = apm.DefaultValue
147146
}
148147
```

‎website/docs/plugin/framework/migrating/attributes-blocks/fields.mdx

+9-9
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,14 @@ func resourceExample() *schema.Resource {
3333
3434
## Framework
3535
36-
In the Framework, you set the same fields on the `tfsdk.Attribute` struct, with the same behavior.
36+
In the Framework, you set the same fields on the `schema.Attribute` implementation, with the same behavior.
3737
3838
```go
39-
func (d *resourceTypeExample) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
40-
return tfsdk.Schema{
39+
func (r *ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
40+
resp.Schema = schema.Schema{
4141
/* ... */
42-
Attributes: map[string]tfsdk.Attribute{
43-
"attribute_example": {
42+
Attributes: map[string]schema.Attribute{
43+
"attribute_example": schema.XXXAttribute{
4444
Required: bool
4545
Optional: bool
4646
Computed: bool
@@ -81,10 +81,10 @@ The following example from the `data_source_http.go` file shows how the `url` at
8181
to be required with the Framework.
8282
8383
```go
84-
func (d *httpDataSource) GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics) {
85-
return tfsdk.Schema{
86-
Attributes: map[string]tfsdk.Attribute{
87-
"url": {
84+
func (d *httpDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
85+
resp.Schema = schema.Schema{
86+
Attributes: map[string]schema.Attribute{
87+
"url": schema.StringAttribute{
8888
Required: true,
8989
/* ... */
9090
},

0 commit comments

Comments
 (0)