helper/schema: Custom diff logic support for providers

builtin/providers/test/provider.go

@@ -17,8 +17,9 @@ func Provider() terraform.ResourceProvider {
 			},
 		},
 		ResourcesMap: map[string]*schema.Resource{
-			"test_resource":         testResource(),
-			"test_resource_gh12183": testResourceGH12183(),
+			"test_resource":                  testResource(),
+			"test_resource_gh12183":          testResourceGH12183(),
+			"test_resource_with_custom_diff": testResourceCustomDiff(),
 		},
 		DataSourcesMap: map[string]*schema.Resource{
 			"test_data_source":    testDataSource(),

builtin/providers/test/resource_with_custom_diff.go

@@ -0,0 +1,154 @@
+package test
+
+import (
+	"fmt"
+
+	"github.com/hashicorp/terraform/helper/schema"
+)
+
+func testResourceCustomDiff() *schema.Resource {
+	return &schema.Resource{
+		Create:        testResourceCustomDiffCreate,
+		Read:          testResourceCustomDiffRead,
+		CustomizeDiff: testResourceCustomDiffCustomizeDiff,
+		Update:        testResourceCustomDiffUpdate,
+		Delete:        testResourceCustomDiffDelete,
+		Schema: map[string]*schema.Schema{
+			"required": {
+				Type:     schema.TypeString,
+				Required: true,
+			},
+			"computed": {
+				Type:     schema.TypeInt,
+				Computed: true,
+			},
+			"index": {
+				Type:     schema.TypeInt,
+				Computed: true,
+			},
+			"veto": {
+				Type:     schema.TypeBool,
+				Optional: true,
+			},
+			"list": {
+				Type:     schema.TypeList,
+				Computed: true,
+				Elem:     &schema.Schema{Type: schema.TypeString},
+			},
+		},
+	}
+}
+
+type listDiffCases struct {
+	Type  string
+	Value string
+}
+
+func testListDiffCases(index int) []listDiffCases {
+	switch index {
+	case 0:
+		return []listDiffCases{
+			{
+				Type:  "add",
+				Value: "dc1",
+			},
+		}
+	case 1:
+		return []listDiffCases{
+			{
+				Type:  "remove",
+				Value: "dc1",
+			},
+			{
+				Type:  "add",
+				Value: "dc2",
+			},
+			{
+				Type:  "add",
+				Value: "dc3",
+			},
+		}
+	}
+	return nil
+}
+
+func testListDiffCasesReadResult(index int) []interface{} {
+	switch index {
+	case 1:
+		return []interface{}{"dc1"}
+	default:
+		return []interface{}{"dc2", "dc3"}
+	}
+}
+
+func testResourceCustomDiffCreate(d *schema.ResourceData, meta interface{}) error {
+	d.SetId("testId")
+
+	// Required must make it through to Create
+	if _, ok := d.GetOk("required"); !ok {
+		return fmt.Errorf("missing attribute 'required', but it's required")
+	}
+
+	_, new := d.GetChange("computed")
+	expected := new.(int) - 1
+	actual := d.Get("index").(int)
+	if expected != actual {
+		return fmt.Errorf("expected computed to be 1 ahead of index, got computed: %d, index: %d", expected, actual)
+	}
+	d.Set("index", new)
+
+	return testResourceCustomDiffRead(d, meta)
+}
+
+func testResourceCustomDiffRead(d *schema.ResourceData, meta interface{}) error {
+	if err := d.Set("list", testListDiffCasesReadResult(d.Get("index").(int))); err != nil {
+		return err
+	}
+	return nil
+}
+
+func testResourceCustomDiffCustomizeDiff(d *schema.ResourceDiff, meta interface{}) error {
+	if d.Get("veto").(bool) == true {
+		return fmt.Errorf("veto is true, diff vetoed")
+	}
+	// Note that this gets put into state after the update, regardless of whether
+	// or not anything is acted upon in the diff.
+	d.SetNew("computed", d.Get("computed").(int)+1)
+
+	// This tests a diffed list, based off of the value of index
+	dcs := testListDiffCases(d.Get("index").(int))
+	s := d.Get("list").([]interface{})
+	for _, dc := range dcs {
+		switch dc.Type {
+		case "add":
+			s = append(s, dc.Value)
+		case "remove":
+			for i := range s {
+				if s[i].(string) == dc.Value {
+					copy(s[i:], s[i+1:])
+					s = s[:len(s)-1]
+					break
+				}
+			}
+		}
+	}
+	d.SetNew("list", s)
+
+	return nil
+}
+
+func testResourceCustomDiffUpdate(d *schema.ResourceData, meta interface{}) error {
+	_, new := d.GetChange("computed")
+	expected := new.(int) - 1
+	actual := d.Get("index").(int)
+	if expected != actual {
+		return fmt.Errorf("expected computed to be 1 ahead of index, got computed: %d, index: %d", expected, actual)
+	}
+	d.Set("index", new)
+	return testResourceCustomDiffRead(d, meta)
+}
+
+func testResourceCustomDiffDelete(d *schema.ResourceData, meta interface{}) error {
+	d.SetId("")
+	return nil
+}

builtin/providers/test/resource_with_custom_diff_test.go

@@ -0,0 +1,53 @@
+package test
+
+import (
+	"fmt"
+	"regexp"
+	"testing"
+
+	"github.com/hashicorp/terraform/helper/resource"
+)
+
+// TestResourceWithCustomDiff test custom diff behaviour.
+func TestResourceWithCustomDiff(t *testing.T) {
+	resource.UnitTest(t, resource.TestCase{
+		Providers: testAccProviders,
+		Steps: []resource.TestStep{
+			{
+				Config: resourceWithCustomDiffConfig(false),
+				Check: resource.ComposeTestCheckFunc(
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "computed", "1"),
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "index", "1"),
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "list.#", "1"),
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "list.0", "dc1"),
+				),
+				ExpectNonEmptyPlan: true,
+			},
+			{
+				Config: resourceWithCustomDiffConfig(false),
+				Check: resource.ComposeTestCheckFunc(
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "computed", "2"),
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "index", "2"),
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "list.#", "2"),
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "list.0", "dc2"),
+					resource.TestCheckResourceAttr("test_resource_with_custom_diff.foo", "list.1", "dc3"),
+					resource.TestCheckNoResourceAttr("test_resource_with_custom_diff.foo", "list.2"),
+				),
+				ExpectNonEmptyPlan: true,
+			},
+			{
+				Config:      resourceWithCustomDiffConfig(true),
+				ExpectError: regexp.MustCompile("veto is true, diff vetoed"),
+			},
+		},
+	})
+}
+
+func resourceWithCustomDiffConfig(veto bool) string {
+	return fmt.Sprintf(`
+resource "test_resource_with_custom_diff" "foo" {
+	required = "yep"
+	veto = %t
+}
+`, veto)
+}

