Refactor existing docs content into multiple pages

docs/configure.md

@@ -0,0 +1,213 @@
+# Using the AWS Gateway API Controller
+
+The first part of this section provides an example of setting up of service-to-service communications on a single cluster.
+The second section extends that example by creating another inventory service on a second cluster on a different VPC, and spreading traffic to that service across the two clusters and VPCs.
+Both clusters are created using `eksctl`, with both clusters created from the same account by the same cluster admin.
+
+## Set up single-cluster/VPC service-to-service communications
+
+This example creates a single cluster in a single VPC, then configures two routes (rates and inventory) and three services (parking, review, and inventory-1). The following figure illustrates this setup:
+
+![Single cluster/VPC service-to-service communications](images/example1.png)
+
+**Steps**
+
+   **Set up Service-to-Service communications**
+
+1. Create the Kubernetes Gateway `my-hotel`:
+   ```bash
+   kubectl apply -f examples/my-hotel-gateway.yaml
+   ```
+1. Verify that `my-hotel` gateway is created (this could take about five minutes):
+   ```bash
+   kubectl get gateway  
+   ```
+   ```
+   NAME       CLASS         ADDRESS   READY   AGE
+   my-hotel   aws-lattice                     7d12h
+   ```
+1. Once the gateway is created, find the VPC Lattice service network:
+   ```bash
+   kubectl get gateway my-hotel -o yaml
+   ```
+   ```
+   apiVersion: gateway.networking.k8s.io/v1alpha2
+   kind: Gateway
+   ...
+   status:
+   conditions:
+   message: 'aws-gateway-arn: arn:aws:vpc-lattice:us-west-2:694065802095:servicenetwork/sn-0ab6bb70055929edd'
+   reason: Reconciled
+   status: "True"
+   ```
+1. Create the Kubernetes HTTPRoute rates for the parking service, review service, and HTTPRoute rate:
+   ```bash
+   kubectl apply -f examples/parking.yaml
+   kubectl apply -f examples/review.yaml
+   kubectl apply -f examples/rate-route-path.yaml
+   ```
+1. Create the Kubernetes HTTPRoute inventory (this could take about five minutes):
+   ```bash
+   kubectl apply -f examples/inventory-ver1.yaml
+   kubectl apply -f examples/inventory-route.yaml
+   ```
+1. Find out HTTPRoute's DNS name from HTTPRoute status:
+   ```bash
+   kubectl get httproute
+   ```
+   ```
+   NAME        HOSTNAMES   AGE
+   inventory               51s
+   rates                   6m11s
+   ```
+1. List the route’s yaml file to see the DNS address (highlighted here on the `message` line):
+
+      ```bash
+      kubectl get httproute inventory -o yaml
+      ```
+
+      ```
+      apiVersion: gateway.networking.k8s.io/v1alpha2
+      kind: HTTPRoute
+      metadata:
+      annotations:
+         kubectl.kubernetes.io/last-applied-configuration: |
+            {"apiVersion":"gateway.networking.k8s.io/v1alpha2","kind":"HTTPRoute","metadata":{"annotations":{},"name":"inventory","namespace":"default"}... }}]}]}}
+      ...
+      status:
+      parents:
+      - conditions:
+         - lastTransitionTime: "2022-11-22T02:29:22Z"
+            message: 'DNS Name: <b><i>inventory-default-0f326944c3d681c0d.7d67968.vpc-lattice-svcs.us-west-2.on.aws</i></b>'
+            reason: Reconciled
+            status: "True"
+            type: httproute
+         controllerName: application-networking.k8s.aws/gateway-api-controller
+         parentRef:
+            group: gateway.networking.k8s.io
+            kind: Gateway
+            name: my-hotel
+      ...
+      ```
+
+      ```bash
+      kubectl get httproute rates inventory -o yaml
+      ```
+
+**Check service connectivity**
+
+1. Check Service-Inventory Pod access for Service-Rates/parking or Service-Rates/review by execing into the pod, then curling each service.
+   ```bash
+   kubectl get pod
+   ```
+   ```
+   NAME                                    READY   STATUS    RESTARTS   AGE
+   inventory-ver1-7bb6989d9d-2p2hk         1/1     Running   0          7d13h
+   inventory-ver1-7bb6989d9d-464rk         1/1     Running   0          7d13h
+   parking-6cdcd5b4b4-bbzvt                1/1     Running   0          103m
+   parking-6cdcd5b4b4-g8dkb                1/1     Running   0          103m
+   review-5888566ff6-2plsj                 1/1     Running   0          101m
+   review-5888566ff6-89fqk                 1/1     Running   0          101m
+   ```
+1. Exec into an inventory pod to check connectivity to parking and review services:
+   ```bash
+   kubectl exec -ti inventory-ver1-7bb6989d9d-2p2hk sh
+   ```
+1. From inside of the inventory pod, use `curl` to connect to the parking service (using the DNS Name from the previous `kubectl get httproute` command):
+   ```bash
+   curl rates-00422586e3362607e.7d67968.vpc-service-network-svcs.us-west-2.amazonaws.com/parking 
+   ```
+   ```
+   Requesting to Pod(parking-6cdcd5b4b4-g8dkb): parking handler pod
+   ```
+1. From inside of the pod, use `curl` to connect to the review service:
+   ```bash
+   curl rates-00422586e3362607e.7d67968.vpc-service-network-svcs.us-west-2.amazonaws.com/review 
+   ```
+   ```
+   Requesting to Pod(review-5888566ff6-89fqk): review handler pod
+   ```
+1. Exit the pod:
+   ```bash
+   exit
+   ```
+1. Exec into a parking pod to check connectivity to the inventory-ver1 service:
+   ```bash
+   kubectl exec -ti parking-6cdcd5b4b4-bbzvt sh
+   ```
+1. From inside of the parking pod, use `curl` to connect to the inventory-ver1 service:
+   ```bash
+   curl inventory-00422586e3362607e.7d67968.vpc-service-network-svcs.us-west-2.amazonaws.com
+   ```
+   ```
+   Requesting to Pod(inventory-ver1-7bb6989d9d-2p2hk): inventory-ver1 handler pod 
+   ```
+## Set up multi-cluster/multi-VPC service-to-service communications
+
+This sections builds on the previous section by migrating a Kubernetes service (HTTPRoute inventory) from one Kubernetes cluster to a different Kubernetes cluster.
+For example, it will:
+
+* Migrate the Kubernetes inventory service from a Kubernetes v1.21 cluster to a Kubernetes v1.23 cluster in a different VPC.
+* Scale up the Kubernetes inventory service to run it in another cluster (and another VPC) in addition to the current cluster.
+
+The following figure illustrates this:
+
+![Multiple clusters/VPCs service-to-service communications](images/example2.png)
+
+**Steps**
+
+   **Set up inventory on a second cluster** 
+
+1. Create a second cluster (using the same instructions used to create the first).
+
+1. Ensure you're using the second cluster profile. 
+   ```bash
+   kubectl config get-contexts 
+   ```
+   If your profile is set to the first cluster, switch your credentials to use the second cluster:
+   ```bash
+   kubectl config use-context <yourcluster2info>
+   ```
+1. Create a Kubernetes inventory-ver2 service in the second cluster:
+   ```bash
+   kubectl apply -f examples/inventory-ver2.yaml
+   ```
+1. Export this Kubernetes inventory-ver2 from the second cluster, so that it can be referenced by HTTPRoute in the other cluster:
+   ```bash
+   kubectl apply -f examples/inventory-ver2-export.yaml
+   ```
+   **Switch back to the first cluster**
+
+1. Switch credentials back to the first cluster
+   ```bash
+   kubectl config use-context <yourcluster1info>
+   ```
+1. Import the Kubernetes inventory-ver2 into first cluster:
+   ```bash
+   kubectl apply -f examples/inventory-ver2-import.yaml
+   ```
+1. Update the HTTPRoute inventory to route 10% traffic to the first cluster and 90% traffic to the second cluster:
+   ```bash
+   kubectl apply -f examples/inventory-route-bluegreen.yaml
+   ```
+1. Check the Service-Rates/parking pod access to Service-Inventory by execing into the parking pod:
+   ```bash
+   kubectl exec -ti parking-6cdcd5b4b4-bbzvt sh
+   ```
+1. From inside of the pod, use `curl` to connect to the inventory service:
+
+      ```bash
+      for ((i=1;i<=30;i++)); do   curl   "inventory-default-0f89d8ff5e98400d0.7d67968.vpc-lattice-svcs.us-west-2.on.aws"; done
+      ```
+      ```
+      Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod <----> in 2nd cluster
+      Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod
+      Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod
+      Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod
+      Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver1 handler pod <----> in 1st cluster
+      Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod
+      Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver2 handler pod
+      Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver2 handler pod
+      Requsting to Pod(inventory-ver1-74fc59977-wg8br): Inventory-ver1 handler pod....
+      ```
+      You can see that the traffic is distributed between *inventory-ver1* and *inventory-ver2* as expected.

