docs: add how-to setup

docs/concepts/DNSBasedGlobalLoadBalancing/README.md

@@ -38,6 +38,12 @@ spec:
 
 To export a multi-cluster service, `TrafficManagerProfile` and `TrafficManagerBackend` should be created within namespace that the service resides in - that is, they reference the `Service` with the same namespace name as the traffic manager resources.
 
+The following diagram illustrates the relationship between the Azure Traffic Manager resources and Kubernetes resources:
+![](overview.png)
+
+> Note: When you delete the `TrafficManagerProfile`, the corresponding Azure Traffic Manager resources (including any endpoints)
+> will be deleted as well and the accepted condition of `TrafficManagerBackend` which are referring to the `TrafficManagerProfile` will become false. 
+
 ## User stories
 **Single Service Deployed to Multiple Clusters**
 
@@ -105,14 +111,15 @@ status:
 For networking member agents operating within the member cluster, the necessary permissions should be in place to access the public IP address.
 
 To support the traffic manager feature, networking hub agent needs to have the following permissions:
-
-```
-"Microsoft.Network/publicIPAddresses/read",
-"Microsoft.Network/trafficManagerProfiles/read",
-"Microsoft.Network/trafficManagerProfiles/write",
-"Microsoft.Network/trafficManagerProfiles/delete",
-"Microsoft.Network/trafficManagerProfiles/azureEndpoints/read",
-"Microsoft.Network/trafficManagerProfiles/azureEndpoints/write",
-"Microsoft.Network/trafficManagerProfiles/azureEndpoints/delete"
-```
+* `Microsoft.Network/publicIPAddresses/read` on the public IP address resource created in the member clusters.
+* Azure Traffic Manager permissions on the resource group where the traffic manager profile is created.
+
+    ```
+    "Microsoft.Network/trafficManagerProfiles/read",
+    "Microsoft.Network/trafficManagerProfiles/write",
+    "Microsoft.Network/trafficManagerProfiles/delete",
+    "Microsoft.Network/trafficManagerProfiles/azureEndpoints/read",
+    "Microsoft.Network/trafficManagerProfiles/azureEndpoints/write",
+    "Microsoft.Network/trafficManagerProfiles/azureEndpoints/delete"
+    ```
 

docs/howtos/traffic-manager-permissions-setup.md

