suggested improvements

Author: jim-minter

articles/kubernetes-fleet/architectural-overview.md

@@ -11,7 +11,7 @@ ms.topic: conceptual
 
 # Architectural overview of Azure Kubernetes Fleet Manager
 
-Azure Kubernetes Fleet Manager (Fleet) is meant to solve at-scale and multi-cluster problems of Azure Kubernetes Service (AKS) clusters. This document provides an architectural overview of topological relationship between a Fleet resource and AKS clusters. This document also provides a conceptual overview of scenarios available on top of Fleet resource like Kubernetes resource propagation and multi-cluster Layer-4 load balancing.
+Azure Kubernetes Fleet Manager (Fleet) solves at-scale and multi-cluster problems of Azure Kubernetes Service (AKS) clusters. This document provides an architectural overview of the relationship between a Fleet resource and AKS clusters. This document also provides a conceptual overview of scenarios available on top of Fleet resource, including update orchestration, Kubernetes resource propagation (preview) and multi-cluster Layer-4 load balancing (preview).
 
 [!INCLUDE [preview features note](./includes/preview/preview-callout.md)]
 
@@ -29,9 +29,26 @@ You can join up to 100 AKS clusters as member clusters to the same fleet resourc
 
 If you want to use fleet only for the update orchestration scenario, you can create a fleet resource without the hub cluster. The fleet resource is treated just as a grouping resource, and does not have its own data plane. This is the default behavior when creating a new fleet resource.
 
-If you want to use fleet for Kubernetes object propagation and multi-cluster load balancing in addition to update orchestration, then you need to create the fleet resource with the hub cluster enabled. If you have a hub cluster data plane for the fleet, you can use it to check the member clusters joined.
+If you want to use fleet for Kubernetes object propagation (preview) and multi-cluster load balancing (preview) in addition to update orchestration, then you need to create the fleet resource with the hub cluster enabled.
 
-Once a cluster is joined to a fleet resource, a MemberCluster custom resource is created on the fleet. Note that once a fleet resource has been created, it is not possible to change the hub mode (with/without) for the fleet resource.
+Note that once a fleet resource has been created, it is not possible to change the hub mode for the fleet resource.
+
+## Update orchestration across multiple clusters
+
+Platform admins managing Kubernetes fleets with large number of clusters often have problems with staging their updates in a safe and predictable way across multiple clusters. To address this pain point, Kubernetes Fleet Manager (Fleet) allows you to orchestrate updates across multiple clusters using update runs, stages, groups, and strategies.
+
+:::image type="content" source="./media/conceptual-update-orchestration-inline.png" alt-text="A diagram showing an upgrade run containing two update stages, each containing two update groups with two member clusters." lightbox="./media/conceptual-update-orchestration.png":::
+
+* **Update run**: An update run represents an update being applied to a collection of AKS clusters. An update run updates clusters in a predictable fashion by defining update stages and update groups. An update run can be stopped and started.
+* **Update stage**: Update runs are divided into stages which are applied sequentially. For example, a first update stage might update test environment member clusters, and a second update stage would then subsequently update production environment member clusters. A wait time can be specified to delay between the application of subsequent update stages.
+* **Update group**: Each update stage contains one or more update groups, which are used to select the member clusters to be updated. Update groups are also used to order the application of updates to member clusters. Within an update stage, updates are applied to all the different update groups in parallel; within an update group, member clusters update sequentially. Each member cluster of the fleet can only be a part of one update group.
+* **Update strategy**: Update strategies allows you to store templates for your update runs instead of creating them individually for each update run.
+
+Currently, the supported update operations on the cluster are upgrades. Within upgrades, you can either upgrade both the Kubernetes control plane version and the node image, or you can choose to upgrade only the node image. The latest available node image for a given cluster may vary based on its region (check [release tracker](../aks/release-tracker.md) for more information). Node image upgrades currently support upgrading each cluster to the latest node image available in its region, or applying a consistent node image across all clusters of the update run, regardless of the cluster regions. In this case the update run picks the **latest common** image across all these regions to achieve consistency.
+
+## Member cluster representation on the hub
+
+ Once each cluster is joined to a fleet resource, a corresponding MemberCluster custom resource is created on the fleet hub.
 
 The member clusters can be viewed by running the following command:
 