docs/deploy.md

@@ -0,0 +1,85 @@
+# Deploying the AWS Gateway API Controller
+
+Follow these instructions to create a cluster and deploy the AWS Gateway API Controller.
+Run through them again for a second cluster to use with the extended example shown later.
+
+1. You can use an existing EKS cluster or create a new one as shown here:
+   ```bash
+   eksctl create cluster --name <my-cluster> --region us-west-2
+   ```
+1. Configure security group: To receive traffic from the VPC Lattice fleet, you must set up security groups so that they allow all Pods communicating with VPC Lattice to allow traffic on all ports from the 169.254.171.0/24 address range. See [Control traffic to resources using security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) for details. You can use the following managed prefix to provide the values:
+   ```bash
+   aws ec2 get-managed-prefix-list-entries --region us-west-2 --prefix-list-id pl-0721453c7ac4ec009
+   ```
+   ```
+   ENTRIES 169.254.171.0/24
+   ```
+1. Create an IAM OIDC provider: See [Creating an IAM OIDC provider for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) for details.
+   ```bash
+   eksctl utils associate-iam-oidc-provider --cluster <my-cluster> --approve
+   ```
+1. Create a policy (`recommended-inline-policy.json`) in IAM with the following content that can invoke the gateway API and copy the policy arn for later use:
+   ```bash
+   {
+       "Version": "2012-10-17",
+       "Statement": [
+           {
+               "Effect": "Allow",
+               "Action": [
+                   "vpc-lattice:*",
+                   "iam:CreateServiceLinkedRole",
+                   "ec2:DescribeVpcs",
+                   "ec2:DescribeSubnets"
+               ],
+               "Resource": "*"
+           }
+       ]
+   }
+   ```
+   ```bash
+   aws iam create-policy \
+      --policy-name VPCLatticeControllerIAMPolicy \
+      --policy-document file://examples/recommended-inline-policy.json
+   ```
+1. Create the `system` namespace:
+   ```bash
+   kubectl apply -f examples/deploy-namesystem.yaml
+   ```
+1. Retrieve the policy ARN:
+   ```bash
+   export VPCLatticeControllerIAMPolicyArn=$(aws iam list-policies --query 'Policies[?PolicyName==`VPCLatticeControllerIAMPolicy`].Arn' --output text)
+   ```
+1. Create an iamserviceaccount for pod level permission:
+   ```bash
+   eksctl create iamserviceaccount \
+      --cluster=<my-cluster> \
+      --namespace=system \
+      --name=gateway-api-controller \
+      --attach-policy-arn=$VPCLatticeControllerIAMPolicyArn \
+      --override-existing-serviceaccounts \
+      --region us-west-2 \
+      --approve
+   ```
+
+1. Run either `kubectl` or `helm` to deploy the controller:
+
+      ```bash
+      kubectl apply -f examples/deploy-v0.0.1.yaml
+      ```
+
+      or
+
+      ```bash
+      # login to ECR
+      aws ecr-public get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin public.ecr.aws
+      # Run helm with either install or upgrade
+      helm install gateway-api-controller \
+         oci://public.ecr.aws/aws-application-networking-k8s/aws-gateway-controller-chart\
+         --version=v0.0.2 \
+         --set=aws.region=us-west-2 --set=serviceAccount.create=false --namespace system
+      ```
+
+1. Create the amazon-vpc-lattice GatewayClass:
+   ```bash
+   kubectl apply -f examples/gatewayclass.yaml
+   ```