Update docs for v2.11 (#4443)

Includes details about when we will deprecate CRD versions in order to
keep CRDs from growing too large.

Fixes #2687.

Author: matthchr

docs/hugo/content/contributing/create-a-new-release.md

@@ -60,7 +60,7 @@ Perform a simple smoke test to make sure the new release is capable of starting
 
 3. Enable workload identity on that cluster:
    ```
-   task: controller:create-mi-for-workload-identity
+   task controller:create-mi-for-workload-identity
    ```
 
 4. Install cert-manager
@@ -101,7 +101,7 @@ Perform a simple smoke test to make sure the new release is capable of starting
 
     ``` bash
     kubectl apply -f v2/samples/resources/v1api/v1api20200601_resourcegroup.yaml
-    kubectl apply -f v2/samples/network/v1api20201101/v1api20201101_virtualnetwork.yaml
+    kubectl apply -f v2/samples/network/v1api20240301/v1api20240301_virtualnetwork.yaml
     ```
 11. Make sure they deploy successfully - check in the portal as well.
 

docs/hugo/content/guide/crd-management.md

@@ -129,6 +129,31 @@ The recommended workflow for removing CRDs you are no longer using is:
 4. Delete the CRD using `kubectl delete`.
 5. Start the operator pod.
 
+## Number of versions supported in a CRD
+
+There is a limit to how large a CRD can be.
+
+Each time a new version is added to a CRD it gets bigger. Large CRDs, those with many properties or deeply nested 
+properties, will fit fewer versions before they run into the CRD size limit.
+
+In order to keep CRDs under the size limit, ASO will periodically remove older versions of CRDs that are approaching
+the size limit. When doing this we will adhere to the following rules:
+
+* Give at least 1 release advanced notice before a CRD version is removed. Look for the "upcoming breaking changes" 
+  section of the release notes.
+* Remove older versions first to make room for newer ones.
+* Remove preview versions before removing stable versions.
+* Always keep at least the latest 2 stable versions and the latest 1 preview version (if applicable, 
+  not all resources have preview versions). Some resources may retain more than this, but we'll never retain less than
+  this.
+
+For manually installed CRDs, [`asoctl clean crds`]( {{< relref "asoctl#clean-crds" >}} ) can be used to prepare
+CRDs for upgrade when a CRD version that was previously a storage version was removed.
+
+For ASO managed CRDs, ASO will automatically clean up the old storage versions when it's upgraded to the new version
+that removed those CRDs. **Note:** This is not yet implemented, it is being tracked by 
+[#4376](https://github.com/Azure/azure-service-operator/issues/4376).
+
 ## Best Practices
 
 * Do not use `crdPattern=*` on AKS free tier clusters. It installs so many CRDs that it can overload kube-apiserver and cause

docs/hugo/content/reference/_index.md

@@ -5,19 +5,12 @@ no_list: true
 ---
 To install the CRDs for these resources, your ASO configuration must include `alertsmanagement.azure.com/*` as a one of the configured CRD patterns. See [CRD Management in ASO](https://azure.github.io/azure-service-operator/guide/crd-management/) for details on doing this for both [Helm](https://azure.github.io/azure-service-operator/guide/crd-management/#helm) and [YAML](https://azure.github.io/azure-service-operator/guide/crd-management/#yaml) based installations.
 
-### Next Release
-
-Development of these new resources is complete and they will be available in the next release of ASO.
-
-| Resource               | ARM Version | CRD Version   | Supported From | Sample                                                                                                                                                |
-|------------------------|-------------|---------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
-| SmartDetectorAlertRule | 2021-04-01  | v1api20210401 | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/alertsmanagement/v1api20210401/v1api20210401_smartdetectoralertrule.yaml) |
-
 ### Released
 
 These resource(s) are available for use in the current release of ASO. Different versions of a given resource reflect different versions of the Azure ARM API.
 
-| Resource                                                                                                                                                                     | ARM Version | CRD Version   | Supported From | Sample                                                                                                                                             |
-|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
-| [PrometheusRuleGroup](https://azure.github.io/azure-service-operator/reference/alertsmanagement/v1api20230301/#alertsmanagement.azure.com/v1api20230301.PrometheusRuleGroup) | 2023-03-01  | v1api20230301 | v2.8.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/alertsmanagement/v1api20230301/v1api20230301_prometheusrulegroup.yaml) |
+| Resource                                                                                                                                                                     | ARM Version | CRD Version   | Supported From | Sample                                                                                                                                                |
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [PrometheusRuleGroup](https://azure.github.io/azure-service-operator/reference/alertsmanagement/v1api20230301/#alertsmanagement.azure.com/v1api20230301.PrometheusRuleGroup) | 2023-03-01  | v1api20230301 | v2.8.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/alertsmanagement/v1api20230301/v1api20230301_prometheusrulegroup.yaml)    |
+| SmartDetectorAlertRule                                                                                                                                                       | 2021-04-01  | v1api20210401 | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/alertsmanagement/v1api20210401/v1api20210401_smartdetectoralertrule.yaml) |
 

docs/hugo/content/reference/alertsmanagement/_index.md

@@ -5,17 +5,6 @@ no_list: true
 ---
 To install the CRDs for these resources, your ASO configuration must include `containerservice.azure.com/*` as a one of the configured CRD patterns. See [CRD Management in ASO](https://azure.github.io/azure-service-operator/guide/crd-management/) for details on doing this for both [Helm](https://azure.github.io/azure-service-operator/guide/crd-management/#helm) and [YAML](https://azure.github.io/azure-service-operator/guide/crd-management/#yaml) based installations.
 
-### Next Release
-
-Development of these new resources is complete and they will be available in the next release of ASO.
-
-| Resource                                                                                                                                                                               | ARM Version | CRD Version   | Supported From | Sample                                                                                                                                                  |
-|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [MaintenanceConfiguration](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.MaintenanceConfiguration) | 2024-09-01  | v1api20240901 | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_maintenanceconfiguration.yaml) |
-| [ManagedCluster](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.ManagedCluster)                     | 2024-09-01  | v1api20240901 | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_managedcluster.yaml)           |
-| [ManagedClustersAgentPool](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.ManagedClustersAgentPool) | 2024-09-01  | v1api20240901 | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_managedclustersagentpool.yaml) |
-| [TrustedAccessRoleBinding](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.TrustedAccessRoleBinding) | 2024-09-01  | v1api20240901 | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_trustedaccessrolebinding.yaml) |
-
 ### Released
 
 These resource(s) are available for use in the current release of ASO. Different versions of a given resource reflect different versions of the Azure ARM API.