helper/schema/backend.go

@@ -65,7 +65,7 @@ func (b *Backend) Configure(c *terraform.ResourceConfig) error {
 
 	// Get a ResourceData for this configuration. To do this, we actually
 	// generate an intermediary "diff" although that is never exposed.
-	diff, err := sm.Diff(nil, c)
+	diff, err := sm.Diff(nil, c, nil, nil)
 	if err != nil {
 		return err
 	}

helper/schema/provider.go

@@ -251,7 +251,7 @@ func (p *Provider) Configure(c *terraform.ResourceConfig) error {
 
 	// Get a ResourceData for this configuration. To do this, we actually
 	// generate an intermediary "diff" although that is never exposed.
-	diff, err := sm.Diff(nil, c)
+	diff, err := sm.Diff(nil, c, nil, p.meta)
 	if err != nil {
 		return err
 	}
@@ -293,7 +293,7 @@ func (p *Provider) Diff(
 		return nil, fmt.Errorf("unknown resource type: %s", info.Type)
 	}
 
-	return r.Diff(s, c)
+	return r.Diff(s, c, p.meta)
 }
 
 // Refresh implementation of terraform.ResourceProvider interface.
@@ -410,7 +410,7 @@ func (p *Provider) ReadDataDiff(
 		return nil, fmt.Errorf("unknown data source: %s", info.Type)
 	}
 
-	return r.Diff(nil, c)
+	return r.Diff(nil, c, p.meta)
 }
 
 // RefreshData implementation of terraform.ResourceProvider interface.

helper/schema/provisioner.go

@@ -146,7 +146,7 @@ func (p *Provisioner) Apply(
 		}
 
 		sm := schemaMap(p.ConnSchema)
