Blocks

Note: The Plugin Framework is in beta.

Some providers, resources, and data sources include repeatable nested blocks in their attributes. These nested blocks typically represent separate objects that are related to (or embedded within) the containing object.

This page explains how to migrate nested blocks that are not computed (i.e., do not set Computed: true) from SDKv2 to the Framework. Refer to Blocks with Computed Fields for more details about migrating nested blocks that contain fields that are computed.

Nested Block Example

The following example shows a nested block in Terraform resource configuration. The subject nested block within the tls_cert_request resource configures the subject of a certificate request with the common_name and organization attributes.

resource "tls_cert_request" "example" {
  private_key_pem = file("private_key.pem")

  subject {
    common_name  = "example.com"
    organization = "ACME Examples, Inc"
  }
}

SDKv2

In SDKv2, blocks are defined by an attribute whose type is TypeList or TypeSet and whose Elem field is set to a schema.Resource that contains a map of the block's attribute names to corresponding schemaSchema structs.

func resourceExample() *schema.Resource {
    return &schema.Resource{
         /* ... */
        map[string]*schema.Schema{
            "example" = &schema.Schema{
                Type:     schema.TypeList,
                Optional: bool,
                MaxItems: int,
                Elem: &schema.Resource{
                    Schema: map[string]*schema.Schema{
                        "nested_example": {
                            Type:        schema.TypeString,
                            Optional:    bool,
                            /* ... */

Framework

In the Framework, you implement nested blocks with the Blocks field of your provider, resource, or data source's schema, as returned by the Schema method. The Blocks field maps the name of each block to a schema.Block definition.

func (r *ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    return schema.Schema{
        /* ... */
        Blocks: map[string]schema.Block{
            "example": schema.ListNestedBlock{
                NestedObject: schema.NestedBlockObject{
                    Attributes: map[string]schema.Attribute{
                        "nested_example": schema.StringAttribute{
                            Optional: bool
                            /* ... */

Example

The following examples show how to migrate portions of the tls provider.

For a complete example, clone the terraform-provider-tls repository and compare the common_cert.go file in v3.4.0 with the resource_cert_request.go file in v4.0.1.

SDKv2

The following example from the common_cert.go file shows the implementation of the subject nested block on the cert_request resource's schema with SDKv2.

map[string]*schema.Schema{
    "private_key_pem": &schema.Schema{
        Type:      schema.TypeString,
        /* ... */

    "subject" = &schema.Schema{
        Type:     schema.TypeList,
        MaxItems: 1,
        Elem: &schema.Resource{
            Schema: map[string]*schema.Schema{
                "organization": {
                    Type:        schema.TypeString,
                    /* ... */
                },
                "common_name": {
                    Type:        schema.TypeString,
                    /* ... */
                },
                /* ... */

Framework

The following example from the resource_cert_request.go file shows how the nested subject block on the cert_request resource is defined with the Framework after the migration.

schema.Schema{
        Attributes: map[string]schema.Attribute{
            "private_key_pem": schema.StringAttribute{
            /* ... */

        Blocks: map[string]schema.Block{
            "subject": schema.ListNestedBlock{
                NestedObject: schema.NestedBlockObject{
                    Attributes: map[string]schema.Attribute{
                        "organization": schema.StringAttribute{
                            /* ... */
                        },
                        "common_name": schema.StringAttribute{
                            /* ... */
                        },
                Validators: validator.List{
                    listvalidator.SizeAtMost(1),
                },