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..fd08db4c 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