Add generation support to apps with CNB validation

Author: heroku-johnny

docs/resources/app.md

@@ -10,14 +10,19 @@ description: |-
 
 Provides a Heroku App resource. This can be used to create and manage applications on Heroku.
 
+The Heroku platform supports two generations:
+- **Cedar** (default): Traditional platform with support for buildpacks, stack configuration, and internal routing
+- **Fir**: Next-generation platform with Cloud Native Buildpacks (CNB), enhanced security, and modern containerization
+
 -> **Always reference apps by ID (UUID) in Terraform configuration**
 Starting with v5.0 of this provider, all HCL app references are by ID. Read more details in [Upgrading](guides/upgrading.html).
 
 ## Example Usage
 
+### Cedar Generation (Default)
 ```hcl-terraform
-resource "heroku_app" "default" {
-  name   = "my-cool-app"
+resource "heroku_app" "cedar_app" {
+  name   = "my-cedar-app"
   region = "us"
 
   config_vars = {
@@ -27,6 +32,24 @@ resource "heroku_app" "default" {
   buildpacks = [
     "heroku/go"
   ]
+  
+  stack = "heroku-22"
+}
+```
+
+### Fir Generation (Cloud Native Buildpacks)
+```hcl-terraform
+resource "heroku_app" "fir_app" {
+  name       = "my-fir-app"
+  region     = "us"
+  generation = "fir"
+
+  config_vars = {
+    FOOBAR = "baz"
+  }
+  
+  # Note: buildpacks and stack are not supported for Fir generation
+  # Use project.toml in your application code instead
 }
 ```
 
@@ -52,9 +75,12 @@ The following arguments are supported:
 * `name` - (Required) The name of the application. In Heroku, this is also the
    unique ID, so it must be unique and have a minimum of 3 characters.
 * `region` - (Required) The region that the app should be deployed in.
-* `stack` - (Optional) The application stack is what platform to run the application in.
+* `generation` - (Optional) Generation of the app platform. Valid values are `cedar` and `fir`. Defaults to `cedar` for backward compatibility. **ForceNew**. 
+   - **Cedar**: Traditional platform supporting buildpacks, stack configuration, and internal routing
+   - **Fir**: Next-generation platform with Cloud Native Buildpacks (CNB). Does not support `buildpacks`, `stack`, or `internal_routing` fields
+* `stack` - (Optional) The application stack is what platform to run the application in. **Note**: Not supported for `fir` generation apps.
 * `buildpacks` - (Optional) Buildpack names or URLs for the application.