@@ -0,0 +1,53 @@
+# How-to Guide: Traffic Manager Permissions setup
+
+This guide provides an overview of how to set up permissions for Azure Traffic Manager in order to use the DNS based global
+load balancing feature.
+
+## Get the hub and member agents identity
+
+Figure out the identity used by hub-net-controller-manager and member-net-controller-manager.
+There are various ways to set up the fleet networking, and the recommended way is to use [workload-identity](https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster).
+
+```bash
+export HUB_IDENTITY_PRINCIPAL_ID=$(az identity show \
+    --name "${HUB_USER_ASSIGNED_IDENTITY_NAME}" \
+    --resource-group "${RESOURCE_GROUP}" \
+    --query principalId \
+    --output tsv)
+export MEMBER_IDENTITY_PRINCIPAL_ID=$(az identity show \
+    --name "${MEMBER_USER_ASSIGNED_IDENTITY_NAME}" \
+    --resource-group "${RESOURCE_GROUP}" \
+    --query principalId \
+    --output tsv)
+```
+
+## Create the role assignment for the hub agent
+
+### Create the role assignment for the hub agent to manage the Azure Traffic Manager
+Assign role “[Traffic Manager Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/networking#traffic-manager-contributor)” to hub cluster identity at the Azure Traffic Manager resource group scope
+```bash
+az role assignment create --assignee "${HUB_IDENTITY_PRINCIPAL_ID}" --role "a4b10055-b0c7-44c2-b00f-c7b5b3550cf7" --scope "/subscriptions/mySubscriptions/resourceGroups/MyAzureTrafficManagerResourceGroup"
+```
+
+### Create the role assignment for the hub agent to read the public IP address used by the member cluster
+
+Grant Public IP address read permission to the hub cluster identity so that the hub networking agent can read the public IP address of the members (either BYO or MC_rg). 
+
+> Note: You can create your own customized role to restrict access or restrict the scope based on your security requirements.
+
+For example, the following command grants the “[Reader](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/general#reader)” to the hub cluster identity at the resource group of the public ip scope for testing purpose.
+
+```bash
+az role assignment create --assignee "${HUB_IDENTITY_PRINCIPAL_ID}" --role "acdd72a7-3385-48ef-bd42-f606fba81ae7" --scope "/subscriptions/mySubscriptions/resourceGroups/MyPIPResourceGroup"
+```
+
+## Create the role assignment for the member agent
+Grant Public IP address read permission to the member cluster identity so that the member networking agent can read the public IP address of the members (either BYO or MC_rg).
+
+> Note: You can create your own customized role to restrict access or restrict the scope based on your security requirements.
+
+For example, the following command grants the “[Reader](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/general#reader)” to the member cluster identity at the resource group of the public ip scope for testing purpose.
+
+```bash
+az role assignment create --assignee "${MEMBER_IDENTITY_PRINCIPAL_ID}" --role "acdd72a7-3385-48ef-bd42-f606fba81ae7" --scope "/subscriptions/mySubscriptions/resourceGroups/MyPIPResourceGroup"
+```

docs/tutorials/ApplicationMigration/ApplicationMigration.md

@@ -21,6 +21,11 @@ The following resources are currently deployed in the hub cluster and use cluste
 
 ```yaml
 apiVersion: v1
+kind: Namespace
+metadata:
+  name: test-app
+---
+apiVersion: v1
 kind: Service
 metadata:
   name: nginx-service
@@ -68,6 +73,8 @@ spec:
             value:
               {"service.beta.kubernetes.io/azure-dns-label-name":"fleet-${MEMBER-CLUSTER-NAME}"}
 ```
+> Note: "${MEMBER-CLUSTER-NAME}" is a [reserved variable](https://github.com/Azure/fleet/blob/main/docs/concepts/Override/README.md#reserved-variables-in-the-json-patch-override-value) in the override, and it will be replaced with the name of the member cluster.
+
 > Note: Please update the dns label name to match your specific requirements, and the "fleet-${MEMBER-CLUSTER-NAME}" may be not available.
 
 Summary:

docs/tutorials/ApplicationMigration/testfiles/nginx-service.yaml

@@ -1,4 +1,9 @@
 apiVersion: v1
+kind: Namespace
+metadata:
+  name: test-app
+---
+apiVersion: v1
 kind: Service
 metadata:
   name: nginx-service

docs/tutorials/BuildMultiClusterApplication/BuildMultiClusterApplication.md

@@ -25,6 +25,11 @@ The following resources are currently deployed in the hub cluster and use cluste
 
 ```yaml
 apiVersion: v1
+kind: Namespace
+metadata:
+  name: multi-cluster-app
+---
+apiVersion: v1
 kind: Service
 metadata:
   name: nginx-service
@@ -72,6 +77,11 @@ spec:
             value:
               {"service.beta.kubernetes.io/azure-dns-label-name":"multi-cluster-app-${MEMBER-CLUSTER-NAME}"}
 ```
+> Note: "${MEMBER-CLUSTER-NAME}" is a [reserved variable](https://github.com/Azure/fleet/blob/main/docs/concepts/Override/README.md#reserved-variables-in-the-json-patch-override-value) in the override, and it will be replaced with the name of the member cluster.
+
+> Note: Please update the dns label name to match your specific requirements, and the "multi-cluster-app-${MEMBER-CLUSTER-NAME}" may be not available.
+
+
 Summary:
 - This defines a Kubernetes Service named `nginx-service` in the `test-app` namespace.
 - The service is of type LoadBalancer with a public ip address and a DNS name assigned.
@@ -99,7 +109,7 @@ data:
     kind: Deployment
     metadata:
       name: nginx-deployment
-      namespace: test-app
+      namespace:  multi-cluster-app
     spec:
       replicas: 2
       selector:

docs/tutorials/BuildMultiClusterApplication/testfiles/nginx-service.yaml

@@ -1,4 +1,9 @@
 apiVersion: v1
+kind: Namespace
+metadata:
+  name: multi-cluster-app
+---
+apiVersion: v1
 kind: Service
 metadata:
   name: nginx-service