From e36461221deca6990fd55ce51b2dbfaf2186eac8 Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Fri, 17 Nov 2023 07:54:04 -0800 Subject: [PATCH 1/2] Update Gateway resource docs and fix markdown styles --- docs/api-types/gateway.md | 71 ++++++++++++++++++++++++ docs/api-types/grpc-route.md | 14 +++-- docs/api-types/http-route.md | 14 +++-- docs/api-types/iam-auth-policy.md | 2 +- docs/api-types/service.md | 2 +- docs/api-types/target-group-policy.md | 2 +- docs/api-types/vpc-association-policy.md | 6 +- docs/concepts/grpc.md | 4 -- docs/faq.md | 18 ++---- mkdocs.yml | 3 +- 10 files changed, 104 insertions(+), 32 deletions(-) create mode 100644 docs/api-types/gateway.md diff --git a/docs/api-types/gateway.md b/docs/api-types/gateway.md new file mode 100644 index 00000000..de9462f1 --- /dev/null +++ b/docs/api-types/gateway.md @@ -0,0 +1,71 @@ +# Gateway API Reference + +## Introduction + +`Gateway` allows you to configure network traffic through AWS Gateway API Controller. +When a Gateway is defined with `amazon-vpc-lattice` GatewayClass, the controller will watch for the gateway +and the resources under them, creating required resources under Amazon VPC Lattice. + +Internally, a Gateway points to a VPC Lattice [service network](https://docs.aws.amazon.com/vpc-lattice/latest/ug/service-networks.html). +Service networks are identified by Gateway name (without namespace) - for example, a Gateway named `my-gateway` +will point to a VPC Lattice service network `my-gateway`. If multiple Gateways share the same name, all of them +will point to the same service network. + +VPC Lattice service networks must be managed separately, as it is a broader concept that can cover resources +outside the Kubernetes cluster. To create and manage a service network, you can either: + +- Specify `DEFAULT_SERVICE_NETWORK` configuration option on the controller. This will make the controller + to create a service network with such name, and associate the cluster VPC to it for you. This is suitable + for simple use cases with single service network. +- Manage service networks outside the cluster, using AWS Console, CDK, CloudFormation, etc. This is recommended + for more advanced use cases that cover multiple clusters and VPCs. + +Gateways with `amazon-vpc-lattice` GatewayClass do not create a single entrypoint to bind Listeners and Routes +under them. Instead, each Route will have its own domain name assigned. To see an example of how domain names +are assigned, please refer to our [Getting Started Guide](../guides/getstarted.md). + +### Supported GatewayClass +- `amazon-vpc-lattice` + This is the default GatewayClass for managing traffic using Amazon VPC Lattice. + +### Limitations +- GatewayAddress status does not represent all accessible endpoints belong to a Gateway. + Instead, you should check annotations of each Route. +- Only `Terminate` is supported for TLS mode. TLSRoute is currently not supported. +- TLS certificate cannot be provided through `certificateRefs` field by `Secret` resource. + Instead, you can create an ACM certificate and put its ARN to the `options` field. + +## Example Configuration + +Here is a sample configuration that demonstrates how to set up a `Gateway`: + +```yaml +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: Gateway +metadata: + name: my-hotel +spec: + gatewayClassName: amazon-vpc-lattice + listeners: + - name: http + protocol: HTTP + port: 80 + - name: https + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - name: unused + options: + application-networking.k8s.aws/certificate-arn: +``` + +The created Gateway will point to a VPC Lattice service network named `my-hotel`. Routes under this Gateway can have +either `http` or `https` listener as a parent based on their desired protocol to use. + +--- + +This `Gateway` documentation provides a detailed introduction, feature set, and a basic example of how to configure +and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the +official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway). \ No newline at end of file diff --git a/docs/api-types/grpc-route.md b/docs/api-types/grpc-route.md index eef30395..5cdaeea9 100644 --- a/docs/api-types/grpc-route.md +++ b/docs/api-types/grpc-route.md @@ -2,10 +2,10 @@ ## Introduction -With integration of the Gateway API, the EKS Controller project supports `GRPCRoute`. +With integration of the Gateway API, AWS Gateway API Controller supports `GRPCRoute`. This allows you to define and manage the routing of gRPC traffic within your Kubernetes cluster. -### GRPCRoute Key Features & Limitations: +### GRPCRoute Key Features & Limitations **Features**: @@ -25,7 +25,13 @@ This allows you to define and manage the routing of gRPC traffic within your Kub - **No Method Without Service**: Matching only by a gRPC method without specifying a service is not supported. - **Case Insensitivity**: All method matches are currently case-insensitive. -## Example Configuration: +### Annotations + +- `application-networking.k8s.aws/lattice-assigned-domain-name` + Represents a VPC Lattice generated domain name for the resource. This annotation will automatically set + when a `GRPCRoute` is programmed and ready. + +## Example Configuration Here is a sample configuration that demonstrates how to set up a `GRPCRoute` for a HelloWorld gRPC service: @@ -71,5 +77,5 @@ In this example: --- This `GRPCRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure -and use the resource within the EKS Controller project. For in-depth details and specifications, you can refer to the +and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the official [Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha2.GRPCRoute). \ No newline at end of file diff --git a/docs/api-types/http-route.md b/docs/api-types/http-route.md index 2c3c7464..89124120 100644 --- a/docs/api-types/http-route.md +++ b/docs/api-types/http-route.md @@ -2,10 +2,10 @@ ## Introduction -With integration of the Gateway API, the EKS Controller project supports `HTTPRoute`. +With integration of the Gateway API, AWS Gateway API Controller supports `HTTPRoute`. This allows you to define and manage the routing of HTTP and HTTPS traffic within your Kubernetes cluster. -### HTTPRoute Key Features & Limitations: +### HTTPRoute Key Features & Limitations **Features**: @@ -24,7 +24,13 @@ This allows you to define and manage the routing of HTTP and HTTPS traffic withi - **Header Matches Limit**: A maximum of 5 header matches per rule is supported. - **Case Insensitivity**: All path matches are currently case-insensitive. -## Example Configuration: +### Annotations + +- `application-networking.k8s.aws/lattice-assigned-domain-name` + Represents a VPC Lattice generated domain name for the resource. This annotation will automatically set + when a `HTTPRoute` is programmed and ready. + +## Example Configuration ### Example 1 @@ -113,5 +119,5 @@ In this example: --- This `HTTPRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure -and use the resource within the EKS Controller project. For in-depth details and specifications, you can refer to the +and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute). \ No newline at end of file diff --git a/docs/api-types/iam-auth-policy.md b/docs/api-types/iam-auth-policy.md index 6ddfedd8..80741132 100644 --- a/docs/api-types/iam-auth-policy.md +++ b/docs/api-types/iam-auth-policy.md @@ -11,7 +11,7 @@ An IAMAuthPolicy can be attached to a Gateway, HTTPRoute, or GRPCRoute. Please visit the [VPC Lattice Auth Policy documentation page](https://docs.aws.amazon.com/vpc-lattice/latest/ug/auth-policies.html) for more details about Auth Policies. -## Features +### Features - Attaching a policy to a Gateway results in an AuthPolicy being applied to the Gateway's associated VPC Lattice Service Network. diff --git a/docs/api-types/service.md b/docs/api-types/service.md index 6e010ffd..45db3df7 100644 --- a/docs/api-types/service.md +++ b/docs/api-types/service.md @@ -5,7 +5,7 @@ Kubernetes Services define a logical set of Pods and a policy by which to access them, often referred to as a microservice. The set of Pods targeted by a Service is determined by a `selector`. -### Service Key Features & Limitations: +### Service Key Features & Limitations **Features**: diff --git a/docs/api-types/target-group-policy.md b/docs/api-types/target-group-policy.md index 530650c7..1ebe9a08 100644 --- a/docs/api-types/target-group-policy.md +++ b/docs/api-types/target-group-policy.md @@ -21,7 +21,7 @@ The policy will not take effect if: These restrictions are not forced; for example, users may create a policy that targets a service that is not created yet. However, the policy will not take effect unless the target is valid. -**Limitations and Considerations** +### Limitations and Considerations - Attaching TargetGroupPolicy to a resource that is already referenced by a route will result in a replacement of VPC Lattice TargetGroup resource, except for health check updates. diff --git a/docs/api-types/vpc-association-policy.md b/docs/api-types/vpc-association-policy.md index f29e77d2..8a5b09c3 100644 --- a/docs/api-types/vpc-association-policy.md +++ b/docs/api-types/vpc-association-policy.md @@ -5,13 +5,13 @@ VpcAssociationPolicy is a Custom Resource Definition (CRD) that can be attached to a Gateway to define the configuration of the ServiceNetworkVpcAssociation between the Gateway's associated VPC Lattice Service Network and the cluster VPC. -## Recommended Security Group Inbound Rules +### Recommended Security Group Inbound Rules | Source | Protocol | Port Range | Comment | |---------------------------------------------------------|-----------------------------------------------------|-------------------------------------------------|-----------------------------------------------------------| | Kubernetes cluster VPC CIDR or security group reference | Protocols defined in the gateway's listener section | Ports defined in the gateway's listener section | Allow inbound traffic from current cluster vpc to gateway | -## Limitations and Considerations +### Limitations and Considerations When attaching a VpcAssociationPolicy to a resource, the following restrictions apply: @@ -24,7 +24,7 @@ The security group will not take effect if: * The `associateWithVpc` field is set to false. -### WARNING +### :warning: Removing Security Groups The VPC Lattice `UpdateServiceNetworkVpcAssociation` API cannot be used to remove all security groups. If you have a VpcAssociationPolicy attached to a gateway that already has security groups applied, updating the VpcAssociationPolicy with empty security group ids or deleting the VpcAssociationPolicy will NOT remove the security groups from the gateway. diff --git a/docs/concepts/grpc.md b/docs/concepts/grpc.md index 6a173adf..25cfd603 100644 --- a/docs/concepts/grpc.md +++ b/docs/concepts/grpc.md @@ -121,7 +121,3 @@ Greeting: Hello world ``` This confirms that our gRPC request was successfully routed through VPC Lattice and processed by our `greeter-grpc-server`. - ---- - -We hope this guide helps you get started with using `GRPCRoute` in the EKS Controller project! \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md index 06a7e332..c09527ca 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,24 +1,16 @@ # Frequently Asked Questions (FAQ) -* **Q: How can I get involved with AWS Gateway API Controller?** - +* **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: Where can I find AWS Gateway API Controller releases?** - +* **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?** - +* **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?** - +* **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. - + 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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index aeeb817c..76b0d43c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,8 +20,9 @@ nav: - API Specification: api-reference.md - API Reference: - AccessLogPolicy: api-types/access-log-policy.md + - Gateway: api-types/gateway.md - GRPCRoute: api-types/grpc-route.md - - HttpRoute: api-types/http-route.md + - HTTPRoute: api-types/http-route.md - IAMAuthPolicy: api-types/iam-auth-policy.md - Service: api-types/service.md - TargetGroupPolicy: api-types/target-group-policy.md From a22d3528264834e7f2620ccff87db20848c4939b Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Fri, 17 Nov 2023 07:56:24 -0800 Subject: [PATCH 2/2] Fix hyphen --- docs/faq.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index c09527ca..fd08db4c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,15 +1,15 @@ # Frequently Asked Questions (FAQ) -* **Q: How can I get involved with AWS Gateway API Controller?** +- **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: Where can I find AWS Gateway API Controller releases?** +- **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?** +- **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?** +- **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.