Update deployment instructions (#516)

docs/concepts/custom-domain-name.md

@@ -43,13 +43,13 @@ AWS Gateway API Controller supports ExternalDNS integration through CRD source -
    The following example command runs ExternalDNS compiled from source, using AWS Route53 provider:
    ```sh
    build/external-dns --source crd --crd-source-apiversion externaldns.k8s.io/v1alpha1 \
-   --crd-source-kind DNSEndpoint --provider aws
+   --crd-source-kind DNSEndpoint --provider aws --txt-prefix "prefix."
    ```
 1. Create HTTPRoutes and Services. The controller should create `DNSEndpoint` resource owned by the HTTPRoute you created.
 1. ExternalDNS will watch the changes and create DNS record on the configured DNS provider.
 
 ## Notes
 
-* You MUST have a registered domain name (e.g. `my-test.com`) in route53 and complete the `Prerequisites` mentioned in [Configure a custom domain name for your service](https://docs.aws.amazon.com/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom).
+* You MUST have a registered hosted zone (e.g. `my-test.com`) in route53 and complete the `Prerequisites` mentioned in [Configure a custom domain name for your service](https://docs.aws.amazon.com/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom).
 * If you are not using ExternalDNS, you should manually associate your custom domain name with your service following [Configure a custom domain name for your service](https://docs.aws.amazon.com/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom).
 

docs/concepts/https.md

@@ -53,28 +53,29 @@ If you want to use a custom domain name along with its own certificate, you can:
 * Follow instructions on [Requesting a public certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) and get an ACM certificate ARN.
 * Add the ARN to the listener configuration as shown below.
 
-The following shows modifications to `examples/my-hotel.yaml` to add a custom certificate:
+The following shows modifications to `examples/my-hotel-gateway.yaml` to add a custom certificate:
 ```
 apiVersion: gateway.networking.k8s.io/v1beta1
 kind: Gateway
 metadata:
   name: my-hotel
+  annotations:
+    application-networking.k8s.aws/lattice-vpc-association: "true"
 spec:
   gatewayClassName: amazon-vpc-lattice
   listeners:
   - name: http
     protocol: HTTP
     port: 80
   - name: https
-    protocol: HTTPS
+    protocol: HTTPS      # This is required
     port: 443
-  - name: tls-with-custom-cert       # Specify listener with custom certs
-    protocol: HTTPS                  # Specify HTTPS protocol 
-    port: 443                        # Specify communication on port 443
-    tls:                             # Specify TLS configuration
-      mode: Terminate                # Specify mode for TLS listener
-      options:                       # Specify certificate options
-        application-networking.k8s.aws/certificate-arn: arn:aws:acm:us-west-2:<account>:certificate/4555204d-07e1-43f0-a533-d02750f41545 
+    tls:
+      mode: Terminate    # This is required
+      certificateRefs:   # This is required per API spec, but currently not used by the controller
+      - name: unused
+      options:           # Instead, we specify ACM certificate ARN under this section
+        application-networking.k8s.aws/certificate-arn: arn:aws:acm:us-west-2:<account>:certificate/<certificate-id>
 ```
 Note that only `Terminate` mode is supported (Passthrough is not supported).
 
@@ -91,14 +92,14 @@ spec:
   parentRefs:
   - name: my-hotel
     sectionName: http 
-  - name: my-hotel                     # Specify parentRefs
-    sectionName: tls-with-custom-cert  # Specify custom-defined certificate 
+  - name: my-hotel                     # Use the listener defined above as parentRef
+    sectionName: https
 ...
-```        
+```
 
 ### Enabling TLS connection on the backend
 
-Currently TLS Passthrough mode is not supported in the controller, but it allows TLS re-encryption to support backends that only allow TLS connections.
+Currently, TLS Passthrough mode is not supported in the controller, but it allows TLS re-encryption to support backends that only allow TLS connections.
 To handle this use case, you need to configure your service to receive HTTPS traffic instead:
 
 ```

docs/concepts/overview.md

@@ -59,7 +59,7 @@ With VPC Lattice you can also avoid some of these common problems:
 As a Kubernetes user, you can have a very Kubernetes-native experience using the VPC Lattice APIs.
 The following figure illustrates how VPC Lattice objects connect to [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) objects:
 
-![VPC Lattice objects relation to Kubernetes objects](images/personae.png)
+![VPC Lattice objects relation to Kubernetes objects](../images/personae.png)
 
 As shown in the figure, there are different personas associated with different levels of control in VPC Lattice.
 Notice that the Kubernetes Gateway API syntax is used to create the gateway, HTTPRoute and services, but Kubernetes gets the details of those items from VPC Lattice:

docs/faq.md

@@ -1,10 +1,24 @@
 # Frequently Asked Questions (FAQ)
 
-Q: How can I get involved with AWS Gateway API Controller?
-A: We welcome general feedback, questions, feature requests, or bug reports by creating a [Github issue](https://github.com/aws/aws-application-networking-k8s/issues/new).
+* **Q: How can I get involved with AWS Gateway API Controller?**
 
-Q: Where can I find AWS Gateway API Controller releases?
-A: AWS Gateway API Controller releases are tags of the Github repository. The [Github releases page](https://github.com/aws/aws-application-networking-k8s/releases) shows all the releases.
+  A: We welcome general feedback, questions, feature requests, or bug reports by creating a [Github issue](https://github.com/aws/aws-application-networking-k8s/issues/new).
 
-Q: Which EKS CNI versions are supported?
-A: Your AWS VPC CNI must be v1.8.0 or later to work with VPC Lattice.
+
+* **Q: Where can I find AWS Gateway API Controller releases?**
+
+  A: AWS Gateway API Controller releases are tags of the Github repository. The [Github releases page](https://github.com/aws/aws-application-networking-k8s/releases) shows all the releases.
+
+
+* **Q: Which EKS CNI versions are supported?**
+
+  A: Your AWS VPC CNI must be v1.8.0 or later to work with VPC Lattice.
+
+
+* **Q: Which versions of Gateway API are supported?**
+
+  A: AWS Gateway API Controller supports Gateway API CRD bundle versions between v0.6.1 and v1.0.0.
+  The controller does not reject other versions, but will provide "best effort support" to it.
+  Not all features of Gateway API are supported - for detailed features and limitation, please refer to individual API references.
+
+  By default, Gateway API v0.6.1 CRD bundle is included in the helm chart.

docs/guides/deploy.md

@@ -3,31 +3,36 @@
 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.
 
-**NOTE**: You can get the yaml files used on this page by cloning the [AWS Gateway API Controller for VPC Lattice](https://github.com/aws/aws-application-networking-k8s) site. The files are in the `examples/` directory.
+**NOTE**: You can get the yaml files used on this page by cloning the [AWS Gateway API Controller](https://github.com/aws/aws-application-networking-k8s) repository.
+
+## Cluster Setup
+
+### Using EKS Cluster
+
+EKS is a simple, recommended way of preparing a cluster for running services with AWS Gateway API Controller.
 
 1. Set your region and cluster name as environment variables. See the [Amazon VPC Lattice FAQs](https://aws.amazon.com/vpc/lattice/faqs/) for a list of supported regions. For this example, we use `us-west-2`:
    ```bash
    export AWS_REGION=us-west-2
    export CLUSTER_NAME=my-cluster
    ```
-2. You can use an existing EKS cluster or create a new one as shown here:
+1. You can use an existing EKS cluster or create a new one as shown here:
    ```bash
    eksctl create cluster --name $CLUSTER_NAME --region $AWS_REGION
    ```
-3. Configure security group to receive traffic from the VPC Lattice network. You must set up security groups so that they allow all Pods communicating with VPC Lattice to allow traffic from the VPC Lattice managed prefix lists.  See [Control traffic to resources using security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) for details. Lattice has both an IPv4 and IPv6 prefix lists available.
-
+1. Configure security group to receive traffic from the VPC Lattice network. You must set up security groups so that they allow all Pods communicating with VPC Lattice to allow traffic from the VPC Lattice managed prefix lists.  See [Control traffic to resources using security groups](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) for details. Lattice has both an IPv4 and IPv6 prefix lists available.
     ```bash
     CLUSTER_SG=$(aws eks describe-cluster --name $CLUSTER_NAME --output json| jq -r '.cluster.resourcesVpcConfig.clusterSecurityGroupId')
     PREFIX_LIST_ID=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=="\'com.amazonaws.$AWS_REGION.vpc-lattice\'"].PrefixListId" | jq -r '.[]')
     aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID}}],IpProtocol=-1"
     PREFIX_LIST_ID_IPV6=$(aws ec2 describe-managed-prefix-lists --query "PrefixLists[?PrefixListName=="\'com.amazonaws.$AWS_REGION.ipv6.vpc-lattice\'"].PrefixListId" | jq -r '.[]')
     aws ec2 authorize-security-group-ingress --group-id $CLUSTER_SG --ip-permissions "PrefixListIds=[{PrefixListId=${PREFIX_LIST_ID_IPV6}}],IpProtocol=-1"
     ```
-3. 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.
+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 $CLUSTER_NAME --approve --region $AWS_REGION
    ```
-4. 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:
+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",
@@ -57,15 +62,15 @@ Run through them again for a second cluster to use with the extended example sho
       --policy-name VPCLatticeControllerIAMPolicy \
       --policy-document file://examples/recommended-inline-policy.json
    ```
-5. Create the `aws-application-networking-system` namespace:
+1. Create the `aws-application-networking-system` namespace:
    ```bash
    kubectl apply -f examples/deploy-namesystem.yaml
    ```
-6. Retrieve the policy ARN:
+1. Retrieve the policy ARN:
    ```bash
    export VPCLatticeControllerIAMPolicyArn=$(aws iam list-policies --query 'Policies[?PolicyName==`VPCLatticeControllerIAMPolicy`].Arn' --output text)
    ```
-7. Create an iamserviceaccount for pod level permission:
+1. Create an iamserviceaccount for pod level permission:
    ```bash
    eksctl create iamserviceaccount \
       --cluster=$CLUSTER_NAME \
@@ -76,7 +81,53 @@ Run through them again for a second cluster to use with the extended example sho
       --region $AWS_REGION \
       --approve
    ```
-8. Run either `kubectl` or `helm` to deploy the controller:
+
+#### IPv6 support
+
+IPv6 address type is automatically used for your services and pods if
+[your cluster is configured to use IPv6 addresses](https://docs.aws.amazon.com/eks/latest/userguide/cni-ipv6.html).
+
+```bash
+# To create an IPv6 cluster
+kubectl apply -f examples/ipv6-cluster.yaml
+```
+
+If your cluster is configured to be dual-stack, you can set the IP address type
+of your service using the `ipFamilies` field. For example:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: ipv4-target-in-dual-stack-cluster
+spec:
+  ipFamilies:
+    - "IPv4"
+  selector:
+    app: parking
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 8090
+```
+
+
+### Using a self-managed Kubernetes cluster
+
+You can install AWS Gateway API Controller to a self-managed Kubernetes cluster in AWS.
+
+The controller utilizes [IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) to get necessary information from instance metadata, such as AWS account ID and VPC ID.
+If your cluster is using IMDSv2, ensure the hop limit is 2 or higher to allow the access from the controller:
+
+```bash
+aws ec2 modify-instance-metadata-options --http-put-response-hop-limit 2 --region <region> --instance-id <instance-id>
+```
+
+Alternatively, you can manually provide configuration variables when installing the controller, as described in the next section.
+
+## Controller Installation
+
+1. Run either `kubectl` or `helm` to deploy the controller. Check [Environment Variables](../concepts/environment.md) for detailed explanation of each configuration option.
    ```bash
    kubectl apply -f examples/deploy-v0.0.18.yaml
    ```
@@ -89,16 +140,17 @@ Run through them again for a second cluster to use with the extended example sho
       oci://public.ecr.aws/aws-application-networking-k8s/aws-gateway-controller-chart\
       --version=v0.0.18 \
       --set=serviceAccount.create=false --namespace aws-application-networking-system \
-      # awsRegion, clusterVpcId, clusterName, awsAccountId are required for case where IMDS is NOT AVAILABLE, e.g Fargate, self-managed clusters with IMDS access blocked 
+      # awsRegion, clusterVpcId, awsAccountId are required for case IMDS is not available.
       --set=awsRegion= \
       --set=clusterVpcId= \
-      --set=clusterName= \
       --set=awsAccountId= \
-      # latticeEndpoint is required for the case where the VPC Lattice endpoint is being overridden
-      --set=latticeEndpoint= \
-   
+      # clusterName is required except for EKS cluster.
+      --set=clusterName= \
+      # When specified, the controller will automatically create a service network with the name.
+      --set=defaultServiceNetwork=my-hotel
    ```
-9. Create the `amazon-vpc-lattice` GatewayClass:
+1. Create the `amazon-vpc-lattice` GatewayClass:
    ```bash
    kubectl apply -f examples/gatewayclass.yaml
    ```
+1. You are all set! Check our [Getting Started Guide](getstarted.md) to try setting up service-to-service communication.

docs/guides/getstarted.md

@@ -6,49 +6,46 @@ The first part of this section provides an example of setting up of service-to-s
 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.
 
-Using these examples as a foundation, see the [Configuration](configure/index.md) section for ways to further configure service-to-service communications.
+Using these examples as a foundation, see the [Configuration](../concepts/index.md) section for ways to further configure service-to-service communications.
 
 
-**NOTE**: You can get the yaml files used on this page by cloning the [AWS Gateway API Controller for VPC Lattice](https://github.com/aws/aws-application-networking-k8s) site. The files are in the `examples/` directory.
+**NOTE**: You can get the yaml files used on this page by cloning the [AWS Gateway API Controller](https://github.com/aws/aws-application-networking-k8s) repository.
 
 ## 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)
+![Single cluster/VPC service-to-service communications](../images/example1.png)
 
 ### Steps
 
-**Set up service-to-service communications**
+#### Setup service-to-service communications
 
-1. Use AWS CLI to create a VPC Lattice service network, with the name `my-hotel`:
+1. AWS Gateway API Controller needs a VPC Lattice service network to operate.
+   When `DEFAULT_SERVICE_NETWORK` environment variable is specified, the controller will automatically configure a service network for you.
+  For example:
    ```bash
-   aws vpc-lattice create-service-network --name my-hotel 
-   {
-    "arn": "<my-hotel-sn-arn>",
-    "authType": "NONE",
-    "id": "<my-hotel-sn-id>",
-    "name": "my-hotel"
-   }
+   helm upgrade gateway-api-controller \
+     oci://281979210680.dkr.ecr.us-west-2.amazonaws.com/aws-gateway-controller-chart \
+     --reuse-values \
+     --set=defaultServiceNetwork=my-hotel
    ```
-
-1. Create the service network VPC association between current k8s cluster VPC and `my-hotel` service network:
-   ```bash
-     aws vpc-lattice create-service-network-vpc-association --service-network-identifier <my-hotel-sn-id> --vpc-identifier <k8s-cluster-vpc-id>
-      {
-       "arn": "<snva-arn>",
-       "createdBy": "<timestamp>",
-       "id": "<snva-id>",
-       "status": "CREATE_IN_PROGRESS"
-       }
-      ```
-
-   Wait until above ServiceNetworkVpcAssociation status change to `ACTIVE`:
+   Alternatively, you can use AWS CLI to manually create a VPC Lattice service network, with the name `my-hotel`:
    ```bash
-   aws vpc-lattice  get-service-network-vpc-association --service-network-vpc-association-identifier snva-0041ace3a8658371e
+   aws vpc-lattice create-service-network --name my-hotel # grab service network ID
+   aws vpc-lattice create-service-network-vpc-association --service-network-identifier <service-network-id> --vpc-identifier <k8s-cluster-vpc-id>
+   ```
+   Ensure the service network created above is ready to accept traffic, by checking if the VPC association status is `ACTIVE`:
+   ```bash
+   aws vpc-lattice list-service-network-vpc-associations --vpc-id <k8s-cluster-vpc-id>
    {
-       ....
-       "status": "ACTIVE",
+      "items": [
+         {
+             ...
+            "status": "ACTIVE",
+             ...
+         }
+      ]
    }
    ```
 1. Create the Kubernetes Gateway `my-hotel`:
@@ -120,7 +117,8 @@ This example creates a single cluster in a single VPC, then configures two route
    echo $ratesFQDN $inventoryFQDN
    rates-default-034e0056410499722.7d67968.vpc-lattice-svcs.us-west-2.on.aws inventory-default-0c54a5e5a426f92c2.7d67968.vpc-lattice-svcs.us-west-2.on.aws
    ```
-   **Verify service-to-service communications**
+
+#### Verify service-to-service communications
 
 1. Check connectivity from  the `inventory-ver1` service to `parking` and `review` services:
    ```bash
@@ -150,7 +148,7 @@ For example, it will:
 
 The following figure illustrates this:
 
-![Multiple clusters/VPCs service-to-service communications](images/example2.png)
+![Multiple clusters/VPCs service-to-service communications](../images/example2.png)
 
 ### Steps
 
@@ -204,32 +202,3 @@ The following figure illustrates this:
    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.
-
-## IPv6 Support
-
-IPv6 address type is automatically used for your services and pods if
-[your cluster is configured to use IPv6 addresses](https://docs.aws.amazon.com/eks/latest/userguide/cni-ipv6.html).
-
-```bash
-# To create an IPv6 cluster
-kubectl apply -f examples/ipv6-cluster.yaml
-```
-
-If your cluster is configured to be dual-stack, you can set the IP address type
-of your service using the `ipFamilies` field. For example:
-
-```yaml
-apiVersion: v1
-kind: Service
-metadata:
-  name: ipv4-target-in-dual-stack-cluster
-spec:
-  ipFamilies:
-    - "IPv4"
-  selector:
-    app: parking
-  ports:
-    - protocol: TCP
-      port: 80
-      targetPort: 8090
-```