Skip to content

Commit 61689bc

Browse files
author
Doyoon Kim
authored
Update Gateway docs and fix styles (#518)
* Update Gateway resource docs and fix markdown styles
1 parent 42cbb61 commit 61689bc

File tree

10 files changed

+104
-32
lines changed

10 files changed

+104
-32
lines changed

‎docs/api-types/gateway.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Gateway API Reference
2+
3+
## Introduction
4+
5+
`Gateway` allows you to configure network traffic through AWS Gateway API Controller.
6+
When a Gateway is defined with `amazon-vpc-lattice` GatewayClass, the controller will watch for the gateway
7+
and the resources under them, creating required resources under Amazon VPC Lattice.
8+
9+
Internally, a Gateway points to a VPC Lattice [service network](https://docs.aws.amazon.com/vpc-lattice/latest/ug/service-networks.html).
10+
Service networks are identified by Gateway name (without namespace) - for example, a Gateway named `my-gateway`
11+
will point to a VPC Lattice service network `my-gateway`. If multiple Gateways share the same name, all of them
12+
will point to the same service network.
13+
14+
VPC Lattice service networks must be managed separately, as it is a broader concept that can cover resources
15+
outside the Kubernetes cluster. To create and manage a service network, you can either:
16+
17+
- Specify `DEFAULT_SERVICE_NETWORK` configuration option on the controller. This will make the controller
18+
to create a service network with such name, and associate the cluster VPC to it for you. This is suitable
19+
for simple use cases with single service network.
20+
- Manage service networks outside the cluster, using AWS Console, CDK, CloudFormation, etc. This is recommended
21+
for more advanced use cases that cover multiple clusters and VPCs.
22+
23+
Gateways with `amazon-vpc-lattice` GatewayClass do not create a single entrypoint to bind Listeners and Routes
24+
under them. Instead, each Route will have its own domain name assigned. To see an example of how domain names
25+
are assigned, please refer to our [Getting Started Guide](../guides/getstarted.md).
26+
27+
### Supported GatewayClass
28+
- `amazon-vpc-lattice`
29+
This is the default GatewayClass for managing traffic using Amazon VPC Lattice.
30+
31+
### Limitations
32+
- GatewayAddress status does not represent all accessible endpoints belong to a Gateway.
33+
Instead, you should check annotations of each Route.
34+
- Only `Terminate` is supported for TLS mode. TLSRoute is currently not supported.
35+
- TLS certificate cannot be provided through `certificateRefs` field by `Secret` resource.
36+
Instead, you can create an ACM certificate and put its ARN to the `options` field.
37+
38+
## Example Configuration
39+
40+
Here is a sample configuration that demonstrates how to set up a `Gateway`:
41+
42+
```yaml
43+
apiVersion: gateway.networking.k8s.io/v1beta1
44+
kind: Gateway
45+
metadata:
46+
name: my-hotel
47+
spec:
48+
gatewayClassName: amazon-vpc-lattice
49+
listeners:
50+
- name: http
51+
protocol: HTTP
52+
port: 80
53+
- name: https
54+
protocol: HTTPS
55+
port: 443
56+
tls:
57+
mode: Terminate
58+
certificateRefs:
59+
- name: unused
60+
options:
61+
application-networking.k8s.aws/certificate-arn: <certificate-arn>
62+
```
63+
64+
The created Gateway will point to a VPC Lattice service network named `my-hotel`. Routes under this Gateway can have
65+
either `http` or `https` listener as a parent based on their desired protocol to use.
66+
67+
---
68+
69+
This `Gateway` documentation provides a detailed introduction, feature set, and a basic example of how to configure
70+
and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the
71+
official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway).

‎docs/api-types/grpc-route.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22

33
## Introduction
44

5-
With integration of the Gateway API, the EKS Controller project supports `GRPCRoute`.
5+
With integration of the Gateway API, AWS Gateway API Controller supports `GRPCRoute`.
66
This allows you to define and manage the routing of gRPC traffic within your Kubernetes cluster.
77

8-
### GRPCRoute Key Features & Limitations:
8+
### GRPCRoute Key Features & Limitations
99

1010
**Features**:
1111

@@ -25,7 +25,13 @@ This allows you to define and manage the routing of gRPC traffic within your Kub
2525
- **No Method Without Service**: Matching only by a gRPC method without specifying a service is not supported.
2626
- **Case Insensitivity**: All method matches are currently case-insensitive.
2727

28-
## Example Configuration:
28+
### Annotations
29+
30+
- `application-networking.k8s.aws/lattice-assigned-domain-name`
31+
Represents a VPC Lattice generated domain name for the resource. This annotation will automatically set
32+
when a `GRPCRoute` is programmed and ready.
33+
34+
## Example Configuration
2935

3036
Here is a sample configuration that demonstrates how to set up a `GRPCRoute` for a HelloWorld gRPC service:
3137

@@ -71,5 +77,5 @@ In this example:
7177
---
7278

7379
This `GRPCRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure
74-
and use the resource within the EKS Controller project. For in-depth details and specifications, you can refer to the
80+
and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the
7581
official [Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha2.GRPCRoute).

‎docs/api-types/http-route.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22

33
## Introduction
44

5-
With integration of the Gateway API, the EKS Controller project supports `HTTPRoute`.
5+
With integration of the Gateway API, AWS Gateway API Controller supports `HTTPRoute`.
66
This allows you to define and manage the routing of HTTP and HTTPS traffic within your Kubernetes cluster.
77

8-
### HTTPRoute Key Features & Limitations:
8+
### HTTPRoute Key Features & Limitations
99

1010
**Features**:
1111

@@ -24,7 +24,13 @@ This allows you to define and manage the routing of HTTP and HTTPS traffic withi
2424
- **Header Matches Limit**: A maximum of 5 header matches per rule is supported.
2525
- **Case Insensitivity**: All path matches are currently case-insensitive.
2626

27-
## Example Configuration:
27+
### Annotations
28+
29+
- `application-networking.k8s.aws/lattice-assigned-domain-name`
30+
Represents a VPC Lattice generated domain name for the resource. This annotation will automatically set
31+
when a `HTTPRoute` is programmed and ready.
32+
33+
## Example Configuration
2834

2935
### Example 1
3036

@@ -113,5 +119,5 @@ In this example:
113119
---
114120

115121
This `HTTPRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure
116-
and use the resource within the EKS Controller project. For in-depth details and specifications, you can refer to the
122+
and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the
117123
official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute).

