Add api server lb documentation

docs/book/src/SUMMARY.md

@@ -3,6 +3,7 @@
 [Introduction](./introduction.md)
 [Roadmap](./roadmap.md)
 - [Topics](./topics/topics.md)
+    - [API Server Endpoint](./topics/api-server-endpoint.md)
     - [Cloud Provider Config](./topics/cloud-provider-config.md)
     - [Custom Images](./topics/custom-images.md)
     - [Data Disks](./topics/data-disks.md)

docs/book/src/topics/api-server-endpoint.md

@@ -0,0 +1,105 @@
+# API Server Endpoint
+
+This document describes how to configure your clusters' api server load balancer and IP.
+
+### Load Balancer Type
+
+CAPZ supports two load balancer types, `Public` and `Internal`. `Public`, which is also the default, means that your API Server Load Balancer will have a publicly accessible IP address.
+`Internal`, also known as a "private cluster", means that the API Server endpoint will only be accessible from within the cluster's virtual network (or peered VNets).
+
+A `Public` cluster will have an Azure public load balancer load balancing internet traffic to the control plane nodes.
+
+A `Private` cluster will have an Azure internal load balancer load balancing traffic inside the VNet to the control plane nodes.
+
+For more information on Azure load balancing, see [Load Balancer documentation](https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview).
+
+<aside class="note warning">
+
+<h1> Warning </h1>
+
+When creating a workload cluster with `apiServerLB` type `Internal`, the management cluster needs to be in the same VNet, or a peered VNet, as the workload cluster. Otherwise, it will not be able to access the target cluster's api server and the cluster creation will fail.  
+
+</aside>
+
+Here is an example of configuring the API Server LB type:
+
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
+kind: AzureCluster
+metadata:
+  name: my-private-cluster
+  namespace: default
+spec:
+  location: eastus
+  networkSpec:
+    apiServerLB:
+      type: Internal
+```
+
+### Private IP
+
+When using an api server load balancer of type `Internal`, the default private IP address associated with that load balancer will be `10.0.0.100`.
+If also specifying a [custom virtual network](./custom-vnet.md), make sure you provide a private IP address that is in the range of your control plane subnet and not in use.
+
+For example:
+
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
+kind: AzureCluster
+metadata:
+  name: my-private-cluster
+  namespace: default
+spec:
+  location: eastus
+  networkSpec:
+    vnet:
+      name: my-vnet
+      cidrBlocks: 
+        - 172.16.0.0/16
+    subnets:
+      - name: my-subnet-cp
+        role: control-plane
+        cidrBlocks: 
+          - 172.16.0.0/24
+      - name: my-subnet-node
+        role: node
+        cidrBlocks: 
+          - 172.16.2.0/24
+    apiServerLB:
+      type: Internal
+      frontendIPs:
+        - name: lb-private-ip-frontend
+          privateIP: 172.16.0.100
+```
+
+### Public IP
+
+When using an api server load balancer of type `Public`, a dynamic public IP address will be created, along with a unique FQDN.
+
+You can also choose to provide your own public api server IP. To do so, specify the existing public IP as follows:
+
+````yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
+kind: AzureCluster
+metadata:
+  name: my-cluster
+  namespace: default
+spec:
+  location: eastus
+  networkSpec:
+    apiServerLB:
+      type: Public
+      frontendIPs:
+        - name: lb-public-ip-frontend
+          publicIP:
+            name: my-public-ip
+            dns: my-cluster-986b4408.eastus.cloudapp.azure.com
+````
+
+Note that `dns` is the FQDN associated to your public IP address (look for "DNS name" in the Azure Portal).
+
+When you BYO api server IP, CAPZ does not manage its lifecycle, ie. the IP will not get deleted as part of cluster deletion.
+
+### Load Balancer SKU
+
+At this time, CAPZ only supports Azure Standard Load Balancers. See [SKU comparison](https://docs.microsoft.com/en-us/azure/load-balancer/skus#skus) for more information on Azure Load Balancers SKUs.

docs/book/src/topics/custom-vnet.md

@@ -5,7 +5,7 @@
 To deploy a cluster using a pre-existing vnet, modify the `AzureCluster` spec to include the name and resource group of the existing vnet as follows, as well as the control plane and node subnets as follows:
 
 ```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
 kind: AzureCluster
 metadata:
   name: cluster-byo-vnet
@@ -24,30 +24,7 @@ spec:
   resourceGroup: cluster-byo-vnet
   ```
 
-When providing a vnet, it is required to also provide the two subnets that should be used for control planes and nodes. The internal load balancer private IP can be optionally provided in the control plane subnet spec as follows:
-
-```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
-kind: AzureCluster
-metadata:
-  name: cluster-byo-vnet
-  namespace: default
-spec:
-  location: southcentralus
-  networkSpec:
-    vnet:
-      resourceGroup: custom-vnet
-      name: my-vnet
-    subnets:
-      - name: control-plane-subnet
-        role: control-plane
-        internalLBIPAddress: "10.0.1.6"
-      - name: node-subnet
-        role: node
-  resourceGroup: cluster-byo-vnet
-```
-
-If provided, the private IP should be a valid IP within the control plane subnet address space. If no IP is provided, the internal load balancer reconciler will select a free IP within the subnet range at creation.
+When providing a vnet, it is required to also provide the two subnets that should be used for control planes and nodes.
 
 If providing an existing vnet and subnets with existing network security groups, make sure that the control plane security group allows inbound to port 6443, as port 6443 is used by kubeadm to bootstrap the control planes. Alternatively, you can [provide a custom control plane endpoint](https://github.com/kubernetes-sigs/cluster-api-bootstrap-provider-kubeadm#kubeadmconfig-objects) in the `KubeadmConfig` spec.
 
@@ -58,7 +35,7 @@ The pre-existing vnet can be in the same resource group or a different resource
 It is also possible to customize the vnet to be created without providing an already existing vnet. To do so, simply modify the `AzureCluster` `NetworkSpec` as desired. Here is an illustrative example of a cluster with a customized vnet address space (CIDR) and customized subnets:
 
 ```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
 kind: AzureCluster
 metadata:
   name: cluster-example
@@ -95,7 +72,7 @@ It is the responsibility of the user to supply those rules themselves if using c
 Here is an illustrative example of customizing ingresses that builds on the one above by adding an ingress rule to the control plane nodes:
 
 ```yaml
-apiVersion: infrastructure.cluster.x-k8s.io/v1alpha2
+apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
 kind: AzureCluster
 metadata:
   name: cluster-example