Refactored documentation (#630)

* Documentation refactoring

docs/api-reference.md

@@ -1,4 +1,4 @@
-# API Reference
+# API Specification
 
 This page contains the API field specification for Gateway API.
 

docs/api-types/service-export.md

@@ -12,7 +12,6 @@ for example, using target groups in the VPC Lattice setup outside Kubernetes.
 Note that ServiceExport is not the implementation of Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/);
 instead AWS Gateway API Controller uses its own version of the resource for the purpose of Gateway API integration.
 
-For more multi-cluster use cases and detailed explanation, please refer to [our recommended multi-cluster architecture](../guides/multi-cluster.md).
 
 ### Limitations
 * The exported Service can only be used in HTTPRoutes. GRPCRoute is currently not supported.

docs/api-types/service-import.md

@@ -11,7 +11,6 @@ Just like Services, ServiceImports can be a backend reference of HTTPRoutes. Alo
 Note that ServiceImport is not the implementation of Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/);
 instead AWS Gateway API Controller uses its own version of the resource for the purpose of Gateway API integration.
 
-For more multi-cluster use cases, please refer to [our recommended multi-cluster architecture](../guides/multi-cluster.md).
 
 ### Limitations
 * ServiceImport shares the limitations of [ServiceExport](service-export.md).

docs/concepts/concepts.md

@@ -0,0 +1,21 @@
+# AWS Gateway API Controller User Guide
+
+As part of the VPC Lattice launch, AWS introduced the AWS Gateway API Controller ; an implementation of the Kubernetes Gateway API. Gateway API is an open-source standard interface to enable Kubernetes application networking through expressive, extensible, and role-oriented interfaces. AWS Gateway API controller extends custom resources, defined by Gateway API, which allows you to create VPC Lattice resources using Kubernetes APIs.
+
+When installed in your cluster, the controller watches for the creation of Gateway API resources such as gateways and routes and provisions corresponding Amazon VPC Lattice objects. This enables users to configure VPC Lattice Services, VPC Lattice service networks and Target Groups using Kubernetes APIs, without needing to write custom code or manage sidecar proxies. The AWS Gateway API Controller is an open-source project and fully supported by Amazon.
+
+AWS Gateway API Controller integrates with Amazon VPC Lattice and allows you to:
+
+* Handle network connectivity seamlessly between services across VPCs and accounts.
+* Discover VPC Lattice services spanning multiple Kubernetes clusters.
+* Implement a defense-in-depth strategy to secure communication between those services.
+* Observe the request/response traffic across the services.
+
+This documentation describes how to set up the AWS Gateway API Controller, provides example use cases, development concepts, and API references. AWS Gateway API Controller will provide developers the ability to publish services running on Kubernetes cluster and other compute platforms on AWS such as AWS Lambda or Amazon EC2. Once the AWS Gateway API controller deployed and running, you will be able to manage services for multiple Kubernetes clusters and other compute targets on AWS through the following:
+
+* **CLI**: Use `aws` and `eksctl` to create clusters and set up AWS policies. Then use `kubectl` and YAML files to set up Kubernetes objects.
+* **AWS Console**: View VPC Lattice assets through the VPC area of the AWS console.
+
+Integrating with the Kubernetes Gateway API provides a kubernetes-native experience for developers to create services, manage network routing and traffic behaviour without the heavy lifting managing the underlying networking infrastrcuture. This lets you work with Kubernetes service-related resources using Kubernetes APIs and custom resource definitions (CRDs) defined by the Kubernetes [networking.k8s.io specification](https://gateway-api.sigs.k8s.io/references/spec/).
+
+For more information on this technology, see [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). 

docs/concepts/overview.md

@@ -4,68 +4,84 @@ For medium and large-scale customers, applications can often spread across multi
 For example, information pertaining to a company’s authentication, billing, and inventory may each be served by services running on different VPCs in AWS.
 Someone wanting to run an application that is spread out in this way might find themselves having to work with multiple ways to configure:
 
-- Authentication and authorization
+- Authentication and Authorization
 - Observability
-- Service discovery
+- Service Discovery
 - Network connectivity and traffic routing
 
 This is not a new problem.
-A common approach to interconnecting services that span multiple VPCs is to use service meshes. But these require sidecars, which can introduce scaling problems and present their own management challenges, such as dealing with control plane and data plane at scale.
+A common approach to interconnecting services that span multiple VPCs is to use service meshes. However, these require sidecars, which can introduce scaling problems and present their own management challenges, such as dealing with control plane and data plane at scale.
 
 If you just want to run an application, you should be shielded from details needed to find assets across multiple VPCs and multiple clusters. You should also have consistent ways of working with assets across your VPCs, even if those assets include different combinations of instances, clusters, containers, and serverless. And while making it simpler to run multi-VPC applications easier for users, administrators still need the tools to control and audit their resources to suit their company’s compliance needs.
 
 ## Service Directory, Networks, Policies and Gateways
 
-The goal of VPC Lattice is to provide a way to have a single, over-arching services view of all services across multiple VPCs.
-You should also have consistent ways of working with assets across your VPCs, even if those assets include different combinations of instances, clusters, containers, and serverless.
+The goal of VPC Lattice is to provide a way to have a single, overarching services view of all services across multiple VPCs. You should also have consistent ways of working with assets across your VPCs, even if those assets include different combinations of instances, clusters, containers, and serverless.
 The components making up that view include:
 
-- Service Directory: This is an account-level directory for gathering your services in once place.
-  This can provide a view from the VPC Lattice section of the AWS console into all the services you own, as well as services that are shared with you.
-  A service might direct traffic to a particular service type (such as HTTP) and port (such as port 80).
-  However, using different rules, a request for the service could be sent to different targets such as a Kubernetes pod or a Lambda function, based on path or query string parameter.
+**Service**
 
-- Service Network: Because applications might span multiple VPCs and accounts, there is a need to create networks that span those items.
-  These networks let you register services to run across accounts and VPCs.
-  You can create common authorization rules to simplify connectivity.
+An independently deployable unit of software that delivers a specific task or function. A service can run on EC2 instances or ECS containers, or as Lambda functions, within an account or a virtual private cloud (VPC). 
 
-- Service Policies: You can build service policies to configure observability, access, and traffic management across any service network or gateway.
-  You configure rules for handling traffic and for authorizing access.
-  For now, you can assign IAM roles to allow certain requests.
-  These are similar to S3 or IAM resource policies.
-  Overall, this provides a common way to apply access rules at the service or service network levels.
 
-- Service Gateway: This feature is not yet implemented.
-  It is meant to centralize management of ingress and egress gateways.
-  The Service Gateway will also let you manage access to external dependencies and clients using a centrally managed VPC.
+<figure markdown="span">
+  ![VPC Lattice Service](../images/service.png){ width="500" }
+  <figcaption>A VPC Lattice service has the following components: target groups, listeners, and rules.</figcaption>
+</figure>
 
-If all goes well, you should be able to achieve some of the following goals:
 
-- Kubernetes multi-cluster connectivity: Say that you have multiple clusters across multiple VPCs.
-  After configuring your services with the Kubernetes Gateway API, you can facilitate communications between services on those clusters without dealing with the underlying infrastructure.
+**Service Network**
+
+A logical boundary for a collection of services. A client is any resource deployed in a VPC that is associated with the service network. Clients and services that are associated with the same service network can communicate with each other if they are authorized to do so.
+
+<figure markdown="span">
+  ![VPC Lattice service network](../images/service-network.png){ width="400" }
+  <figcaption>In the following figure, the clients can communicate with both services, because the VPC and services are associated with the same service network.</figcaption>
+</figure>
+
+**Service Directory**
+A central registry of all VPC Lattice services that you own or are shared with your account through [AWS Resource Access Manager](https://aws.amazon.com/ram/) (AWS RAM).
+
+**Auth Policies**
+Fine-grained authorization policies that can be used to define access to services. You can attach separate authorization policies to individual services or to the service network. For example, you can create a policy for how a payment service running on an auto scaling group of EC2 instances should interact with a billing service running in AWS Lambda.
+
+## Use-cases
+
+In the context of Kubernetes, Amazon VPC Lattice helps to simplify the following:
+
+- **Kubernetes multi-cluster connectivity**: Architecting multiple clusters across multiple VPCs.
+  After configuring your services with the AWS Gateway API Controller, you can facilitate advanced traffic management and application layer routing between services on those clusters without dealing with the underlying infrastructure.
   VPC Lattice handles a lot of the details for you without needing things like sidecars.
-- Serverless access: VPC Lattice allows access to serverless features, as well as Kubernetes cluster features.
+- **Cross-platform access**: VPC Lattice allows access to serverless and Amazon EC2 features, as well as Kubernetes cluster features.
   This gives you a way to have a consistent interface to multiple types of platforms.
+- **Implement a defense-in-depth strategy**: Secure communication between services and networks.
+- **Observe the request/response traffic** across the services.
+
 
 With VPC Lattice you can also avoid some of these common problems:
 
-- Overlapping IP addresses: Even with well-managed IP addresses, overlapping address use can occur by mistake or when organizations or companies merge together.
+- **Overlapping IP addresses**: Even with well-managed IP addresses, overlapping address use can occur by mistake or when organizations or companies merge together.
   IP address conflicts can also occur if you wanted to manage resources across multiple Kubernetes clusters.
-- Sidecar management: Changes to sidecars might require those sidecars to be reconfigured or rebooted.
+- **Sidecar management**: Changes to sidecars might require those sidecars to be reconfigured or rebooted.
   While this might not be a big issue for a handful of sidecars, it can be disruptive if you have thousands of pods, each with its own sidecar.
 
 ## Relationship between VPC Lattice and Kubernetes
 
 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)
+<figure markdown="span">
+  ![VPC Lattice objects relation to Kubernetes objects](../images/fundamentals-mapping.png){ width="550" }
+</figure>
+
 
 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:
 
-- Infrastructure provider: Creates the Kubernetes GatewayClass to identify VPC Lattice as the GatewayClass.
-- Cluster operator: Creates the Kubernetes Gateway, which gets information from VPC Lattice related to the Service Gateway and Service Networks, as well as their related Service Policies.
-- Application developer: Creates HTTPRoute objects that point to Kubernetes services, which in turn are directed to particular pods, in this case.
-  This is all done by checking the related VPC Lattice Services (and related policies), Target Groups, and Targets
-  Keep in mind that Target Groups v1 and v2 can be on different clusters in different VPCs.
+- **Infrastructure provider**: Creates the Kubernetes `GatewayClass` to identify VPC Lattice as the GatewayClass.
+- **Cluster operator**: Creates the Kubernetes `Gateway`, which gets information from VPC Lattice related to the Service Gateway and service networks, as well as their related Service Policies.
+- **Application developer**: Creates `HTTPRoute` objects that point to Kubernetes services, which in turn are directed to particular pods, in this case.
+
+This is all done by checking the related VPC Lattice Services (and related policies), Target Groups, and Targets.
+
+Keep in mind that you can have different Target Groups spread across different clusters/VPCs receiving traffic from the same VPC Lattice Service (`HTTPRoute`).