Skip to content

Commit 07701cc

Browse files
author
Doyoon Kim
authored
Add TargetGroupPolicy docs (#361)
1 parent 242241f commit 07701cc

File tree

3 files changed

+125
-0
lines changed

3 files changed

+125
-0
lines changed

‎docs/configure/https.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,27 @@ spec:
9797
sectionName: tls-with-custom-cert # Specify custom-defined certificate
9898
...
9999
```
100+
101+
### Enabling TLS connection on the backend
102+
103+
Currently TLS Passthrough mode is not supported in the controller, but it allows TLS re-encryption to support backends that only allow TLS connections.
104+
To handle this use case, you need to configure your service to receive HTTPS traffic instead:
105+
106+
```
107+
apiVersion: application-networking.k8s.aws/v1alpha1
108+
kind: TargetGroupPolicy
109+
metadata:
110+
name: test-policy
111+
spec:
112+
targetRef:
113+
group: ""
114+
kind: Service
115+
name: my-parking-service # Put service name here
116+
protocol: HTTPS
117+
protocolVersion: HTTP1
118+
```
119+
120+
This will create VPC Lattice TargetGroup with HTTPS protocol option, which can receive TLS traffic.
121+
Note that certificate validation is not supported.
122+
123+
For more details, please refer to [TargetGroupPolicy API reference](../reference/target-group-policy.md).

‎docs/developer.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ $kubectl apply -f config/crds/bases/k8s-gateway-v0.6.1.yaml
6969
kubectl apply -f config/crds/bases/multicluster.x-k8s.io_serviceexports.yaml
7070
kubectl apply -f config/crds/bases/multicluster.x-k8s.io_serviceimports.yaml
7171
kubectl apply -f config/crds/bases/externaldns.k8s.io_dnsendpoints.yaml
72+
kubectl apply -f config/crds/bases/application-networking.k8s.aws_targetgrouppolicies.yaml
7273
kubectl apply -f examples/gatewayclass.yaml
7374
```
7475

‎docs/reference/target-group-policy.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# TargetGroupPolicy API Reference
2+
3+
## TargetGroupPolicy
4+
5+
By default, AWS Gateway API Controller assumes plaintext HTTP/1 traffic for backend Kubernetes resources.
6+
TargetGroupPolicy is a CRD that can be attached to a Service, which allows the users to define protocol and
7+
health check configurations of those backend resources.
8+
9+
When attaching a policy to a resource, the following restrictions apply:
10+
11+
* A policy can be only attached to `Service` resources.
12+
* The attached resource can only be `backendRef` of `HTTPRoute` and `GRPCRoute`.
13+
* The attached resource should exist in the same namespace as the policy resource.
14+
15+
The policy will not take effect if:
16+
17+
* The resource does not exist
18+
* The resource is not referenced by any route
19+
* The resource is referenced by a route of unsupported type
20+
21+
These restrictions are not forced; for example, users may create a policy that targets a service that is not created yet.
22+
However, the policy will not take effect unless the target is valid.
23+
24+
### Notes
25+
26+
* Attaching TargetGroupPolicy to a resource that is already referenced by a route will result in a replacement
27+
of VPC Lattice TargetGroup resource, except for health check updates.
28+
* Removing TargetGroupPolicy of a resource will roll back protocol configuration to default setting. (HTTP1/HTTP plaintext)
29+
30+
|Field |Description |
31+
|--- |--- |
32+
|`apiVersion` *string* |``application-networking.k8s.aws/v1alpha1`` |
33+
|`kind` *string* |``TargetGroupPolicy`` |
34+
|`metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta) |Kubernetes metadata for the resource. |
35+
|`spec` *TargetGroupPolicySpec* |Defines the desired state of TargetGroupPolicy. |
36+
37+
## TargetGroupPolicySpec
38+
39+
Appears on: TargetGroupPolicy
40+
41+
TargetGroupPolicySpec defines the desired state of TargetGroupPolicy.
42+
43+
Updates to this configuration result in a replacement of VPC Lattice TargetGroup resource, except for `healthCheck` field.
44+
45+
|Field | Description|
46+
|--- |---|
47+
|`targetRef` *[PolicyTargetReference](https://gateway-api.sigs.k8s.io/geps/gep-713/#policy-targetref-api)* | TargetRef points to the kubernetes `Service` resource that will have this policy attached. This field is following the guidelines of Kubernetes Gateway API policy attachment. |
48+
|`protocol` *string* | (Optional) The protocol to use for routing traffic to the targets. Supported values are `HTTP` (default) and `HTTPS`.<br/> Changes to this value results in a replacement of VPC Lattice target group. |
49+
|`protocolVersion` *string* | (Optional) The protocol version to use. Supported values are `HTTP1` (default) and `HTTP2`. When a policy is behind GRPCRoute, this field value will be ignored as GRPC is only supported through HTTP/2.<br/> Changes to this value results in a replacement of VPC Lattice target group. |
50+
|`healthCheck` *HealthCheckConfig* | (Optional) The health check configuration.<br/> Changes to this value will update VPC Lattice resource in place. |
51+
52+
## HealthCheckConfig
53+
54+
Appears on: TargetGroupPolicySpec
55+
56+
HealthCheckConfig defines health check configuration for given VPC Lattice target group. For the detailed explanation and supported values, please refer to [VPC Lattice documentation](https://docs.aws.amazon.com/vpc-lattice/latest/ug/target-group-health-checks.html) on health checks.
57+
58+
|Field |Description |
59+
|--- |--- |
60+
|`enabled` *boolean* |(Optional) Indicates whether health checking is enabled. |
61+
|`intervalSeconds` *integer* |(Optional) The approximate amount of time, in seconds, between health checks of an individual target. |
62+
|`timeoutSeconds` *integer* |(Optional) The amount of time, in seconds, to wait before reporting a target as unhealthy. |
63+
|`healthyThresholdCount` *integer* |(Optional) The number of consecutive successful health checks required before considering an unhealthy target healthy. |
64+
|`statusMatch` *string* |(Optional) A regular expression to match HTTP status codes when checking for a successful response from a target. |
65+
|`path` *string* |(Optional) The destination for health checks on the targets. |
66+
|`port` *integer* |(Optional) The port used when performing health checks on targets. If not specified, health check defaults to the port that a target receives traffic on. |
67+
|`protocol` *string* |(Optional) The protocol used when performing health checks on targets. |
68+
|`protocolVersion` *string* |(Optional) The protocol version used when performing health checks on targets. Defaults to HTTP/1. |
69+
|`unhealthyThresholdCount` *integer* |(Optional) The number of consecutive failed health checks required before considering a target unhealthy. |
70+
71+
## Example Configuration
72+
73+
This will enable TLS traffic between the gateway and Kubernetes service, with customized health check configuration.
74+
75+
Note that the TLS traffic is always terminated at the gateway, so it will be re-encrypted in this case. The gateway does not perform any certificate validations to the certificate on targets.
76+
77+
```
78+
apiVersion: application-networking.k8s.aws/v1alpha1
79+
kind: TargetGroupPolicy
80+
metadata:
81+
name: test-policy
82+
spec:
83+
targetRef:
84+
group: ""
85+
kind: Service
86+
name: my-parking-service
87+
protocol: HTTPS
88+
protocolVersion: HTTP1
89+
healthCheck:
90+
enabled: true
91+
intervalSeconds: 5
92+
timeoutSeconds: 1
93+
healthyThresholdCount: 3
94+
unhealthyThresholdcount: 2
95+
path: "/healthcheck"
96+
port: 80
97+
protocol: HTTP
98+
protocolVersion: HTTP
99+
statusMatch: "200"
100+
```

0 commit comments

Comments
 (0)