Multi cluster doc improve

docs/guides/multi-cluster.md

@@ -0,0 +1,48 @@
+# Recommended Multi-Cluster Architecture
+
+Here is a recommended multi-cluster architecture if you'd like to setup kubernetes service-to-service communications across multiple clusters.
+
+Suppose your organization would like to have one large infrastructure that have many clusters in one AWS account. It's recommended your infrastructure includes the following components:
+- One manually created VPC Lattice service network, (it could create by either AWS Console, CLI, CloudFormation, Terraform or any other tools)
+- Create `VpcServiceNetworkAssociations` between VPC Lattice service network and each config cluster's VPC and workload clusters' VPCs
+- Multiple workload cluster(s), that are used to run application workload(s). Workload cluster(s) should only have following workloads related kubernetes objects:
+  - Application workload(s) (`Pod(s)`, `Deployment(s)` etc.)
+  - `Service(s)` for application workload(s)
+  - `ServiceExport(s)`, that export kubernetes application Service(s) to the "config cluster"
+- One extra dedicated "config cluster", which is act as a "service network control plane" and it should include following kubernetes objects:
+  - One `Gateway` that has __same name__ as the manually created VPC Lattice service network name
+  - `ServiceImport(s)`, that reference to kubernetes application services that export from workload cluster(s)
+  - `HTTPRoute(s)`,`GRPCRoute(s)`, that have rules backendRefs to `ServiceImport(s)` that referring kubernetes application service(s) in workload cluster(s)
+
+![config cluster and multiple workload clusters](../images/multi-cluster.png)
+
+
+Above architecture is recommended for following reasons:
+- Putting all Route(s) and only one Gateway in the config cluster is easier to manage and have less chance to have conflict.
+- You are easier to have seperated roles in your organization. The infra operator team only manage the resource in the config cluster and VPC Lattice resource, and the application developer team only manage the resource in the workload cluster(s).
+
+
+
+Following steps show you how to set up this recommended multi-cluster architecture with 1 config cluster and 2 workload clusters.
+1. Create 3 k8s clusters: `config cluster`, `workload cluster-1`, `workload cluster-2`. Install AWS gateway api controller in each cluster, you could follow this instruction [deploy.md](deploy.md)
+1. Create a VPC Lattice `ServiceNetwork` with name `my-gateway`
+1. Create `VPCServiceNetworkAssociation(s)` between previous step created service network and each config cluster's VPC and workload clusters' VPCs
+1. Setup following resource in the workload cluster1:
+    ```
+    kubectl apply -f examples/service-1.yaml
+    kubectl apply -f examples/service-1-export.yaml
+    ```
+1. Setup following resource in the workload cluster2:
+    ```
+    kubectl apply -f examples/service-2.yaml
+    kubectl apply -f examples/service-2-export.yaml
+    ```
+1. Setup following resource in the config cluster:
+    ```
+    kubectl apply -f examples/my-gateway.yaml
+    kubectl apply -f examples/my-httproute.yaml
+    kubectl apply -f examples/service-1-import.yaml
+    kubectl apply -f examples/service-2-import.yaml
+    ```
+1. At this point, the connectivity setup finished, pods in workload cluster1 are able to communicate with `service-2` in workload cluster2 (and vice versa) via the `my-httproute` dns name.
+1. Furthermore, you could have more workloads clusters to join the `my-gateway` service network by creating the `ServiceNewtorkAssociation(s)`, they will all be able to communicate with `service-1` and `service-2` via the `my-httproute` dns name and path matching.

examples/my-gateway.yaml

@@ -0,0 +1,10 @@
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: Gateway
+metadata:
+  name: my-gateway
+spec:
+  gatewayClassName: amazon-vpc-lattice
+  listeners:
+  - name: http
+    protocol: HTTP
+    port: 80

examples/my-httproute.yaml

@@ -0,0 +1,23 @@
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: HTTPRoute
+metadata:
+  name: my-httproute
+spec:
+  parentRefs:
+  - name: my-hotel
+    sectionName: http
+  rules:
+  - backendRefs:
+    - name: service-1
+      kind: ServiceImport
+    matches:
+    - path:
+        type: PathPrefix
+        value: /service-1
+  - backendRefs:
+    - name: service-2
+      kind: ServiceImport
+    matches:
+    - path:
+        type: PathPrefix
+        value: /service-2

examples/service-1-export.yaml

@@ -0,0 +1,6 @@
+apiVersion: application-networking.k8s.aws/v1alpha1
+kind: ServiceExport
+metadata:
+  name: service-1
+  annotations:
+    application-networking.k8s.aws/federation: "amazon-vpc-lattice"

examples/service-1-import.yaml

@@ -0,0 +1,9 @@
+apiVersion: application-networking.k8s.aws/v1alpha1
+kind: ServiceImport
+metadata:
+  name: service-1
+spec:
+  type: ClusterSetIP
+  ports:
+  - port: 80
+    protocol: TCP

examples/service-1.yaml

@@ -0,0 +1,36 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: service-1
+  labels:
+    app: service-1
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: service-1
+  template:
+    metadata:
+      labels:
+        app: service-1
+    spec:
+      containers:
+      - name: service-1
+        image: public.ecr.aws/x2j8p8w7/http-server:latest
+        env:
+        - name: PodName
+          value: "service-1 handler pod"
+
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: service-1
+spec:
+  selector:
+    app: service-1
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 8090

examples/service-2-export.yaml

@@ -0,0 +1,6 @@
+apiVersion: application-networking.k8s.aws/v1alpha1
+kind: ServiceExport
+metadata:
+  name: service-2
+  annotations:
+    application-networking.k8s.aws/federation: "amazon-vpc-lattice"

examples/service-2-import.yaml

@@ -0,0 +1,9 @@
+apiVersion: application-networking.k8s.aws/v1alpha1
+kind: ServiceImport
+metadata:
+  name: service-2
+spec:
+  type: ClusterSetIP
+  ports:
+  - port: 80
+    protocol: TCP

examples/service-2.yaml

@@ -0,0 +1,36 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: service-2
+  labels:
+    app: service-2
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: service-2
+  template:
+    metadata:
+      labels:
+        app: service-2
+    spec:
+      containers:
+      - name: service-2
+        image: public.ecr.aws/x2j8p8w7/http-server:latest
+        env:
+        - name: PodName
+          value: "service-2 handler pod"
+
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: service-2
+spec:
+  selector:
+    app: service-2
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 8090