@@ -51,19 +68,6 @@ The following labels are added automatically to all member clusters, which can t
 * `fleet.azure.com/resource-group`
 * `fleet.azure.com/subscription-id`
 
-## Update orchestration across multiple clusters
-
-Platform admins managing Kubernetes fleets with large number of clusters often have problems with staging their updates in a safe and predictable way across multiple clusters. To address this pain point, Fleet allows orchestrating updates across multiple clusters using update runs, stages, and groups.
-
-:::image type="content" source="./media/conceptual-update-orchestration-inline.png" alt-text="A diagram showing an upgrade run containing two update stages, each containing two update groups with two member clusters." lightbox="./media/conceptual-update-orchestration.png":::
-
-* **Update group**: A group of AKS clusters for which updates are done sequentially one after the other. Each member cluster of the fleet can only be a part of one update group.
-* **Update stage**: Update stages allow pooling together update groups for which the updates need to be run in parallel. It can be used to define wait time between two different collections of update groups.
-* **Update run**: An update being applied to a collection of AKS clusters in a sequential or stage-by-stage manner. An update run can be stopped and started. An update run can either upgrade clusters one-by-one or in a stage-by-stage fashion using update stages and update groups.
-* **Update strategy**: Update strategy allows you to store templates for your update runs instead of creating them individually for each update run.
-
-Currently, the only supported update operations on the cluster are upgrades. Within upgrades, you can either upgrade both the Kubernetes control plane version and the node image or you can choose to upgrade only the node image. Node image upgrades currently only allow upgrading to either the latest available node image for each cluster, or applying the same consistent node image across all clusters of the update run. As it's possible for an update run to have AKS clusters across multiple regions where the latest available node images can be different (check [release tracker](../aks/release-tracker.md) for more information). The update run picks the **latest common** image across all these regions to achieve consistency.
-
 ## Kubernetes resource propagation
 
 Fleet provides `ClusterResourcePlacement` as a mechanism to control how cluster-scoped Kubernetes resources are propagated to member clusters. For more details, see the [resource propagation documentation](resource-propagation.md).

articles/kubernetes-fleet/faq.md

@@ -19,15 +19,15 @@ This article covers the frequently asked questions for Azure Kubernetes Fleet Ma
 
 Azure Kubernetes Service (AKS) simplifies deploying a managed Kubernetes cluster in Azure by offloading the operational overhead to Azure. As a hosted Kubernetes service, Azure handles critical tasks, like health monitoring and maintenance. Since the Kubernetes control plane is managed by Azure, you only manage and maintain the agent nodes. You run your actual workloads on the AKS clusters.
 
-Azure Kubernetes Fleet Manager (Fleet) will help you address at-scale and multi-cluster scenarios for Azure Kubernetes Service clusters. Azure Kubernetes Fleet Manager only provides a group representation for your AKS clusters and helps users with orchestrating Kubernetes resource propagation and multi-cluster load balancing. User workloads can't be run on the fleet cluster itself. 
+Azure Kubernetes Fleet Manager (Fleet) will help you address at-scale and multi-cluster scenarios for Azure Kubernetes Service clusters. Azure Kubernetes Fleet Manager provides a group representation for your AKS clusters and helps users with orchestrating cluster updates, Kubernetes resource propagation and multi-cluster load balancing. User workloads can't be run on the fleet cluster itself. 
 
 ## Creation of AKS clusters from fleet resource
 
-The current preview of Azure Kubernetes Fleet Manager resource supports joining only existing AKS clusters as member. Creation and lifecycle management of new AKS clusters from fleet cluster is in the [roadmap](https://aka.ms/fleet/roadmap).
+Today, Azure Kubernetes Fleet Manager supports joining existing AKS clusters as fleet members. Creation and lifecycle management of new AKS clusters from fleet cluster is in the [roadmap](https://aka.ms/fleet/roadmap).
 
 ## Number of clusters
 
-During preview, you can join up to 20 AKS clusters as member clusters to the same fleet resource.
+You can join up to 100 AKS clusters as member clusters to the same fleet resource.
 
 ## AKS clusters that can be joined as members
 
@@ -39,7 +39,7 @@ Fleet supports joining the following types of AKS clusters as member clusters:
 
 ## Relationship to Azure-Arc enabled Kubernetes
 
-The current preview of Azure Kubernetes Fleet Manager resource supports joining only AKS clusters as member clusters. Support for joining member clusters to the fleet resource is in the [roadmap](https://aka.ms/fleet/roadmap).
+Today, Azure Kubernetes Fleet Manager supports joining AKS clusters as member clusters. Support for joining member clusters to the fleet resource is in the [roadmap](https://aka.ms/fleet/roadmap).
 
 ## Regional or global
 
@@ -62,4 +62,4 @@ The roadmap for Azure Kubernetes Fleet Manager resource is available [here](http
 
 ## Next steps
 
-* Create an [Azure Kuberntes Fleet Manager resource and join member clusters](./quickstart-create-fleet-and-members.md)
+* Create an [Azure Kubernetes Fleet Manager resource and join member clusters](./quickstart-create-fleet-and-members.md)

articles/kubernetes-fleet/overview.md

@@ -15,19 +15,17 @@ keywords: "Kubernetes, Azure, multi-cluster, multi, containers"
 
 # What is Azure Kubernetes Fleet Manager?
 
-Azure Kubernetes Fleet Manager (Fleet) enables multi-cluster and at-scale scenarios for Azure Kubernetes Service (AKS) clusters. A Fleet resource creates a cluster that can be used to manage other member clusters.
-
-Fleet supports the following scenarios:
+Azure Kubernetes Fleet Manager (Fleet) enables at-scale management of multiple Azure Kubernetes Service (AKS) clusters. Fleet supports the following scenarios:
 
 * Create a Fleet resource and group AKS clusters as member clusters.
 
-* Create Kubernetes resource objects on the Fleet resource's cluster and control their propagation to all or a subset of all member clusters.
+* Orchestrate Kubernetes version and node image upgrades across multiple clusters by using update runs, stages, and groups.
 
-* Load balance incoming L4 traffic across service endpoints on multiple clusters
+* Create Kubernetes resource objects on the Fleet resource's hub cluster and control their propagation to all or a subset of all member clusters (preview).
 
-* Export a service from one member cluster to the Fleet resource. Once successfully exported, the service and its endpoints are synced to the hub, which other member clusters (or any Fleet resource-scoped load balancer) can consume.
+* Export and import services between member clusters. Once successfully exported, a service and its endpoints are synced to the hub, and can be consumed by other member clusters (preview).
 
-* Orchestrate Kubernetes version and node image upgrades across multiple clusters by using update runs, stages, and groups.
+* Load balance incoming L4 traffic across service endpoints on multiple clusters (preview).
 
 ## Next steps
 

articles/kubernetes-fleet/quickstart-create-fleet-and-members.md

@@ -90,14 +90,14 @@ The following output example resembles successful creation of the resource group
 
 ## Create a fleet resource
 
-You can create a fleet resource to later group your AKS clusters as member clusters. This resource enables multi-cluster scenarios such as update orchestration across clusters, Kubernetes object propagation to member clusters, and north-south load balancing across endpoints deployed on multiple member clusters.
+You can create a fleet resource to later group your AKS clusters as member clusters. By default this resource enables member cluster grouping and update orchestration. If the fleet hub is enabled, additional preview features are enabled such as Kubernetes object propagation to member clusters, and L4 service load balancing across multiple member clusters.
 
 > [!IMPORTANT]
-> As of now, once a fleet resource has been created, it is not possible to change the hub mode (with/without) for the fleet resource.
+> As of now, once a fleet resource has been created, it is not possible to change the hub mode for the fleet resource.
 
 ### Update orchestration only (default)
 
-If you want to use Fleet only for update orchestration scenario, you can create a fleet resource without the hub cluster using the [az fleet create](/cli/azure/fleet#az-fleet-create) command. This is the default experience when creating a new fleet resource.
+If you want to use Fleet only for update orchestration, you can create a fleet resource without the hub cluster using the [az fleet create](/cli/azure/fleet#az-fleet-create) command. This is the default experience when creating a new fleet resource.
 
 ```azurecli-interactive
 az fleet create --resource-group ${GROUP} --name ${FLEET} --location eastus
@@ -192,36 +192,36 @@ Fleet currently supports joining existing AKS clusters as member clusters.
     **Create AKS clusters**
 
     ```azurecli-interactive
-    export MEMBER_CLUSTER_1=aks-member-1
+    export MEMBER_NAME_1=aks-member-1
 
     az aks create \
         --resource-group ${GROUP} \
         --location eastus \
-        --name ${MEMBER_CLUSTER_1} \
+        --name ${MEMBER_NAME_1} \
         --node-count 1 \
         --network-plugin azure \
         --vnet-subnet-id "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.Network/virtualNetworks/${FIRST_VNET}/subnets/${MEMBER_1_SUBNET}"
     ```
 
     ```azurecli-interactive
-    export MEMBER_CLUSTER_2=aks-member-2
+    export MEMBER_NAME_2=aks-member-2
 
     az aks create \
         --resource-group ${GROUP} \
         --location eastus \
-        --name ${MEMBER_CLUSTER_2} \
+        --name ${MEMBER_NAME_2} \
         --node-count 1 \
         --network-plugin azure \
         --vnet-subnet-id "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.Network/virtualNetworks/${FIRST_VNET}/subnets/${MEMBER_2_SUBNET}"
     ```
 
     ```azurecli-interactive
-    export MEMBER_CLUSTER_3=aks-member-3
+    export MEMBER_NAME_3=aks-member-3
 
     az aks create \
         --resource-group ${GROUP} \
         --location westcentralus \
-        --name ${MEMBER_CLUSTER_3} \
+        --name ${MEMBER_NAME_3} \
         --node-count 1 \
         --network-plugin azure \
         --vnet-subnet-id "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.Network/virtualNetworks/${SECOND_VNET}/subnets/${MEMBER_3_SUBNET}"
@@ -232,14 +232,14 @@ Fleet currently supports joining existing AKS clusters as member clusters.
 1. Set the following environment variables for members:
 
     ```azurecli-interactive
-    export MEMBER_CLUSTER_ID_1=/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.ContainerService/managedClusters/${MEMBER_CLUSTER_1}
     export MEMBER_NAME_1=aks-member-1
+    export MEMBER_CLUSTER_ID_1=/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.ContainerService/managedClusters/${MEMBER_NAME_1}
 
-    export MEMBER_CLUSTER_ID_2=/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.ContainerService/managedClusters/${MEMBER_CLUSTER_2}
     export MEMBER_NAME_2=aks-member-2
+    export MEMBER_CLUSTER_ID_2=/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.ContainerService/managedClusters/${MEMBER_NAME_2}
 
-    export MEMBER_CLUSTER_ID_3=/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.ContainerService/managedClusters/${MEMBER_CLUSTER_3}
     export MEMBER_NAME_3=aks-member-3
+    export MEMBER_CLUSTER_ID_3=/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${GROUP}/providers/Microsoft.ContainerService/managedClusters/${MEMBER_NAME_3}
     ```
 
 1. Join these clusters to the Fleet resource using the following commands:
@@ -428,4 +428,5 @@ To access the Fleet cluster's Kubernetes API, run the following commands:
 
 ## Next steps
 
-* Learn how to use [Kubernetes resource objects propagation](./resource-propagation.md)
+* Learn how to use [Update orchestration](./update-orchestration.md)
+* Learn how to use [Kubernetes resource object propagation](./resource-propagation.md)

articles/kubernetes-fleet/toc.yml

@@ -18,7 +18,7 @@
   items:
   - name: Orchestrate updates across multiple member clusters
     href: update-orchestration.md
-  - name: Kubernetes resource objects propagation
+  - name: Kubernetes resource object propagation
     href: resource-propagation.md
   - name: Multi-cluster Layer 4 Load Balancing
     href: l4-load-balancing.md