@@ -25,16 +14,20 @@ These resource(s) are available for use in the current release of ASO. Different
 | [Fleet](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20230315preview/#containerservice.azure.com/v1api20230315preview.Fleet)                                       | 2023-03-15-preview | v1api20230315preview | v2.4.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20230315preview/v1api20230315preview_fleet.yaml)                    |
 | [FleetsMember](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20230315preview/#containerservice.azure.com/v1api20230315preview.FleetsMember)                         | 2023-03-15-preview | v1api20230315preview | v2.4.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20230315preview/v1api20230315preview_fleetsmember.yaml)             |
 | [FleetsUpdateRun](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20230315preview/#containerservice.azure.com/v1api20230315preview.FleetsUpdateRun)                   | 2023-03-15-preview | v1api20230315preview | v2.4.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20230315preview/v1api20230315preview_fleetsupdaterun.yaml)          |
+| [MaintenanceConfiguration](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.MaintenanceConfiguration)               | 2024-09-01         | v1api20240901        | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_maintenanceconfiguration.yaml)               |
+| [ManagedCluster](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.ManagedCluster)                                   | 2024-09-01         | v1api20240901        | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_managedcluster.yaml)                         |
 | [ManagedCluster](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240402preview/#containerservice.azure.com/v1api20240402preview.ManagedCluster)                     | 2024-04-02-preview | v1api20240402preview | v2.8.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240402preview/v1api20240402preview_managedcluster.yaml)           |
 | [ManagedCluster](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20231102preview/#containerservice.azure.com/v1api20231102preview.ManagedCluster)                     | 2023-11-02-preview | v1api20231102preview | v2.6.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20231102preview/v1api20231102preview_managedcluster.yaml)           |
 | [ManagedCluster](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20231001/#containerservice.azure.com/v1api20231001.ManagedCluster)                                   | 2023-10-01         | v1api20231001        | v2.5.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20231001/v1api20231001_managedcluster.yaml)                         |
 | [ManagedCluster](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20230201/#containerservice.azure.com/v1api20230201.ManagedCluster)                                   | 2023-02-01         | v1api20230201        | v2.0.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20230201/v1api20230201_managedcluster.yaml)                         |
 | [ManagedCluster](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20210501/#containerservice.azure.com/v1api20210501.ManagedCluster)                                   | 2021-05-01         | v1api20210501        | v2.0.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20210501/v1api20210501_managedcluster.yaml)                         |
+| [ManagedClustersAgentPool](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.ManagedClustersAgentPool)               | 2024-09-01         | v1api20240901        | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_managedclustersagentpool.yaml)               |
 | [ManagedClustersAgentPool](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240402preview/#containerservice.azure.com/v1api20240402preview.ManagedClustersAgentPool) | 2024-04-02-preview | v1api20240402preview | v2.8.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240402preview/v1api20240402preview_managedclustersagentpool.yaml) |
 | [ManagedClustersAgentPool](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20231102preview/#containerservice.azure.com/v1api20231102preview.ManagedClustersAgentPool) | 2023-11-02-preview | v1api20231102preview | v2.6.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20231102preview/v1api20231102preview_managedclustersagentpool.yaml) |
 | [ManagedClustersAgentPool](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20231001/#containerservice.azure.com/v1api20231001.ManagedClustersAgentPool)               | 2023-10-01         | v1api20231001        | v2.5.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20231001/v1api20231001_managedclustersagentpool.yaml)               |
 | [ManagedClustersAgentPool](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20230201/#containerservice.azure.com/v1api20230201.ManagedClustersAgentPool)               | 2023-02-01         | v1api20230201        | v2.0.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20230201/v1api20230201_managedclustersagentpool.yaml)               |
 | [ManagedClustersAgentPool](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20210501/#containerservice.azure.com/v1api20210501.ManagedClustersAgentPool)               | 2021-05-01         | v1api20210501        | v2.0.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20210501/v1api20210501_managedclustersagentpool.yaml)               |
+| [TrustedAccessRoleBinding](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240901/#containerservice.azure.com/v1api20240901.TrustedAccessRoleBinding)               | 2024-09-01         | v1api20240901        | v2.11.0        | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240901/v1api20240901_trustedaccessrolebinding.yaml)               |
 | [TrustedAccessRoleBinding](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20240402preview/#containerservice.azure.com/v1api20240402preview.TrustedAccessRoleBinding) | 2024-04-02-preview | v1api20240402preview | v2.8.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20240402preview/v1api20240402preview_trustedaccessrolebinding.yaml) |
 | [TrustedAccessRoleBinding](https://azure.github.io/azure-service-operator/reference/containerservice/v1api20231001/#containerservice.azure.com/v1api20231001.TrustedAccessRoleBinding)               | 2023-10-01         | v1api20231001        | v2.8.0         | [View](https://github.com/Azure/azure-service-operator/tree/main/v2/samples/containerservice/v1api20231001/v1api20231001_trustedaccessrolebinding.yaml)               |