docs: deprecate aiven_project

docs/data-sources/project.md

@@ -4,12 +4,17 @@ page_title: "aiven_project Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
   Gets information about an Aiven project.
+  ~> This resource is deprecated
+  Use aiven_organization_project instead and migrate your existing aiven_project resources https://registry.terraform.io/providers/aiven/aiven/latest/docs/guides/update-deprecated-resources to the new resource.
 ---
 
 # aiven_project (Data Source)
 
 Gets information about an Aiven project.
 
+~> **This resource is deprecated**
+Use ``aiven_organization_project`` instead and [migrate your existing `aiven_project` resources](https://registry.terraform.io/providers/aiven/aiven/latest/docs/guides/update-deprecated-resources) to the new resource.
+
 ## Example Usage
 
 ```terraform

docs/guides/update-deprecated-resources.md

@@ -421,6 +421,125 @@ resource "aiven_account_team_project" "main" {
    terraform state list
    ```
 
+## Migrate `aiven_project` to `aiven_organization_project`
+
+The `aiven_project` resource and data source have been replaced by [`aiven_organization_project`](https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/organization_project).
+Migrate your existing project resources and data sources by replacing them with `aiven_organization_project`.
+
+1. Replace all `aiven_project` resources with the `aiven_organization_project` resource.
+   * Change the `project` attribute to `project_id`. Don't change the value.
+   * Add the `organization_id`.
+   * For projects in an organizational unit, keep the `parent_id` attribute.
+   * Add the `billing_group_id`. You can [get the IDs from the Aiven Console](https://docs.aiven.io/docs/platform/reference/get-resource-IDs).
+
+   For example, the following file has one project in an organization and one in an organizational unit:
+
+      ```hcl
+      data "aiven_organization" "main" {
+        name = "Example organization"
+      }
+
+      resource "aiven_organizational_unit" "example_unit" {
+        name      = "Production"
+        parent_id = data.aiven_organization.main.id
+      }
+
+      resource "aiven_project" "example_project_in_org" {
+        project   = "example-project-in-organization"
+        parent_id = data.aiven_organization.main.id
+      }
+
+      resource "aiven_project" "example_project_in_unit" {
+        project   = "example-project-in-unit"
+        parent_id = aiven_organizational_unit.example_unit.id
+      }
+     ```
+
+     The updated file with the new `aiven_organization_project` resource is:
+
+      ```hcl
+      data "aiven_organization" "main" {
+        name = "Example organization"
+      }
+
+      resource "aiven_organizational_unit" "example_unit" {
+        name      = "Production"
+        parent_id = data.aiven_organization.main.id
+      }
+
+      resource "aiven_organization_project" "example_project_in_org" {
+        project_id       = "example-project-in-organization"
+        organization_id  = data.aiven_organization.main.id
+        billing_group_id = "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
+      }
+
+      resource "aiven_organization_project" "example_project_in_unit" {
+        project_id       = "example-project-in-unit"
+        parent_id        = aiven_organizational_unit.example_unit.id
+        organization_id  = data.aiven_organization.main.id
+        billing_group_id = "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
+      }
+     ```
+
+2. Replace all references to `aiven_project` resources with the new `aiven_organization_project` resources. 
+
+   In the following example, a PostgreSQL service references the `aiven_project` resource:
+
+      ```hcl
+      resource "aiven_pg" "example_postgres" {
+        project = aiven_project.example_project.project
+        ...
+      }
+      ```
+
+   Replace `aiven_project` with `aiven_organization_project` and `project` with `project_id`:
+
+      ```hcl
+      resource "aiven_pg" "example_postgres" {
+        project = aiven_organization_project.example_project.project_id
+        ...
+      }
+      ```
+
+3. Replace all `aiven_project` data sources with the `aiven_organization_project` data source. Change the `project` attribute to `project_id` and
+   add the `organization_id` attribute.
+
+   For example, given the following `aiven_project` data source:
+      ```hcl
+        resource "aiven_project" "example_project" {
+        project   = "example-project"
+      }
+      ```
+
+     The migrated data source with updated attributes is:
+
+      ```hcl
+        resource "aiven_organization_project" "example_project" {
+        project_id      = "example-project"
+        organization_id = data.aiven_organization.main.id
+      }
+      ```
+
+4. Replace all references to the `aiven_project` data sources with the new `aiven_organization_project` data sources. Change `project` to `project_id`.
+
+5. To remove the deprecated resource from Terraform's control, run:
+
+    ```bash
+    terraform state rm aiven_project.example_project
+    ```
+
+6. Add the new project resources by [importing them](https://registry.terraform.io/providers/aiven/aiven/latest/docs/guides/importing-resources). For example:
+
+    ```bash
+    terraform import aiven_organization_project.example_project org12345678/example-project
+    ```
+
+7. To confirm the migration is complete, check that there are no changes by running:
+
+    ```bash
+    terraform plan
+    ```
+
 ## Update `aiven_redis` resources after Valkey upgrade
 
 After you [upgrade from Aiven for Caching to Aiven for Valkey™](https://aiven.io/docs/products/caching/howto/upgrade-aiven-for-caching-to-valkey), update your

docs/resources/organization_project.md

@@ -18,17 +18,25 @@ the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource.
 ## Example Usage
 
 ```terraform
-resource "aiven_organization_project" "foo" {
-  project_id = "example-project"
-
-  organization_id = aiven_organization.foo.id
-  billing_group_id = aiven_billing_group.foo.id
+# Create a project within an organization
+resource "aiven_organization_project" "example_project" {
+  project_id       = "example-project"
+  organization_id  = aiven_organization.main.id
+  billing_group_id = aiven_billing_group.main.id
 
   tag {
-    key = "key_1"
-    value = "value_1"
+    key   = "env"
+    value = "prod"
   }
 }
+
+# Create a project within an organizational unit
+resource "aiven_organization_project" "example_project" {
+  project_id       = "example-project"
+  organization_id  = aiven_organization.main.id
+  parent_id        = data.organizational_unit.example_unit.id
+  billing_group_id = aiven_billing_group.main.id
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
@@ -76,5 +84,5 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-terraform import aiven_organization.main ORGANIZATION_ID/PROJECT_ID
+terraform import aiven_organization_project.example_project ORGANIZATION_ID/PROJECT_ID
 ```

docs/resources/project.md

@@ -4,12 +4,17 @@ page_title: "aiven_project Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
   Creates and manages an Aiven project https://aiven.io/docs/platform/concepts/orgs-units-projects#projects.
+  ~> This resource is deprecated
+  Use aiven_organization_project instead and migrate your existing aiven_project resources https://registry.terraform.io/providers/aiven/aiven/latest/docs/guides/update-deprecated-resources to the new resource.
 ---
 
 # aiven_project (Resource)
 
 Creates and manages an [Aiven project](https://aiven.io/docs/platform/concepts/orgs-units-projects#projects).
 
+~> **This resource is deprecated**
+Use ``aiven_organization_project`` instead and [migrate your existing `aiven_project` resources](https://registry.terraform.io/providers/aiven/aiven/latest/docs/guides/update-deprecated-resources) to the new resource.
+
 ## Example Usage
 
 ```terraform

examples/resources/aiven_organization_project/import.sh

@@ -1 +1 @@
-terraform import aiven_organization.main ORGANIZATION_ID/PROJECT_ID
+terraform import aiven_organization_project.example_project ORGANIZATION_ID/PROJECT_ID

examples/resources/aiven_organization_project/resource.tf

@@ -1,11 +1,19 @@
-resource "aiven_organization_project" "foo" {
-  project_id = "example-project"
-
-  organization_id = aiven_organization.foo.id
-  billing_group_id = aiven_billing_group.foo.id
+# Create a project within an organization
+resource "aiven_organization_project" "example_project" {
+  project_id       = "example-project"
+  organization_id  = aiven_organization.main.id
+  billing_group_id = aiven_billing_group.main.id
 
   tag {
-    key = "key_1"
-    value = "value_1"
+    key   = "env"
+    value = "prod"
   }
+}
+
+# Create a project within an organizational unit
+resource "aiven_organization_project" "example_project" {
+  project_id       = "example-project"
+  organization_id  = aiven_organization.main.id
+  parent_id        = data.organizational_unit.example_unit.id
+  billing_group_id = aiven_billing_group.main.id
 }

internal/sdkprovider/service/project/project.go

@@ -127,11 +127,12 @@ var aivenProjectSchema = map[string]*schema.Schema{
 
 func ResourceProject() *schema.Resource {
 	return &schema.Resource{
-		Description:   "Creates and manages an [Aiven project](https://aiven.io/docs/platform/concepts/orgs-units-projects#projects).",
-		CreateContext: resourceProjectCreate,
-		ReadContext:   resourceProjectRead,
-		UpdateContext: resourceProjectUpdate,
-		DeleteContext: resourceProjectDelete,
+		Description:        "Creates and manages an [Aiven project](https://aiven.io/docs/platform/concepts/orgs-units-projects#projects).",
+		DeprecationMessage: "Use `aiven_organization_project` instead and [migrate your existing aiven_project resources](https://registry.terraform.io/providers/aiven/aiven/latest/docs/guides/update-deprecated-resources) to the new resource.",
+		CreateContext:      resourceProjectCreate,
+		ReadContext:        resourceProjectRead,
+		UpdateContext:      resourceProjectUpdate,
+		DeleteContext:      resourceProjectDelete,
 		Importer: &schema.ResourceImporter{
 			StateContext: schema.ImportStatePassthroughContext,
 		},

templates/guides/update-deprecated-resources.md

@@ -421,6 +421,125 @@ resource "aiven_account_team_project" "main" {
    terraform state list
    ```
 
+## Migrate `aiven_project` to `aiven_organization_project`
+
+The `aiven_project` resource and data source have been replaced by [`aiven_organization_project`](https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/organization_project).
+Migrate your existing project resources and data sources by replacing them with `aiven_organization_project`.
+
+1. Replace all `aiven_project` resources with the `aiven_organization_project` resource.
+   * Change the `project` attribute to `project_id`. Don't change the value.
+   * Add the `organization_id`.
+   * For projects in an organizational unit, keep the `parent_id` attribute.
+   * Add the `billing_group_id`. You can [get the IDs from the Aiven Console](https://docs.aiven.io/docs/platform/reference/get-resource-IDs).
+
+   For example, the following file has one project in an organization and one in an organizational unit:
+
+      ```hcl
+      data "aiven_organization" "main" {
+        name = "Example organization"
+      }
+
+      resource "aiven_organizational_unit" "example_unit" {
+        name      = "Production"
+        parent_id = data.aiven_organization.main.id
+      }
+
+      resource "aiven_project" "example_project_in_org" {
+        project   = "example-project-in-organization"
+        parent_id = data.aiven_organization.main.id
+      }
+
+      resource "aiven_project" "example_project_in_unit" {
+        project   = "example-project-in-unit"
+        parent_id = aiven_organizational_unit.example_unit.id
+      }
+     ```
+
+     The updated file with the new `aiven_organization_project` resource is:
+
+      ```hcl
+      data "aiven_organization" "main" {
+        name = "Example organization"
+      }
+
+      resource "aiven_organizational_unit" "example_unit" {
+        name      = "Production"
+        parent_id = data.aiven_organization.main.id
+      }
+
+      resource "aiven_organization_project" "example_project_in_org" {
+        project_id       = "example-project-in-organization"
+        organization_id  = data.aiven_organization.main.id
+        billing_group_id = "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
+      }
+
+      resource "aiven_organization_project" "example_project_in_unit" {
+        project_id       = "example-project-in-unit"
+        parent_id        = aiven_organizational_unit.example_unit.id
+        organization_id  = data.aiven_organization.main.id
+        billing_group_id = "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
+      }
+     ```
+
+2. Replace all references to `aiven_project` resources with the new `aiven_organization_project` resources. 
+
+   In the following example, a PostgreSQL service references the `aiven_project` resource:
+
+      ```hcl
+      resource "aiven_pg" "example_postgres" {
+        project = aiven_project.example_project.project
+        ...
+      }
+      ```
+
+   Replace `aiven_project` with `aiven_organization_project` and `project` with `project_id`:
+
+      ```hcl
+      resource "aiven_pg" "example_postgres" {
+        project = aiven_organization_project.example_project.project_id
+        ...
+      }
+      ```
+
+3. Replace all `aiven_project` data sources with the `aiven_organization_project` data source. Change the `project` attribute to `project_id` and
+   add the `organization_id` attribute.
+
+   For example, given the following `aiven_project` data source:
+      ```hcl
+        resource "aiven_project" "example_project" {
+        project   = "example-project"
+      }
+      ```
+
+     The migrated data source with updated attributes is:
+
+      ```hcl
+        resource "aiven_organization_project" "example_project" {
+        project_id      = "example-project"
+        organization_id = data.aiven_organization.main.id
+      }
+      ```
+
+4. Replace all references to the `aiven_project` data sources with the new `aiven_organization_project` data sources. Change `project` to `project_id`.
+
+5. To remove the deprecated resource from Terraform's control, run:
+
+    ```bash
+    terraform state rm aiven_project.example_project
+    ```
+
+6. Add the new project resources by [importing them](https://registry.terraform.io/providers/aiven/aiven/latest/docs/guides/importing-resources). For example:
+
+    ```bash
+    terraform import aiven_organization_project.example_project org12345678/example-project
+    ```
+
+7. To confirm the migration is complete, check that there are no changes by running:
+
+    ```bash
+    terraform plan
+    ```
+
 ## Update `aiven_redis` resources after Valkey upgrade
 
 After you [upgrade from Aiven for Caching to Aiven for Valkey™](https://aiven.io/docs/products/caching/howto/upgrade-aiven-for-caching-to-valkey), update your