Documentaton about azurerm_mssql_* and azurerm_sql_* need more clarification

[mathcantin]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Terraform (and AzureRM Provider) Version

Issue with the documentation with azurerm 2.40.0.

Affected Resource(s)

• azurerm_mssql_database
• azurerm_mssql_database_extended_auditing_policy
• azurerm_mssql_database_vulnerability_assessment_rule_baseline
• azurerm_mssql_elasticpool
• azurerm_mssql_server
• azurerm_mssql_server_extended_auditing_policy
• azurerm_mssql_server_security_alert_policy
• azurerm_mssql_server_vulnerability_assessment
• azurerm_sql_active_directory_administrator
• azurerm_sql_database
• azurerm_sql_elasticpool
• azurerm_sql_failover_group
• azurerm_sql_firewall_rule
• azurerm_sql_server
• azurerm_sql_virtual_network_rule

Expected Behaviour

This isn't a bug and I'm not sur I'm in the right place for that, but I think the documentation is confusing for theses resources. In one case we have a deprecation notice (azurerm_sql_elasticpool, but for every others resources we don't have deprecation.

In the most of cases, both manage the same resource in Azure, like azurerm_mssql_database and azurerm_sql_database who manage Microsoft.Sql/servers/myserver/databases/mydatabase.

And examples aren't good to help, like in the azurerm_mssql_database the example usage use azurerm_sql_server instead of azurerm_mssql_server.

Are there any depreciated resources? Why am I supposed to use one resource over another? Are there any bugs to fix in one version, but not in the other?

I believe the documentation would benefit from documenting the differences.

[sharebear]

I realise this is on the borderline of a "me too" comment but I'll try and add some relevant information from what I concluded after just spending half an hour investigating around this.

1. I was just asked to set the minimum TLS version, this is not available via the azurerm_sql_server resource but is available via azurerm_mssql_server this is hinting that perhaps I chose the wrong server resource.
2. The Azure portal calls this an "SQL Server" not an "MSSQL Server", that combined with discrepancy in the documentation noted in the issue discription probably lead to my choosing azurerm_sql_server last autumn.
3. Looking at the PR where azurerm_mssql_server was introduced (#6677) there's no information in the description or commit comments about why this is a new resource instead of updating the existing resource. Is there a discussion somewhere to undertstand the differences? (/cc @katbyte )
4. Crossing fingers that switching requires little more than terraform state mv, path for migration from old to new would be nice to document if the old one is truly deprecated.