‎docs/api-types/iam-auth-policy.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ An IAMAuthPolicy can be attached to a Gateway, HTTPRoute, or GRPCRoute.
1111
Please visit the [VPC Lattice Auth Policy documentation page](https://docs.aws.amazon.com/vpc-lattice/latest/ug/auth-policies.html)
1212
for more details about Auth Policies.
1313

14-
## Features
14+
### Features
1515

1616
- Attaching a policy to a Gateway results in an AuthPolicy being applied to the Gateway's associated
1717
VPC Lattice Service Network.

‎docs/api-types/service.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Kubernetes Services define a logical set of Pods and a policy by which to access them, often referred to as a
66
microservice. The set of Pods targeted by a Service is determined by a `selector`.
77

8-
### Service Key Features & Limitations:
8+
### Service Key Features & Limitations
99

1010
**Features**:
1111

‎docs/api-types/target-group-policy.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The policy will not take effect if:
2121
These restrictions are not forced; for example, users may create a policy that targets a service that is not created yet.
2222
However, the policy will not take effect unless the target is valid.
2323

24-
**Limitations and Considerations**
24+
### Limitations and Considerations
2525

2626
- Attaching TargetGroupPolicy to a resource that is already referenced by a route will result in a replacement
2727
of VPC Lattice TargetGroup resource, except for health check updates.

‎docs/api-types/vpc-association-policy.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@
55
VpcAssociationPolicy is a Custom Resource Definition (CRD) that can be attached to a Gateway to define the configuration
66
of the ServiceNetworkVpcAssociation between the Gateway's associated VPC Lattice Service Network and the cluster VPC.
77

8-
## Recommended Security Group Inbound Rules
8+
### Recommended Security Group Inbound Rules
99

1010
| Source | Protocol | Port Range | Comment |
1111
|---------------------------------------------------------|-----------------------------------------------------|-------------------------------------------------|-----------------------------------------------------------|
1212
| 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 |
1313

14-
## Limitations and Considerations
14+
### Limitations and Considerations
1515

1616
When attaching a VpcAssociationPolicy to a resource, the following restrictions apply:
1717

@@ -24,7 +24,7 @@ The security group will not take effect if:
2424
* The `associateWithVpc` field is set to false.
2525

2626

27-
### WARNING
27+
### :warning: Removing Security Groups
2828

2929
The VPC Lattice `UpdateServiceNetworkVpcAssociation` API cannot be used to remove all security groups.
3030
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.

‎docs/concepts/grpc.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,3 @@ Greeting: Hello world
121121
```
122122
123123
This confirms that our gRPC request was successfully routed through VPC Lattice and processed by our `greeter-grpc-server`.
124-
125-
---
126-
127-
We hope this guide helps you get started with using `GRPCRoute` in the EKS Controller project!

‎docs/faq.md‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,16 @@
11
# Frequently Asked Questions (FAQ)
22

3-
* **Q: How can I get involved with AWS Gateway API Controller?**
4-
3+
- **Q: How can I get involved with AWS Gateway API Controller?**
54
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).
65

7-
8-
* **Q: Where can I find AWS Gateway API Controller releases?**
9-
6+
- **Q: Where can I find AWS Gateway API Controller releases?**
107
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.
118

12-
13-
* **Q: Which EKS CNI versions are supported?**
14-
9+
- **Q: Which EKS CNI versions are supported?**
1510
A: Your AWS VPC CNI must be v1.8.0 or later to work with VPC Lattice.
1611

17-
18-
* **Q: Which versions of Gateway API are supported?**
19-
12+
- **Q: Which versions of Gateway API are supported?**
2013
A: AWS Gateway API Controller supports Gateway API CRD bundle versions between v0.6.1 and v1.0.0.
2114
The controller does not reject other versions, but will provide "best effort support" to it.
22-
Not all features of Gateway API are supported - for detailed features and limitation, please refer to individual API references.
23-
15+
Not all features of Gateway API are supported - for detailed features and limitation, please refer to individual API references.
2416
By default, Gateway API v0.6.1 CRD bundle is included in the helm chart.

‎mkdocs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,9 @@ nav:
2020
- API Specification: api-reference.md
2121
- API Reference:
2222
- AccessLogPolicy: api-types/access-log-policy.md
23+
- Gateway: api-types/gateway.md
2324
- GRPCRoute: api-types/grpc-route.md
24-
- HttpRoute: api-types/http-route.md
25+
- HTTPRoute: api-types/http-route.md
2526
- IAMAuthPolicy: api-types/iam-auth-policy.md
2627
- Service: api-types/service.md
2728
- TargetGroupPolicy: api-types/target-group-policy.md

0 commit comments

Comments
 (0)