4.0 - Overview, Beta and Upgrade guides (#26759)

* add resources and data sources for removal

* add more resources and data sources that will be removed in 4.0

* add deprecated mysql resources and data source for removal

* add more deprecated resources

* add beta and overview guides for 4.0

* add deprecate properties for resources and data sources

* fix resource names

* remove some TODOs

* saving these updates here because i'm paranoid something will happen

* complete configmodeattr section

* fix typo

* add more breaking changes

* add upgrade guide documentation for subscription ID becoming required

* add detail on provider functions

* finish TODO deprecations and alphabetical ordering of changes

* add properties with changed default values

* add iothub configmodeattr change

* add stats on resources/data sources and clarify notes on ignore_changes

* add address_prefixes change for subnet block

* upgrade guide: add deprecated storage properties

* standardise on Azure Provider and fix typos

* add address_space change

* remove configmodeattr info after revert

* add additional changes and remove configmodeattr from the overview

---------

Co-authored-by: Tom Bamford <[email protected]>
Co-authored-by: jackofallops <[email protected]>

website/docs/guides/4.0-beta.html.markdown

@@ -0,0 +1,56 @@
+---
+layout: "azurerm"
+page_title: "Azure Resource Manager: Opting into the 4.0 Beta"
+description: |-
+Azure Resource Manager: Opting into Beta Functionality coming in version 4.0 of the Azure Provider
+
+---
+
+# Opting into Beta Functionality coming in version 4.0 of the Azure Provider
+
+Version 4.0 of the Azure Provider will introduce several new features ([full details can be found in the 4.0 Upgrade Guide](/docs/providers/azurerm/guides/4.0-upgrade-guide.html)):
+
+- Improved control and granularity over Resource Provider registration
+- Provider functions
+- Additional configuration options for Subnets defined in-line in the Virtual Network Resource.
+- Improved consistency in updating and removing lists and blocks
+
+Since both Azure and Terraform's Azure Provider move quickly - in order to continue rapidly shipping new features we've used Feature Toggles to gradually add support for the new functionality coming in version 4.0 of the Azure Provider as we've been developing 3.x versions of the Azure Provider.
+
+What this means is that the most recent 3.x versions of the Azure Provider are able to opt-into certain functionality coming in version 4.0 of the Azure Provider.
+
+This guide details how to enable these features and how you can submit feedback prior to the final release.
+
+## Disclaimers
+
+-> The functionality provided in this Beta is subject to change - as such **this Beta should not be used in Production**.
+
+-> Once opted in, it will not be possible to opt-out of the Beta, this is because the new functionality and removal of deprecated functionality in 4.0 will make **irreversible changes to the Terraform state**. We recommend making backups of your environment and state files before activating the Beta in case a rollback of the environment is required.
+
+-> Whilst certain feature flags may be available in earlier versions of the Azure Provider they existed in an incomplete manner - **the Beta is only supported when using version 3.114 (or later) of the Azure Provider**.
+
+## 4.0 Features, Removals and Deprecations
+
+It's possible to opt into the Beta by setting the Environment Variable `ARM_FOURPOINTZERO_BETA` to `true`.
+
+On a macOS/Linux system you can do this via:
+
+```bash
+export ARM_FOURPOINTZERO_BETA=true
+```
+
+On a Windows System (in PowerShell) you can do this via:
+
+```powershell
+[System.Environment]::SetEnvironmentVariable('ARM_FOURPOINTZERO_BETA', 'true', [System.EnvironmentVariableTarget]::User)
+```
+
+-> **Note:** You may need to reload/re-open your Terminal after setting this Environment Variable.
+
+---
+
+## Providing Feedback
+
+Firstly - thanks for trialling the new functionality coming in version 4.0 of the Azure Provider.
+
+We're keeping track of Beta Feedback in the GitHub Repository - as such [please follow this link to open an issue containing your feedback](https://github.com/terraform-providers/terraform-provider-azurerm/issues/new?template=Beta_Feedback.md).

website/docs/guides/4.0-overview.html.markdown

@@ -0,0 +1,62 @@
+---
+layout: "azurerm"
+page_title: "Azure Resource Manager: Upcoming Version 4.0 of the Azure Provider"
+description: |-
+Azure Resource Manager: Upcoming Version 4.0 of the Azure Provider
+---
+
+# Upcoming Version 4.0 of the Azure Provider
+
+-> **Note:** Since this documentation is versioned, we recommend checking [the latest version of this document](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/4.0-overview).
+
+Version 4.0 of the Azure Provider will be a major release, which means that this will include breaking changes as required, in addition to new functionality and bug fixes.
+
+During the development of version 2.0 as well as 3.0 of the Azure Provider we made use of Feature Toggling to gradually add support for the new functionality. This allows users to try out the next major release of the provider in non-production environments, to get a sense of the upcoming changes that will be required in their configuration and to provide invaluable feedback on the changes.
+
+We have used the same approach for version 4.0 of the Azure Provider too, providing an opt-in Beta for the changes coming in version 4.0 whilst using 3.x versions of the Azure Provider.
+
+Since we'll be iteratively adding this functionality over time, we encourage you to use the latest version of the Azure Provider when using this functionality. Please note that this is subject to change (including breaking changes) prior to the release of version 4.0 of the Azure Provider. In addition, an upgrade guide containing the detailed changes coming in version 4.0 of the Azure Provider has been made available and can be found [here](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/4.0-upgrade-guide).
+
+## Disclaimer
+
+Important to note is that the activation of the Beta should **only be done in non-production environments** and the **activation is non-reversible** since the changes in 4.0 will affect the Terraform state. We recommend making backups of the environment and state files that you will be testing the beta in, in case a rollback is required.
+
+## Pinning to a 3.x version of the Azure Provider
+
+We recommend pinning the version of each Provider you use in Terraform, for example:
+
+```hcl
+terraform {
+  required_providers {
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = "=3.112.0"
+    }
+  }
+}
+
+# Configure the Microsoft Azure Provider
+provider "azurerm" {
+  features {}
+}
+```
+
+## What's available in Version 4.0 of the Azure Provider?
+
+-> **Note:** Since new functionality is being added iteratively, this page will be updated as new functionality is added to the 4.0 Beta
+
+Version 4.0 of the Azure Provider is a work-in-progress, as such only functionality which is currently available is documented here.
+
+Below is a brief overview of the biggest changes and new features coming in 4.0. For more details on these please see the [4.0 upgrade guide](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/4.0-upgrade-guide).
+
+### Improved Resource Provider Registration
+
+Resource Provider Registration within the provider will be defined with better clarity and gives users more control over which resource providers to automatically register.
+
+### Provider Functions
+
+With the introduction of provider functions in Terraform 1.8, we'll be introducing two new Azure specific provider functions for Azure Resource IDs in 4.0.
+
+### Additional Configuration Options for Subnets defined in the Virtual Network Resource
+
+We've extended the `subnet` block within the `azurerm_virtual_network` resource to allow creation of subnets with delegations and route tables, among other options.