-  Buildpacks configured externally won't be altered if this is not present.
+  Buildpacks configured externally won't be altered if this is not present. **Note**: Not supported for `fir` generation apps. Use project.toml for Cloud Native Buildpacks configuration instead.
 * `config_vars`<sup>[1](#deleting-vars)</sup> - (Optional) Configuration variables for the application.
      The config variables in this map are not the final set of configuration
      variables, but rather variables you want present. That is, other
@@ -68,7 +94,7 @@ The following arguments are supported:
 * `space` - (Optional) The name of a private space to create the app in.
 * `internal_routing` - (Optional) If true, the application will be routable
   only internally in a private space. This option is only available for apps
-  that also specify `space`.
+  that also specify `space`. **Note**: Not supported for `fir` generation apps.
 * `organization` - (Optional) A block that can be specified once to define
      Heroku Team settings for this app. The fields for this block are
      documented below.
@@ -96,6 +122,7 @@ The following attributes are exported:
 
 * `id` - The ID (UUID) of the app.
 * `name` - The name of the app.
+* `generation` - Generation of the app platform (cedar or fir). Defaults to cedar.
 * `stack` - The application stack is what platform to run the application in.
 * `space` - The private space the app should run in.
 * `internal_routing` - Whether internal routing is enabled the private space app.
@@ -113,6 +140,55 @@ The following attributes are exported:
   attribute `set_app_all_config_vars_in_state` is `false`.
 * `uuid` - The unique UUID of the Heroku app. **NOTE:** Use this for `null_resource` triggers.
 
+## Cloud Native Buildpacks (Fir Generation)
+
+When using the Fir generation (`generation = "fir"`), applications use Cloud Native Buildpacks (CNB) instead of traditional Heroku buildpacks. This requires different configuration approaches:
+
+### project.toml Configuration
+
+Instead of specifying `buildpacks` in Terraform, create a `project.toml` file in your application root:
+
+```toml
+[build]
+[[build.buildpacks]]
+id = "heroku/nodejs"
+
+[[build.buildpacks]] 
+id = "heroku/procfile"
+
+[build.env]
+BP_NODE_VERSION = "18.*"
+```
+
+### Migration from Cedar to Fir
+
+When migrating from Cedar to Fir generation:
+
+1. **Remove incompatible fields**: Remove `buildpacks`, `stack`, and `internal_routing` from your Terraform configuration
+2. **Add project.toml**: Create a `project.toml` file in your application code with buildpack configuration
+3. **Update generation**: Set `generation = "fir"` in your app resource
+4. **Redeploy**: Deploy your application with the new configuration
+
+```hcl-terraform
+# Before (Cedar)
+resource "heroku_app" "example" {
+  name   = "my-app"
+  region = "us"
+  
+  buildpacks = ["heroku/nodejs"]
+  stack      = "heroku-22"
+}
+
+# After (Fir)
+resource "heroku_app" "example" {
+  name       = "my-app" 
+  region     = "us"
+  generation = "fir"
+  
+  # buildpacks and stack removed - configured via project.toml
+}
+```
+
 ## Import
 
 Apps can be imported using an existing app's `UUID` or name.

heroku/heroku_supported_features.go

@@ -20,6 +20,12 @@ var featureMatrix = map[string]map[string]map[string]bool{
 			"inbound_ruleset":       true, // Cedar supports inbound rulesets
 			"peering_connection":    true, // Cedar supports IPv4 peering
 		},
+		"app": {
+			"buildpacks":              true,  // Traditional buildpacks supported
+			"stack":                   true,  // Stack setting supported
+			"internal_routing":        true,  // Internal routing supported
+			"cloud_native_buildpacks": false, // CNB not supported on Cedar
+		},
 	},
 	"fir": {
 		"space": {
@@ -34,6 +40,12 @@ var featureMatrix = map[string]map[string]map[string]bool{
 			"inbound_ruleset":       false, // Inbound rulesets not supported
 			"peering_connection":    false, // IPv4 peering not supported
 		},
+		"app": {
+			"buildpacks":              false, // Traditional buildpacks not supported
+			"stack":                   false, // Stack setting not supported
+			"internal_routing":        false, // Internal routing not supported
+			"cloud_native_buildpacks": true,  // CNB supported on Fir
+		},
 	},
 }
 

heroku/heroku_supported_features_test.go

@@ -75,13 +75,63 @@ func TestIsFeatureSupported(t *testing.T) {
 		},
 
 		// Unknown resource type tests
+		// App feature tests
 		{
-			name:         "Cedar app features should be unsupported (not implemented yet)",
+			name:         "Cedar app buildpacks should be supported",
 			generation:   "cedar",
 			resourceType: "app",
-			feature:      "some_feature",
+			feature:      "buildpacks",
+			expected:     true,
+		},
+		{
+			name:         "Cedar app stack should be supported",
+			generation:   "cedar",
+			resourceType: "app",
+			feature:      "stack",
+			expected:     true,
+		},
+		{
+			name:         "Cedar app internal_routing should be supported",
+			generation:   "cedar",
+			resourceType: "app",
+			feature:      "internal_routing",
+			expected:     true,
+		},
+		{
+			name:         "Cedar app cloud_native_buildpacks should be unsupported",
+			generation:   "cedar",
+			resourceType: "app",
+			feature:      "cloud_native_buildpacks",
+			expected:     false,
+		},
+		{
+			name:         "Fir app buildpacks should be unsupported",
+			generation:   "fir",
+			resourceType: "app",
+			feature:      "buildpacks",
+			expected:     false,
+		},
+		{
+			name:         "Fir app stack should be unsupported",
+			generation:   "fir",
+			resourceType: "app",
+			feature:      "stack",
+			expected:     false,
+		},
+		{
+			name:         "Fir app internal_routing should be unsupported",
+			generation:   "fir",
+			resourceType: "app",
+			feature:      "internal_routing",
 			expected:     false,
 		},
