refactor documents (#5088)

Author: dtzar

README.md

@@ -19,12 +19,19 @@
 
 Kubernetes-native declarative infrastructure for Azure.
 
-## What is the Cluster API Provider Azure
+## What is the Cluster API Provider Azure (CAPZ)
 
 The [Cluster API][cluster_api] brings declarative, Kubernetes-style APIs to cluster creation, configuration and management.
 
-The API itself is shared across multiple cloud providers allowing for true Azure
-hybrid deployments of Kubernetes.
+The API itself is shared across multiple cloud providers allowing for true Azure hybrid deployments of Kubernetes.
+
+CAPZ enables efficient management at scale of self-managed or managed (AKS) clusters on Azure.  Furthermore, the CAPZ management cluster can be utilized with the automatically installed Azure Service Operator (ASO) installation dependency to manage any Azure infrastructure.  For more information see the [roadmap high level vision](https://capz.sigs.k8s.io/roadmap#high-level-vision).
+
+## Documentation
+
+Please see our [Book](https://capz.sigs.k8s.io) for in-depth user documentation.
+
+Additional docs can be found in the `/docs` directory, and the [index is here](https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/main/docs/README.md).
 
 ## Quick Start
 
@@ -58,12 +65,6 @@ For more information on Kubernetes version support, see the [Cluster API book](h
 
 ------
 
-## Documentation
-
-Please see our [Book](https://capz.sigs.k8s.io) for in-depth user documentation.
-
-Additional docs can be found in the `/docs` directory, and the [index is here](https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/main/docs/README.md).
-
 ## Getting involved and contributing
 
 Are you interested in contributing to cluster-api-provider-azure? We, the

docs/README.md

@@ -23,3 +23,9 @@
 ## Troubleshooting
 
 - [Troubleshooting guide](https://capz.sigs.k8s.io/topics/troubleshooting.html)
+
+## Docs contributors
+
+To run the link check linter, execute the following command from the root of the repository:
+
+`find . -name '*.md' -not -path './node_modules/*' -exec markdown-link-check '{}' --config .markdownlinkcheck.json -q ';'`

docs/book/src/SUMMARY.md

@@ -1,45 +1,51 @@
 # Summary
 
 [Introduction](./introduction.md)
+[Getting Started](./getting-started.md)
 [Roadmap](./roadmap.md)
-- [Topics](./topics/topics.md)
-    - [Getting Started](./topics/getting-started.md)
-    - [Troubleshooting](./topics/troubleshooting.md)
-    - [AAD Integration](./topics/aad-integration.md)
-    - [Addons](./topics/addons.md)
-    - [API Server Endpoint](./topics/api-server-endpoint.md)
+- [General Topics](./topics/topics.md)
     - [Azure Service Operator](./topics/aso.md)
-    - [Cloud Provider Config](./topics/cloud-provider-config.md)
     - [ClusterClass](./topics/clusterclass.md)
-    - [Control Plane Outbound Load Balancer](./topics/control-plane-outbound-lb.md)
-    - [Custom Images](./topics/custom-images.md)
-    - [Custom Private DNS Zone Name](./topics/custom-dns.md)
-    - [Custom VM Extensions](./topics/custom-vm-extensions.md)
-    - [Disks](./topics/disks.md)
-        - [Data Disks](./topics/data-disks.md)
-        - [OS Disk](./topics/os-disk.md)
-        - [Disk Encryption](./topics/disk-encryption.md)
-    - [Dual-Stack](./topics/dual-stack.md)
-    - [Externally managed Azure infrastructure](./topics/externally-managed-azure-infrastructure.md)
-    - [Failure Domains](./topics/failure-domains.md)
-    - [Flatcar](./topics/flatcar.md)
-    - [GPU-enabled Clusters](./topics/gpu.md)
-    - [Confidential VMs](./topics/confidential-vms.md)
-    - [Trusted Launch for VMs](./topics/trusted-launch-for-vms.md)
     - [Identities](./topics/identities.md)
+        - [AAD Integration](./topics/aad-integration.md)
         - [Identity use cases](./topics/identities-use-cases.md)
         - [Multi-tenancy](./topics/multitenancy.md)
         - [Workload Identity](./topics/workload-identity.md)
-    - [IPv6](./topics/ipv6.md)
-    - [Machine Pools (VMSS)](./topics/machinepools.md)
-    - [Managed Clusters (AKS)](./topics/managedcluster.md)
-    - [Node Outbound Connection](./topics/node-outbound-connection.md)
-    - [Spot Virtual Machines](./topics/spot-vms.md)
-    - [SSH Access to nodes](./topics/ssh-access.md)
-    - [Virtual Networks](./topics/custom-vnet.md)
-    - [VM Identity](./topics/vm-identity.md)
-    - [Windows](./topics/windows.md)
-    - [WebAssembly / WASI Pods](./topics/wasi.md)
+- [Managed Clusters (AKS)](./managed/managed.md)
+    - [Adopting Clusters](./managed/adopting-clusters.md)
+    - [ASO Managed Clusters (AKS)](./managed/asomanagedcluster.md)
+    - [Managed Clusters (AKS)](./managed/managedcluster.md)
+    - [Managed Clusters - BYO VMSS Nodes](./managed/managedcluster-join-vmss.md)
+    - [Troubleshooting](./managed/troubleshooting.md)
+- [Self-managed Clusters](./self-managed/self-managed.md)
+    - [Addons](./self-managed/addons.md)
+    - [API Server Endpoint](./self-managed/api-server-endpoint.md)
+    - [Cloud Provider Config](./self-managed/cloud-provider-config.md)
+    - [Confidential VMs](./self-managed/confidential-vms.md)
+    - [Control Plane Outbound Load Balancer](./self-managed/control-plane-outbound-lb.md)
+    - [Custom Images](./self-managed/custom-images.md)
+    - [Custom Private DNS Zone Name](./self-managed/custom-dns.md)
+    - [Custom VM Extensions](./self-managed/custom-vm-extensions.md)
+    - [Disks](./self-managed/disks.md)
+        - [Data Disks](./self-managed/data-disks.md)
+        - [Disk Encryption](./self-managed/disk-encryption.md)
+        - [OS Disk](./self-managed/os-disk.md)
+    - [Dual-Stack](./self-managed/dual-stack.md)
+    - [Externally managed Azure infrastructure](./self-managed/externally-managed-azure-infrastructure.md)
+    - [Failure Domains](./self-managed/failure-domains.md)
+    - [Flatcar](./self-managed/flatcar.md)
+    - [GPU-enabled Clusters](./self-managed/gpu.md)
+    - [IPv6](./self-managed/ipv6.md)
+    - [Machine Pools (VMSS)](./self-managed/machinepools.md)
+    - [Node Outbound Connection](./self-managed/node-outbound-connection.md)
+    - [Spot Virtual Machines](./self-managed/spot-vms.md)
+    - [SSH Access to nodes](./self-managed/ssh-access.md)
+    - [Troubleshooting](./self-managed/troubleshooting.md)
+    - [Trusted Launch for VMs](./self-managed/trusted-launch-for-vms.md)
+    - [Virtual Networks](./self-managed/custom-vnet.md)
+    - [VM Identity](./self-managed/vm-identity.md)
+    - [WebAssembly / WASI Pods](./self-managed/wasi.md)
+    - [Windows](./self-managed/windows.md)
 - [Development](./developers/development.md)
     - [Kubernetes Developers](./developers/kubernetes-developers.md)
     - [Releasing](./developers/releasing.md)

docs/book/src/developers/development.md

@@ -122,7 +122,7 @@ Makefile targets and scripts are offered to work with go modules:
 
 ### Setting up the environment
 
-Your must have the Azure credentials as outlined in the [getting started prerequisites](../topics/getting-started.md#Prerequisites) section.
+You must have the Azure credentials as outlined in the [getting started prerequisites](../getting-started.md#Prerequisites) section.
 
 ### Tilt Requirements
 
@@ -163,7 +163,7 @@ kustomize_substitutions:
   AZURE_CLIENT_ID: <client-id>
 ```
 
-You should have these values saved from the [getting started prerequisites](../topics/getting-started.md#Prerequisites) section.
+You should have these values saved from the [getting started prerequisites](../getting-started.md#Prerequisites) section.
 
 To build a kind cluster and start Tilt, just run:
 
@@ -218,7 +218,7 @@ kustomize_substitutions:
 EOF
 ```
 
-Make sure to replace the credentials with the values from the [getting started prerequisites](../topics/getting-started.md#Prerequisites) section.
+Make sure to replace the credentials with the values from the [getting started prerequisites](../getting-started.md#Prerequisites) section.
 
 > `$REGISTRY` should be in the format `docker.io/<dockerhub-username>`
 
@@ -245,7 +245,7 @@ To delete the cluster:
 make delete-workload-cluster
 ```
 
-> Check out the [troubleshooting guide](../topics/troubleshooting.md) for common errors you might run into.
+> Check out the [self-managed](../self-managed/troubleshooting.md) and [managed](../managed/troubleshooting.md) troubleshooting guides for common errors you might run into.
 
 #### Viewing Telemetry
 
@@ -414,7 +414,7 @@ Create the cluster:
 make create-cluster
 ```
 
-> Check out the [troubleshooting](../topics/troubleshooting.md) guide for common errors you might run into.
+> Check out the [self-managed](../self-managed/troubleshooting.md) and [managed](../managed/troubleshooting.md) troubleshooting guides for common errors you might run into
 
 ### Instrumenting Telemetry
 Telemetry is the key to operational transparency. We strive to provide insight into the internal behavior of the
@@ -571,7 +571,7 @@ You can optionally set the following variables:
 | `KUBERNETES_VERSION`        | Desired Kubernetes version to test. You can pass in a definitive released version, e.g., "v1.24.0". If you want to use pre-released CI bits of a particular release you may use the "latest-" prefix, e.g., "latest-1.24"; you may use the very latest built CI bits from the kubernetes/kubernetes master branch by passing in "latest". If you provide a `KUBERNETES_VERSION` environment variable, you may not also use `CI_VERSION` (below). Use only one configuration variable to declare the version of Kubernetes to test. |
 | `CI_VERSION`                | Provide a custom CI version of Kubernetes (e.g., `v1.25.0-alpha.0.597+aa49dffc7f24dc`). If not specified, this will be determined from the KUBERNETES_VERSION above if it is an unreleased version. If you provide a `CI_VERSION` environment variable, you may not also use `KUBERNETES_VERSION` (above).                                                                                                                                                                                                                         |
 | `TEST_CCM`                  | Build a cluster that uses custom versions of the Azure cloud-provider cloud-controller-manager and node-controller-manager images                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `EXP_MACHINE_POOL`          | Use [Machine Pool](../topics/machinepools.md) for worker machines.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `EXP_MACHINE_POOL`          | Use [Machine Pool](../self-managed/machinepools.md) for worker machines.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `TEST_WINDOWS`              | Build a cluster that has Windows worker nodes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `REGISTRY`                  | Registry to push any custom k8s images or cloud provider images built.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `CLUSTER_TEMPLATE`          | Use a custom cluster template. It can be a path to a template under templates/, a path on the host or a link. If the value is not set, the script will choose the appropriate cluster template based on existing environment variables.                                                                                                                                                                                                                                                                                            |

docs/book/src/developers/releasing.md

@@ -156,7 +156,7 @@ Note: this step requires access to the Netlify site. If you don't have access, p
 
 #### Minor/Major Releases
 
-1. Follow the communications process for [pre-releases](#pre-releases)
+1. Follow the communications process for [patch-releases](#patch-releases)
 2. An announcement email is sent to `[email protected]` and `[email protected]` with the subject `[ANNOUNCE] cluster-api-provider-azure <version> has been released`
 
 [semver]: https://semver.org/#semantic-versioning-200

docs/book/src/topics/getting-started.md renamed to docs/book/src/getting-started.md

@@ -45,7 +45,7 @@ An Azure Service Principal is needed for deploying Azure resources. The below in
   ```
 
   5. Create an Azure Service Principal by running the following command or skip this step and use a previously created Azure Service Principal.
-  NOTE: the "owner" role is required to be able to create role assignments for [system-assigned managed identity](vm-identity.md).
+  NOTE: the "owner" role is required to be able to create role assignments for system-assigned managed identity.
 
   ```bash
   az ad sp create-for-rbac --role contributor --scopes="/subscriptions/${AZURE_SUBSCRIPTION_ID}"
@@ -84,15 +84,15 @@ For example, if your password is `foo'blah$`, you should do `export AZURE_CLIENT
 
 <h1> Warning </h1>
 
-The capability to set credentials using environment variables is now deprecated and will be removed in future releases, the recommended approach is to use `AzureClusterIdentity` as explained [here](multitenancy.md)
+The capability to set credentials using environment variables is now deprecated and will be removed in future releases, the recommended approach is to use `AzureClusterIdentity` as explained [here](./topics/multitenancy.md)
 
 </aside>
 
 
 ### Building your first cluster
 Check out the [Cluster API Quick Start](https://cluster-api.sigs.k8s.io/user/quick-start.html) to create your first Kubernetes cluster on Azure using Cluster API. Make sure to select the "Azure" tabs.
 
-If you are looking to install additional ASO CRDs, set `ADDITIONAL_ASO_CRDS` to the list of CRDs you want to install. Refer to adding additional CRDs for Azure Service Operator [here](aso.md#Using-aso-for-non-capz-resources).
+If you are looking to install additional ASO CRDs, set `ADDITIONAL_ASO_CRDS` to the list of CRDs you want to install. Refer to adding additional CRDs for Azure Service Operator [here](./topics/aso.md#Using-aso-for-non-capz-resources).
 
 <h1> Warning </h1>