Upgrade guide for v3.0

docs/guides/3.0-upgrade-guide.md

@@ -0,0 +1,142 @@
+---
+page_title: "Upgrade Guide for AzureAD v3.0"
+subcategory: "Upgrade Guides"
+---
+
+# Upgrade Guide for AzureAD Provider v3.0
+
+The last major release for the AzureAD provider was in August 2021. At the last release, we moved from the legacy Azure AD Graph API to Microsoft Graph, and began using our own handwritten SDK. The provider now supports 56 Resources and 21 Data Sources. 
+
+Over the past several months, we have been working to produce a more feature-complete [Microsoft Graph SDK](https://github.com/hashicorp/go-azure-sdk/tree/main/microsoft-graph), and now the AzureAD provider has migrated to this SDK. This opens up many possibilities for new resources, and improves performance and reliability across the entire provider.
+
+Due to the large nature of this change, we have elected to publish a new major version 3.0, whilst also removing some deprecated properties. This guide explains these changes.
+
+## Pinning your provider version
+
+We recommend pinning the version of each provider you use in Terraform. You can do this using the `version` attribute in the `required_providers` block of your `terraform` configuration block.
+
+To pin to a specific version of the AzureAD provider:
+
+```hcl
+terraform {
+  required_providers {
+    azuread = {
+      source  = "hashicorp/azuread"
+      version = "= 2.53.1"
+    }
+  }
+}
+```
+
+To pin to any 2.53.x release:
+
+```hcl
+terraform {
+  required_providers {
+    azuread = {
+      source  = "hashicorp/azuread"
+      version = "~> 2.53.0"
+    }
+  }
+}
+```
+
+To pin to any 2.x release:
+
+```hcl
+terraform {
+  required_providers {
+    azuread = {
+      source  = "hashicorp/azuread"
+      version = "~> 2.0"
+    }
+  }
+}
+```
+
+This will enable you to upgrade to version 3.0 at your convenience, by simply advancing the desired target version in your configuration. See the [Lock and Upgrade Provider Versions](https://learn.hashicorp.com/tutorials/terraform/provider-versioning) guide on HashiCorp Learn for more details.
+
+## Upgrading to version 3.0
+
+We recommend upgrading in a test environment prior to upgrading your production modules. Please be aware that there may be bugs in the initial releases of the new major version. As per the above instructions for pinning the provider version, you can upgrade to the latest 3.0 release by setting the following version constraint in your configuration:
+
+```hcl
+terraform {
+  required_providers {
+    azuread = {
+      source  = "hashicorp/azuread"
+      version = "~> 3.0"
+    }
+  }
+}
+```
+
+Please report any issues you may encounter on [our bug tracker](https://github.com/hashicorp/terraform-provider-azuread/issues). We appreciate feedback from our users!
+
+## Deprecated fields
+
+The following attributes/properties have been deprecated in version 3.0 of the AzureAD provider, and will be removed in a future release.
+
+### Resource: `azuread_application_certificate`
+
+The property `end_date_relative` has been deprecated and will be removed in a future release. Please use the `end_date` property instead. Note that you can make use of the Terraform [`timeadd()` function](https://developer.hashicorp.com/terraform/language/functions/timeadd) to calculate a relative future date.
+
+### Resource: `azuread_application_password`
+
+The property `end_date_relative` has been deprecated and will be removed in a future release. Please use the `end_date` property instead. Note that you can make use of the Terraform [`timeadd()` function](https://developer.hashicorp.com/terraform/language/functions/timeadd) to calculate a relative future date.
+
+### Resource: `azuread_service_principal_certificate`
+
+The property `end_date_relative` has been deprecated and will be removed in a future release. Please use the `end_date` property instead. Note that you can make use of the Terraform [`timeadd()` function](https://developer.hashicorp.com/terraform/language/functions/timeadd) to calculate a relative future date.
+
+### Resource: `azuread_service_principal_password`
+
+The property `end_date_relative` has been deprecated and will be removed in a future release. Please use the `end_date` property instead. Note that you can make use of the Terraform [`timeadd()` function](https://developer.hashicorp.com/terraform/language/functions/timeadd) to calculate a relative future date.
+
+## Removal of deprecated fields
+
+The following attributes/properties were deprecated in 2.x versions of the AzureAD provider, and have now been removed in version 3.0.
+
+### Data Source: `azuread_application`
+
+The property `application_id` has been replaced by the `client_id` property.
+
+### Resource: `azuread_application`
+
+The property `application_id` has been replaced by the `client_id` property.
+
+### Resource: `azuread_application_certificate`
+
+The property `application_object_id` has been replaced by the `application_id` property. Please refer to the [latest documentation for this resource](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_certificate) for example usage.
+
+### Resource: `azuread_application_federated_identity_credential`
+
+The property `application_object_id` has been replaced by the `application_id` property. Please refer to the [latest documentation for this resource](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_federated_identity_credential) for example usage.
+
+### Resource: `azuread_application_password`
+
+The property `application_object_id` has been replaced by the `application_id` property. Please refer to the [latest documentation for this resource](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_password) for example usage.
+
+### Resource: `azuread_application_pre_authorized`
+
+The property `application_object_id` has been replaced by the `application_id` property. Please refer to the [latest documentation for this resource](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_pre_authorized) for example usage.
+
+The property `authorized_app_id` has been replaced by the `authorized_client_id` property.
+
+### Resource: `azuread_directory_role_assignment`
+
+The property `app_scope_object_id` has been replaced by the `app_scope_id` property.
+
+### Data Source: `azuread_service_principal`
+
+The property `application_id` has been replaced by the `client_id` property.
+
+### Resource: `azuread_service_principal`
+
+The property `application_id` has been replaced by the `client_id` property.
+
+### Data Source: `azuread_service_principals`
+
+The property `application_ids` has been replaced by the `client_ids` property.
+
+The attribute `application_id` has been replaced by the `client_id` attribute.