Updated LiveDocs for VGW section

docs/guide/troubleshooting.md

@@ -43,16 +43,29 @@ kubectl port-forward -n "${APPLICATION_NAMESPACE}" \
 
 Then navigate to `localhost:9901/` for the index or `localhost:9901/config_dump` for the envoy config.
 
+## VirtualGateway - Common Issues
+```
+failed to find matching virtualGateway for gatewayRoute:<gatewayRoute.Name>, expecting 1 but found 0
+```
+You will see above error if any of the GatewayRoutes specified in your spec cannot be associated with VirtualGateway.This can happen if there is no matching GatewayRoute based on the namespaceSelector and/or gatewayRouteSelector specified by the VirtualGateway. 
+For more details refer [LiveDocs Virtual Gateway section](../reference/vgw.md)
+
+```
+"Error from server (found multiple matching virtualGateways for gatewayRoute:<gatewayRoute.Name>, expecting 1 but found N"
+```
+You will see an error similar to above if there are multiple VirtualGateways for a single gatewayRoute based on the specified namespaceSelector and gatewayRouteSelector logic. 
+For more details refer [LiveDocs Virtual Gateway section](../reference/vgw.md)
+
 ## mTLS - Common Issues
 
 ### Envoy fails to boot up when SDS based mTLS is enabled
 
 When SDS based mTLS is enabled at the controller level via `enable-sds` flag, controller expects to find SDS Provider’s UDS at path specified by `sds-uds-path`. It is set to a default value of `/run/spire/sockets/agent.sock` which is the default SPIRE Agent’s UDS path. Make sure that SDS Provider on the local node is up and running and UDS is active. Currently, SPIRE is the only supported SDS provider. Please check if SPIRE Agent is up and running on the same node as the problematic Envoy.
- 
+
 You can use the below command to figure out the exact reason of the envoy bootup issue. If the error is due to not being able to mount SDS provider's UDS socket then you would need to address that.
 
 ```bash
-kubectl describe pod <pod-name> -n <namespace-name> 
+kubectl describe pod <pod-name> -n <namespace-name>
 ```
 
 ### Pod is up and running but Envoy doesn’t have any certs in SDS mode.
@@ -93,4 +106,4 @@ HTTP and TCP health checks from the kubelet will not work as is, if mutual TLS i
 
 ### SDS cluster is present in Envoy's config even though corresponding VirtualNode doesn't have mTLS SDS config
 
-Set `appmesh.k8s.aws/sds:disabled` for the deployments behind VirtualNodes without SDS config.
+Set `appmesh.k8s.aws/sds:disabled` for the deployments behind VirtualNodes without SDS config.

docs/reference/vgw.md

@@ -0,0 +1,73 @@
+### GatewayRoute to VirtualGateway Association while via CRD (Yaml Spec)
+A VirtualGateway can select GatewayRoute using 2 types of selectors  
+#### namespaceSelector ####  
+VirtualGateway must specify namespaceSelector to associate GatewayRoutes belonging to a particular namespace.
+An empty namespaceSelector would target GatewayRoutes in all namespaces. While nil or not specifying any namespace selector would not select any GatewayRoutes.
+
+#### gatewayRouteSelector ####  
+VirtualGateway can additionally specify gatewayRouteSelector to select subset of GatewayRoutes in a given namespace. 
+An empty or not specifying this field (nil) will select all GatewayRoutes in a given namespace. If specified then it will select only those GatewayRoutes which have the matching labels. 
+
+Here is a sample spec with 1 VirtualGateway and 2 GatewayRoutes. Here VirtualGateway specified a gatewayRouteSelector, based on which only 1 of the GatewayRoute gets selected.
+
+```
+apiVersion: appmesh.k8s.aws/v1beta2
+kind: VirtualGateway
+metadata:
+  name: ingress-gw
+  namespace: ${APP_NAMESPACE}
+spec:
+  namespaceSelector:
+    matchLabels:
+      gateway: ingress-gw
+  gatewayRouteSelector:
+    matchLabels:
+      gateway: ingress-gw
+  podSelector:
+    matchLabels:
+      app: ingress-gw
+  listeners:
+    - portMapping:
+        port: 8088
+        protocol: http
+---
+apiVersion: appmesh.k8s.aws/v1beta2
+kind: GatewayRoute
+metadata:
+  name: gateway-route-headers
+  namespace: ${APP_NAMESPACE}
+spec:
+  httpRoute:
+    match:
+      prefix: "/headers"
+    action:
+      target:
+        virtualService:
+          virtualServiceRef:
+            name: color-headers
+---
+apiVersion: appmesh.k8s.aws/v1beta2
+kind: GatewayRoute
+metadata:
+  name: gateway-route-paths
+  namespace: ${APP_NAMESPACE}
+  labels:
+    gateway: ingress-gw
+spec:
+  httpRoute:
+    match:
+      prefix: "/paths"
+    action:
+      target:
+        virtualService:
+          virtualServiceRef:
+            name: color-paths
+----
+```
+
+Since the GatewayRoute: gateway-route-headers doesn't have any matching VirtualGateway, customers will see following error message
+```
+failed to find matching virtualGateway for gatewayRoute: gateway-route-headers, expecting 1 but found 0
+```
+
+The above error message is to only inform the user that the GatewayRoute in the error message has not been associated with any VirtualGateway. So the user should either add matching gatewayRouteSelector to the unmatched gatewayRoute or completely remove the gatewayRouteSelector so that the VirtualGateway ignores this field and uses only the namespaceSelector. 

mkdocs.yml

@@ -17,6 +17,7 @@ nav:
       - APISpec: reference/api_spec.md
       - APIDesign: reference/api_design.md
       - SidecarInjection: reference/injector.md
+      - VirtualGateway CRD: reference/vgw.md
 plugins:
   - search
 theme: