From 2dea7b09b2b9b57600b3b4724fc6633d8f79bcd7 Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Mon, 28 Aug 2023 08:05:25 -0700 Subject: [PATCH 1/4] Add TargetGroupPolicy docs --- docs/configure/https.md | 24 +++++++ docs/reference/target-group-policy.md | 94 +++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/reference/target-group-policy.md diff --git a/docs/configure/https.md b/docs/configure/https.md index b8856bac..495a2de5 100644 --- a/docs/configure/https.md +++ b/docs/configure/https.md @@ -97,3 +97,27 @@ spec: sectionName: tls-with-custom-cert # Specify custom-defined certificate ... ``` + +### Enabling TLS connection on the backend + +Currently TLS Passthrough mode is not supported in the controller, but it allows TLS re-encryption to support backends that only allow TLS connections. +To handle this use case, you need to configure your service to receive HTTPS traffic instead: + +``` +apiVersion: application-networking.k8s.aws/v1alpha1 +kind: TargetGroupPolicy +metadata: + name: test-policy +spec: + targetRef: + group: "" + kind: Service + name: my-parking-service # Put service name here + protocol: HTTP + protocolVersion: HTTPS +``` + +This will create VPC Lattice TargetGroup with HTTPS protocol option, which can receive TLS traffic. +Note that certificate validation is not supported. + +For more details, please refer to [TargetGroupPolicy API reference](../reference/target-group-policy.md). \ No newline at end of file diff --git a/docs/reference/target-group-policy.md b/docs/reference/target-group-policy.md new file mode 100644 index 00000000..c42a33a9 --- /dev/null +++ b/docs/reference/target-group-policy.md @@ -0,0 +1,94 @@ +# TargetGroupPolicy API Reference + +## TargetGroupPolicy + +By default, AWS Gateway API Controller assumes plaintext HTTP/1 traffic for backend Kubernetes resources. +TargetGroupPolicy is a CRD that can be attached to a Service, which allows the users to define protocol and +health check configurations of those backend resources. + +When attaching a policy to a resource, the following restrictions apply: + +* A policy can be only attached to `Service` resources. +* The attached resource can only be `backendRef` of `HTTPRoute` and `GRPCRoute`. +* The attached resource should exist in the same namespace as the policy resource. + +The policy will not take effect if: + +* The resource does not exist +* The resource is not referenced by any route +* The resource is referenced by a route of unsupported type + +Attaching TargetGroupPolicy to a resource that is already referenced by a route may result in a replacement +of VPC Lattice TargetGroup resource. + +|Field |Description | +|--- |--- | +|`apiVersion` *string* |``application-networking.k8s.aws/v1alpha1`` | +|`kind` *string* |``TargetGroupPolicy`` | +|`metadata` [*ObjectMeta*](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta) |Kubernetes metadata for the resource. | +|`spec` *TargetGroupPolicySpec* |Defines the desired state of TargetGroupPolicy. | + +## TargetGroupPolicySpec + +Appears on: TargetGroupPolicy + +TargetGroupPolicySpec defines the desired state of TargetGroupPolicy. + +Updates to certain fields of this configuration result in a replacement of VPC Lattice TargetGroup resource. + +|Field | Description| +|--- |---| +|`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. | +|`protocol` *string* | (Optional) The protocol to use for routing traffic to the targets. Supported values are `HTTP` (default) and `HTTPS`.
Changes to this value results in a replacement of VPC Lattice target group. | +|`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.
Changes to this value results in a replacement of VPC Lattice target group. | +|`healthCheck` *HealthCheckConfig* | (Optional) The health check configuration.
Changes to this value will update VPC Lattice resource in place. | + +## HealthCheckConfig + +Appears on: TargetGroupPolicySpec + +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. + +|Field |Description | +|--- |--- | +|`enabled` *boolean* |(Optional) Indicates whether health checking is enabled. | +|`intervalSeconds` *integer* |(Optional) The approximate amount of time, in seconds, between health checks of an individual target. | +|`timeoutSeconds` *integer* |(Optional) The amount of time, in seconds, to wait before reporting a target as unhealthy. | +|`healthyThresholdCount` *integer* |(Optional) The number of consecutive successful health checks required before considering an unhealthy target healthy. | +|`statusMatch` *string* |(Optional) A regular expression to match HTTP status codes when checking for a successful response from a target. | +|`path` *string* |(Optional) The destination for health checks on the targets. | +|`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. | +|`protocol` *string* |(Optional) The protocol used when performing health checks on targets. | +|`protocolVersion` *string* |(Optional) The protocol version used when performing health checks on targets. Defaults to HTTP/1. | +|`unhealthyThresholdCount` *integer* |(Optional) The number of consecutive failed health checks required before considering a target unhealthy. | + +## Example Configuration + +This will enable TLS traffic between the gateway and Kubernetes service, with customized health check configuration. + +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. + +``` +apiVersion: application-networking.k8s.aws/v1alpha1 +kind: TargetGroupPolicy +metadata: + name: test-policy +spec: + targetRef: + group: "" + kind: Service + name: my-parking-service + protocol: HTTPS + protocolVersion: HTTP1 + healthCheck: + enabled: true + intervalSeconds: 5 + timeoutSeconds: 1 + healthyThresholdCount: 3 + unhealthyThresholdcount: 2 + path: "/healthcheck" + port: 80 + protocol: HTTP + protocolVersion: HTTP + statusMatch: "200" +``` From 048f87860f8022128725d9e69db77df1e594ced3 Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Mon, 28 Aug 2023 08:53:41 -0700 Subject: [PATCH 2/4] Update dev instruction --- docs/developer.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developer.md b/docs/developer.md index ee10923b..fab4e77e 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -69,6 +69,7 @@ $kubectl apply -f config/crds/bases/k8s-gateway-v0.6.1.yaml kubectl apply -f config/crds/bases/multicluster.x-k8s.io_serviceexports.yaml kubectl apply -f config/crds/bases/multicluster.x-k8s.io_serviceimports.yaml kubectl apply -f config/crds/bases/externaldns.k8s.io_dnsendpoints.yaml +kubectl apply -f config/crds/bases/application-networking.k8s.aws_targetgrouppolicies.yaml kubectl apply -f examples/gatewayclass.yaml ``` From d99057db9e0a8aeec5c0461518863e2731066a9a Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Mon, 28 Aug 2023 12:00:03 -0700 Subject: [PATCH 3/4] Clarify restrictions on TGP --- docs/reference/target-group-policy.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/reference/target-group-policy.md b/docs/reference/target-group-policy.md index c42a33a9..1dd760c7 100644 --- a/docs/reference/target-group-policy.md +++ b/docs/reference/target-group-policy.md @@ -18,8 +18,14 @@ The policy will not take effect if: * The resource is not referenced by any route * The resource is referenced by a route of unsupported type -Attaching TargetGroupPolicy to a resource that is already referenced by a route may result in a replacement +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. + +### Notes + +* Attaching TargetGroupPolicy to a resource that is already referenced by a route may result in a replacement of VPC Lattice TargetGroup resource. +* Removing TargetGroupPolicy of a resource will roll back protocols to default setting (HTTP1/HTTP plaintext) |Field |Description | |--- |--- | From 57238f2c07bea42c0c781a22e0aed38fb92b6414 Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Mon, 28 Aug 2023 13:06:53 -0700 Subject: [PATCH 4/4] Address comments --- docs/configure/https.md | 4 ++-- docs/reference/target-group-policy.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/configure/https.md b/docs/configure/https.md index 495a2de5..175cc46c 100644 --- a/docs/configure/https.md +++ b/docs/configure/https.md @@ -113,8 +113,8 @@ spec: group: "" kind: Service name: my-parking-service # Put service name here - protocol: HTTP - protocolVersion: HTTPS + protocol: HTTPS + protocolVersion: HTTP1 ``` This will create VPC Lattice TargetGroup with HTTPS protocol option, which can receive TLS traffic. diff --git a/docs/reference/target-group-policy.md b/docs/reference/target-group-policy.md index 1dd760c7..3a1de714 100644 --- a/docs/reference/target-group-policy.md +++ b/docs/reference/target-group-policy.md @@ -23,9 +23,9 @@ However, the policy will not take effect unless the target is valid. ### Notes -* Attaching TargetGroupPolicy to a resource that is already referenced by a route may result in a replacement -of VPC Lattice TargetGroup resource. -* Removing TargetGroupPolicy of a resource will roll back protocols to default setting (HTTP1/HTTP plaintext) +* 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. +* Removing TargetGroupPolicy of a resource will roll back protocol configuration to default setting. (HTTP1/HTTP plaintext) |Field |Description | |--- |--- | @@ -40,7 +40,7 @@ Appears on: TargetGroupPolicy TargetGroupPolicySpec defines the desired state of TargetGroupPolicy. -Updates to certain fields of this configuration result in a replacement of VPC Lattice TargetGroup resource. +Updates to this configuration result in a replacement of VPC Lattice TargetGroup resource, except for `healthCheck` field. |Field | Description| |--- |---|