+		{
+			name:         "Fir app cloud_native_buildpacks should be supported",
+			generation:   "fir",
+			resourceType: "app",
+			feature:      "cloud_native_buildpacks",
+			expected:     true,
+		},
 		{
 			name:         "Fir build features should be unsupported (not implemented yet)",
 			generation:   "fir",

heroku/resource_heroku_app.go

@@ -49,11 +49,12 @@ type application struct {
 
 func resourceHerokuApp() *schema.Resource {
 	return &schema.Resource{
-		Create: switchHerokuAppCreate,
-		Read:   resourceHerokuAppRead,
-		Update: resourceHerokuAppUpdate,
-		Delete: resourceHerokuAppDelete,
-		Exists: resourceHerokuAppExists,
+		Create:        switchHerokuAppCreate,
+		Read:          resourceHerokuAppRead,
+		Update:        resourceHerokuAppUpdate,
+		Delete:        resourceHerokuAppDelete,
+		Exists:        resourceHerokuAppExists,
+		CustomizeDiff: resourceHerokuAppCustomizeDiff,
 
 		Importer: &schema.ResourceImporter{
 			State: resourceHerokuAppImport,
@@ -77,6 +78,15 @@ func resourceHerokuApp() *schema.Resource {
 				ForceNew: true,
 			},
 
+			"generation": {
+				Type:         schema.TypeString,
+				Optional:     true,
+				Default:      "cedar",
+				ForceNew:     true,
+				ValidateFunc: validation.StringInSlice([]string{"cedar", "fir"}, false),
+				Description:  "Generation of the app platform. Defaults to cedar for backward compatibility.",
+			},
+
 			"stack": {
 				Type:     schema.TypeString,
 				Optional: true,
@@ -1034,3 +1044,34 @@ func resourceHerokuAppStateUpgradeV0(ctx context.Context, rawState map[string]in
 
 	return rawState, nil
 }
+
+func resourceHerokuAppCustomizeDiff(ctx context.Context, diff *schema.ResourceDiff, v interface{}) error {
+	generation, generationExists := diff.GetOk("generation")
+
+	if generationExists {
+		generationStr := generation.(string)
+
+		// Validate buildpacks field
+		if buildpacks, buildpacksExists := diff.GetOk("buildpacks"); buildpacksExists {
+			buildpacksList := buildpacks.([]interface{})
+			if len(buildpacksList) > 0 && !IsFeatureSupported(generationStr, "app", "buildpacks") {
+				return fmt.Errorf("buildpacks are not supported for %s generation apps. Use Cloud Native Buildpacks and configure via project.toml instead", generationStr)
+			}
+		}
+
+		// Validate stack field
+		if stack, stackExists := diff.GetOk("stack"); stackExists {
+			if stack.(string) != "" && !IsFeatureSupported(generationStr, "app", "stack") {
+				return fmt.Errorf("stack configuration is not supported for %s generation apps. Remove the 'stack' field", generationStr)
+			}
+		}
+
+		// Validate internal_routing field
+		if internalRouting, internalRoutingExists := diff.GetOk("internal_routing"); internalRoutingExists {
+			if internalRouting.(bool) && !IsFeatureSupported(generationStr, "app", "internal_routing") {
+				return fmt.Errorf("internal routing is not supported for %s generation apps", generationStr)
+			}
+		}
+	}
+	return nil
+}

heroku/resource_heroku_app_test.go

@@ -1006,3 +1006,37 @@ resource "heroku_app" "foobar" {
   }
 }`, appName)
 }
+
+// Unit tests for app generation support
+// Simple unit test for app generation validation logic
+func TestHerokuAppGeneration(t *testing.T) {
+	// Test that the feature matrix correctly identifies supported/unsupported features
+	tests := []struct {
+		name       string
+		generation string
+		feature    string
+		expected   bool
+	}{
+		// Cedar app features - should all be supported except CNB
+		{name: "Cedar buildpacks should be supported", generation: "cedar", feature: "buildpacks", expected: true},
+		{name: "Cedar stack should be supported", generation: "cedar", feature: "stack", expected: true},
+		{name: "Cedar internal_routing should be supported", generation: "cedar", feature: "internal_routing", expected: true},
+		{name: "Cedar cloud_native_buildpacks should be unsupported", generation: "cedar", feature: "cloud_native_buildpacks", expected: false},
+
+		// Fir app features - traditional features should be unsupported, CNB should be supported
+		{name: "Fir buildpacks should be unsupported", generation: "fir", feature: "buildpacks", expected: false},
+		{name: "Fir stack should be unsupported", generation: "fir", feature: "stack", expected: false},
+		{name: "Fir internal_routing should be unsupported", generation: "fir", feature: "internal_routing", expected: false},
+		{name: "Fir cloud_native_buildpacks should be supported", generation: "fir", feature: "cloud_native_buildpacks", expected: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			supported := IsFeatureSupported(tt.generation, "app", tt.feature)
+			if supported != tt.expected {
+				t.Errorf("Expected %t but got %t for generation %s feature %s", tt.expected, supported, tt.generation, tt.feature)
+			}
+			t.Logf("✅ Generation: %s, Feature: %s, Supported: %t", tt.generation, tt.feature, supported)
+		})
+	}
+}