-		diff, err := sm.Diff(nil, terraform.NewResourceConfig(c))
+		diff, err := sm.Diff(nil, terraform.NewResourceConfig(c), nil, nil)
 		if err != nil {
 			return err
 		}
@@ -160,7 +160,7 @@ func (p *Provisioner) Apply(
 		// Build the configuration data. Doing this requires making a "diff"
 		// even though that's never used. We use that just to get the correct types.
 		configMap := schemaMap(p.Schema)
-		diff, err := configMap.Diff(nil, c)
+		diff, err := configMap.Diff(nil, c, nil, nil)
 		if err != nil {
 			return err
 		}

helper/schema/resource.go

@@ -85,6 +85,37 @@ type Resource struct {
 	Delete DeleteFunc
 	Exists ExistsFunc
 
+	// CustomizeDiff is a custom function for working with the diff that
+	// Terraform has created for this resource - it can be used to customize the
+	// diff that has been created, diff values not controlled by configuration,
+	// or even veto the diff altogether and abort the plan. It is passed a
+	// *ResourceDiff, a structure similar to ResourceData but lacking most write
+	// functions like Set, while introducing new functions that work with the
+	// diff such as SetNew, SetNewComputed, and ForceNew.
+	//
+	// The phases Terraform runs this in, and the state available via functions
+	// like Get and GetChange, are as follows:
+	//
+	//  * New resource: One run with no state
+	//  * Existing resource: One run with state
+	//   * Existing resource, forced new: One run with state (before ForceNew),
+	//     then one run without state (as if new resource)
+	//  * Tainted resource: No runs (custom diff logic is skipped)
+	//  * Destroy: No runs (standard diff logic is skipped on destroy diffs)
+	//
+	// This function needs to be resilient to support all scenarios.
+	//
+	// If this function needs to access external API resources, remember to flag
+	// the RequiresRefresh attribute mentioned below to ensure that
+	// -refresh=false is blocked when running plan or apply, as this means that
+	// this resource requires refresh-like behaviour to work effectively.
+	//
+	// For the most part, only computed fields can be customized by this
+	// function.
+	//
+	// This function is only allowed on regular resources (not data sources).
+	CustomizeDiff CustomizeDiffFunc
+
 	// Importer is the ResourceImporter implementation for this resource.
 	// If this is nil, then this resource does not support importing. If
 	// this is non-nil, then it supports importing and ResourceImporter
@@ -126,6 +157,9 @@ type ExistsFunc func(*ResourceData, interface{}) (bool, error)
 type StateMigrateFunc func(
 	int, *terraform.InstanceState, interface{}) (*terraform.InstanceState, error)
 
+// See Resource documentation.
+type CustomizeDiffFunc func(*ResourceDiff, interface{}) error
+
 // Apply creates, updates, and/or deletes a resource.
 func (r *Resource) Apply(
 	s *terraform.InstanceState,
@@ -202,11 +236,11 @@ func (r *Resource) Apply(
 	return r.recordCurrentSchemaVersion(data.State()), err
 }
 
-// Diff returns a diff of this resource and is API compatible with the
-// ResourceProvider interface.
+// Diff returns a diff of this resource.
 func (r *Resource) Diff(
 	s *terraform.InstanceState,
-	c *terraform.ResourceConfig) (*terraform.InstanceDiff, error) {
+	c *terraform.ResourceConfig,
+	meta interface{}) (*terraform.InstanceDiff, error) {
 
 	t := &ResourceTimeout{}
 	err := t.ConfigDecode(r, c)
@@ -215,7 +249,7 @@ func (r *Resource) Diff(
 		return nil, fmt.Errorf("[ERR] Error decoding timeout: %s", err)
 	}
 
-	instanceDiff, err := schemaMap(r.Schema).Diff(s, c)
+	instanceDiff, err := schemaMap(r.Schema).Diff(s, c, r.CustomizeDiff, meta)
 	if err != nil {
 		return instanceDiff, err
 	}
@@ -346,6 +380,11 @@ func (r *Resource) InternalValidate(topSchemaMap schemaMap, writable bool) error
 		if r.Create != nil || r.Update != nil || r.Delete != nil {
 			return fmt.Errorf("must not implement Create, Update or Delete")
 		}
+
+		// CustomizeDiff cannot be defined for read-only resources
+		if r.CustomizeDiff != nil {
+			return fmt.Errorf("cannot implement CustomizeDiff")
+		}
 	}
 
 	tsm := topSchemaMap