docs: update NormalizeSetData comments (#3343)

* docs: update NormalizeSetData comments

Update comments for `NormalizeSetData` to include when `NormalizeSetData` could be useful and the non-obvious consequences of using it.

internal/host/plugin/repository_host_catalog_test.go

@@ -189,7 +189,7 @@ func TestRepository_CreateCatalog(t *testing.T) {
 					PluginId:  plg.GetPublicId(),
 					Attributes: func() []byte {
 						st, err := structpb.NewStruct(map[string]any{
-							"k1":                "foo",
+							"k1":                nil,
 							"nilkey":            nil,
 							normalizeToSliceKey: "normalizeme",
 						})
@@ -206,7 +206,6 @@ func TestRepository_CreateCatalog(t *testing.T) {
 					PluginId:  plg.GetPublicId(),
 					Attributes: func() []byte {
 						b, err := proto.Marshal(&structpb.Struct{Fields: map[string]*structpb.Value{
-							"k1": structpb.NewStringValue("foo"),
 							normalizeToSliceKey: structpb.NewListValue(
 								&structpb.ListValue{
 									Values: []*structpb.Value{

internal/host/plugin/repository_host_set_test.go

@@ -243,7 +243,7 @@ func TestRepository_CreateSet(t *testing.T) {
 					Description: ("test-description-repo"),
 					Attributes: func() []byte {
 						st, err := structpb.NewStruct(map[string]any{
-							"k1":                "foo",
+							"k1":                nil,
 							"removed":           nil,
 							normalizeToSliceKey: "normalizeme",
 						})
@@ -260,7 +260,6 @@ func TestRepository_CreateSet(t *testing.T) {
 					Description: ("test-description-repo"),
 					Attributes: func() []byte {
 						b, err := proto.Marshal(&structpb.Struct{Fields: map[string]*structpb.Value{
-							"k1": structpb.NewStringValue("foo"),
 							normalizeToSliceKey: structpb.NewListValue(
 								&structpb.ListValue{
 									Values: []*structpb.Value{

internal/proto/plugin/v1/host_plugin_service.proto

@@ -17,6 +17,20 @@ service HostPluginService {
   // allows those values to be normalized prior to creating or updating those
   // values in the host catalog data.
   //
+  // NormalizeCatalogData is useful for converting the values of attributes from
+  // a certain format/type to an expected value format/type. This is useful
+  // during migration of values.
+  //
+  // NormalizeCatalogData is called before the values of attributes are persisted.
+  // All normalized values will be persisted in Boundary and returned
+  // to all clients.
+  //
+  // NormalizeCatalogData could affect other clients. For example, on Terraform,
+  // if data is passed to Boundary and then normalized into a new data
+  // structure, it could cause diffs in Terraform for unchanged values.
+  // This is because, the data structure in Terraform's state will now be
+  // different from the normalized data structure returned from Boundary.
+  //
   // NormalizeCatalogData is called before:
   // * OnCreateCatalog
   // * OnUpdateCatalog
@@ -38,6 +52,20 @@ service HostPluginService {
   // allows those values to be normalized prior to creating or updating those
   // values in the host set data.
   //
+  // NormalizeSetData is useful for converting the values of attributes from
+  // a certain format/type to an expected value format/type. This is useful
+  // during migration of values.
+  //
+  // NormalizeSetData is called before the values of attributes are persisted.
+  // All normalized values will be persisted in Boundary and returned
+  // to all clients.
+  //
+  // NormalizeSetData could affect other clients. For example, on Terraform,
+  // if data is passed to Boundary and then normalized into a new data
+  // structure, it could cause diffs in Terraform for unchanged values.
+  // This is because, the data structure in Terraform's state will now be
+  // different from the normalized data structure returned from Boundary.
+  //
   // NormalizeSetData is called before:
   // * OnCreateSet
   // * OnUpdateSet

sdk/pbs/plugin/host_plugin_service_grpc.pb.go

@@ -22,6 +22,20 @@ type HostPluginServiceClient interface {
 	// allows those values to be normalized prior to creating or updating those
 	// values in the host catalog data.
 	//
+	// NormalizeCatalogData is useful for converting the values of attributes from
+	// a certain format/type to an expected value format/type. This is useful
+	// during migration of values.
+	//
+	// NormalizeCatalogData is called before the values of attributes are persisted.
+	// All normalized values will be persisted in Boundary and returned
+	// to all clients.
+	//
+	// NormalizeCatalogData could affect other clients. For example, on Terraform,
+	// if data is passed to Boundary and then normalized into a new data
+	// structure, it could cause diffs in Terraform for unchanged values.
+	// This is because, the data structure in Terraform's state will now be
+	// different from the normalized data structure returned from Boundary.
+	//
 	// NormalizeCatalogData is called before:
 	// * OnCreateCatalog
 	// * OnUpdateCatalog
@@ -39,6 +53,20 @@ type HostPluginServiceClient interface {
 	// allows those values to be normalized prior to creating or updating those
 	// values in the host set data.
 	//
+	// NormalizeSetData is useful for converting the values of attributes from
+	// a certain format/type to an expected value format/type. This is useful
+	// during migration of values.
+	//
+	// NormalizeSetData is called before the values of attributes are persisted.
+	// All normalized values will be persisted in Boundary and returned
+	// to all clients.
+	//
+	// NormalizeSetData could affect other clients. For example, on Terraform,
+	// if data is passed to Boundary and then normalized into a new data
+	// structure, it could cause diffs in Terraform for unchanged values.
+	// This is because, the data structure in Terraform's state will now be
+	// different from the normalized data structure returned from Boundary.
+	//
 	// NormalizeSetData is called before:
 	// * OnCreateSet
 	// * OnUpdateSet
@@ -150,6 +178,20 @@ type HostPluginServiceServer interface {
 	// allows those values to be normalized prior to creating or updating those
 	// values in the host catalog data.
 	//
+	// NormalizeCatalogData is useful for converting the values of attributes from
+	// a certain format/type to an expected value format/type. This is useful
+	// during migration of values.
+	//
+	// NormalizeCatalogData is called before the values of attributes are persisted.
+	// All normalized values will be persisted in Boundary and returned
+	// to all clients.
+	//
+	// NormalizeCatalogData could affect other clients. For example, on Terraform,
+	// if data is passed to Boundary and then normalized into a new data
+	// structure, it could cause diffs in Terraform for unchanged values.
+	// This is because, the data structure in Terraform's state will now be
+	// different from the normalized data structure returned from Boundary.
+	//
 	// NormalizeCatalogData is called before:
 	// * OnCreateCatalog
 	// * OnUpdateCatalog
@@ -167,6 +209,20 @@ type HostPluginServiceServer interface {
 	// allows those values to be normalized prior to creating or updating those
 	// values in the host set data.
 	//
+	// NormalizeSetData is useful for converting the values of attributes from
+	// a certain format/type to an expected value format/type. This is useful
+	// during migration of values.
+	//
+	// NormalizeSetData is called before the values of attributes are persisted.
+	// All normalized values will be persisted in Boundary and returned
+	// to all clients.
+	//
+	// NormalizeSetData could affect other clients. For example, on Terraform,
+	// if data is passed to Boundary and then normalized into a new data
+	// structure, it could cause diffs in Terraform for unchanged values.
+	// This is because, the data structure in Terraform's state will now be
+	// different from the normalized data structure returned from Boundary.
+	//
 	// NormalizeSetData is called before:
 	// * OnCreateSet
 	// * OnUpdateSet