From 24510b673795d5b1dfca44952b33e1fd411ce026 Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Wed, 29 Nov 2023 12:14:23 -0800 Subject: [PATCH 1/3] Add service export/import documentations --- docs/api-types/grpc-route.md | 2 +- docs/api-types/http-route.md | 2 +- docs/api-types/service-export.md | 38 ++++++++++++++++++++++ docs/api-types/service-import.md | 54 ++++++++++++++++++++++++++++++++ mkdocs.yml | 2 ++ 5 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 docs/api-types/service-export.md create mode 100644 docs/api-types/service-import.md diff --git a/docs/api-types/grpc-route.md b/docs/api-types/grpc-route.md index 5cdaeea9..7b9c10a4 100644 --- a/docs/api-types/grpc-route.md +++ b/docs/api-types/grpc-route.md @@ -27,7 +27,7 @@ This allows you to define and manage the routing of gRPC traffic within your Kub ### Annotations -- `application-networking.k8s.aws/lattice-assigned-domain-name` +- `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. diff --git a/docs/api-types/http-route.md b/docs/api-types/http-route.md index 89124120..9bc303ad 100644 --- a/docs/api-types/http-route.md +++ b/docs/api-types/http-route.md @@ -26,7 +26,7 @@ This allows you to define and manage the routing of HTTP and HTTPS traffic withi ### Annotations -- `application-networking.k8s.aws/lattice-assigned-domain-name` +- `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. diff --git a/docs/api-types/service-export.md b/docs/api-types/service-export.md new file mode 100644 index 00000000..866e5c15 --- /dev/null +++ b/docs/api-types/service-export.md @@ -0,0 +1,38 @@ +# ServiceExport API Reference + +## Introduction + +In AWS Gateway API Controller, `ServiceExport` is the way of enabling a Service for multi-cluster traffic setup. +Once a Service is exported, other clusters can refer to it using [`ServiceImport`](service-import.md) resource. + +ServiceExport is a term originated from Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/); +but AWS Gateway API Controller uses its own version of ServiceExport resource with a certain set of features. + +Internally, creating a ServiceExport creates a VPC Lattice [target group](https://docs.aws.amazon.com/vpc-lattice/latest/ug/target-groups.html). +You can take advantage of this by using the created target group in VPC Lattice setup outside Kubernetes. + +For more multi-cluster use cases and detailed explanation, please refer to [our recommended multi-cluster architecture](../guides/multi-cluster.md). + +### Limitations +* The exported Service can only be used in HTTPRoutes. GRPCRoute is currently not supported. +* Limited to one ServiceExport per Service. If you need multiple exports representing each port, + you should create multiple Service-ServiceExport pairs. + +### Annotations + +* `application-networking.k8s.aws/port` + Represents which port of the exported Service will be used. + When a comma-separated list of ports is provided, the traffic will be distributed to all ports in the list. + +## Example Configuration + +The following yaml will create a ServiceExport for a Service named `service-1`: +```yaml +apiVersion: application-networking.k8s.aws/v1alpha1 +kind: ServiceExport +metadata: + name: service-1 + annotations: + application-networking.k8s.aws/port: "9200" +spec: {} +``` diff --git a/docs/api-types/service-import.md b/docs/api-types/service-import.md new file mode 100644 index 00000000..426233a6 --- /dev/null +++ b/docs/api-types/service-import.md @@ -0,0 +1,54 @@ +# ServiceImport API Reference + +## Introduction + +`ServiceImport` is a resource referring to a Service outside the cluster, paired with [`ServiceExport`](service-export.md) +resource defined in the other clusters. Just like Services, ServiceImports can be a backend reference of HTTPRoutes. +Along with the cluster's own Services (and ServiceImports from even more clusters), you can distribute the traffic +across multiple VPCs and clusters. + +ServiceImport is a term originated from Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/); +but AWS Gateway API Controller uses its own version of ServiceImport resource with a certain set of features. + +For more multi-cluster use cases, please refer to [our recommended multi-cluster architecture](../guides/multi-cluster.md). + +### Limitations +* ServiceImport shares the limitations of [ServiceExport](service-export.md). +* The controller only supports ServiceImport through HTTPRoute; sending traffic directly is not supported. +* BackendRef ports pointing to ServiceImport is not respected. Use [port annotation](service-export.md#annotations) of ServiceExport instead. + +### Annotations +* `application-networking.k8s.aws/aws-eks-cluster-name` + Indicates the cluster name owning the exported service. +* `application-networking.k8s.aws/aws-vpc` + Indicates the VPC ID owning the exported service. + +## Example Configuration + +The following yaml imports `service-1` exported from the designated cluster. +```yaml +apiVersion: application-networking.k8s.aws/v1alpha1 +kind: ServiceImport +metadata: + name: service-1 + annotations: + application-networking.k8s.aws/aws-eks-cluster-name: "service-1-owner-cluster" + application-networking.k8s.aws/aws-vpc: "service-1-owner-vpc-id" +spec: {} +``` + +The following example HTTPRoute directs traffic to the above ServiceImport. +```yaml +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: my-route +spec: + parentRefs: + - name: my-gateway + sectionName: http + rules: + - backendRefs: + - name: service-1 + kind: ServiceImport +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index c5615836..2336ba4e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,8 @@ nav: - HTTPRoute: api-types/http-route.md - IAMAuthPolicy: api-types/iam-auth-policy.md - Service: api-types/service.md + - ServiceExport: api-types/service-export.md + - ServiceImport: api-types/service-import.md - TargetGroupPolicy: api-types/target-group-policy.md - VpcAssociationPolicy: api-types/vpc-association-policy.md - Contributing: From c550b85027a4308574006bb70ca4c3f0b338def0 Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Wed, 29 Nov 2023 16:33:19 -0800 Subject: [PATCH 2/3] Address PR comments --- docs/api-types/service-export.md | 13 +++++++------ docs/api-types/service-import.md | 21 +++++++++++++-------- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/api-types/service-export.md b/docs/api-types/service-export.md index 866e5c15..c5be6489 100644 --- a/docs/api-types/service-export.md +++ b/docs/api-types/service-export.md @@ -2,14 +2,15 @@ ## Introduction -In AWS Gateway API Controller, `ServiceExport` is the way of enabling a Service for multi-cluster traffic setup. -Once a Service is exported, other clusters can refer to it using [`ServiceImport`](service-import.md) resource. +In AWS Gateway API Controller, `ServiceExport` enables a Service for multi-cluster traffic setup. +Clusters can import the exported service with [`ServiceImport`](service-import.md) resource. -ServiceExport is a term originated from Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/); -but AWS Gateway API Controller uses its own version of ServiceExport resource with a certain set of features. +Internally, creating a ServiceExport creates a standalone VPC Lattice [target group](https://docs.aws.amazon.com/vpc-lattice/latest/ug/target-groups.html). +Even without ServiceImports, creating ServiceExports can be useful in case you only need the target groups created; +for example, using target groups in the VPC Lattice setup outside Kubernetes. -Internally, creating a ServiceExport creates a VPC Lattice [target group](https://docs.aws.amazon.com/vpc-lattice/latest/ug/target-groups.html). -You can take advantage of this by using the created target group in VPC Lattice setup outside Kubernetes. +Note that ServiceExport is not the implementation of Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/); +instead AWS Gateway API Controller uses its own version of the resource for the purpose of Gateway API integration. For more multi-cluster use cases and detailed explanation, please refer to [our recommended multi-cluster architecture](../guides/multi-cluster.md). diff --git a/docs/api-types/service-import.md b/docs/api-types/service-import.md index 426233a6..fb7f50df 100644 --- a/docs/api-types/service-import.md +++ b/docs/api-types/service-import.md @@ -2,13 +2,18 @@ ## Introduction -`ServiceImport` is a resource referring to a Service outside the cluster, paired with [`ServiceExport`](service-export.md) -resource defined in the other clusters. Just like Services, ServiceImports can be a backend reference of HTTPRoutes. -Along with the cluster's own Services (and ServiceImports from even more clusters), you can distribute the traffic -across multiple VPCs and clusters. +`ServiceImport` is a resource referring to a Service outside the cluster. The primary use-case of ServiceImport is +to pair with [`ServiceExport`](service-export.md) resource, defined in the other clusters. -ServiceImport is a term originated from Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/); -but AWS Gateway API Controller uses its own version of ServiceImport resource with a certain set of features. +Just like Services, ServiceImports can be a backend reference of HTTPRoutes. Along with the cluster's own Services +(and ServiceImports from even more clusters), you can distribute the traffic across multiple VPCs and clusters. + +Internally, `ServiceImport` is simply a reference to a VPC Lattice target group. Even if a target group is not created +by ServiceExport, the controller can still recognize it as long as its name matches the ServiceImport. +This way, you can also send traffic to target groups with EC2 or Lambda targets. + +Note that ServiceImport is not the implementation of Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/); +instead AWS Gateway API Controller uses its own version of the resource for the purpose of Gateway API integration. For more multi-cluster use cases, please refer to [our recommended multi-cluster architecture](../guides/multi-cluster.md). @@ -19,9 +24,9 @@ For more multi-cluster use cases, please refer to [our recommended multi-cluster ### Annotations * `application-networking.k8s.aws/aws-eks-cluster-name` - Indicates the cluster name owning the exported service. + (Optional) When specified, the controller will only find target groups exported from the cluster. * `application-networking.k8s.aws/aws-vpc` - Indicates the VPC ID owning the exported service. + (Optional) When specified, the controller will only find target groups exported from the cluster with the provided VPC ID. ## Example Configuration From 02de3471df33be423848fc81d516b2112860371f Mon Sep 17 00:00:00 2001 From: Doyoon Kim Date: Wed, 29 Nov 2023 16:55:22 -0800 Subject: [PATCH 3/3] Rollback service import introduction --- docs/api-types/service-import.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/api-types/service-import.md b/docs/api-types/service-import.md index fb7f50df..01679c48 100644 --- a/docs/api-types/service-import.md +++ b/docs/api-types/service-import.md @@ -2,16 +2,12 @@ ## Introduction -`ServiceImport` is a resource referring to a Service outside the cluster. The primary use-case of ServiceImport is -to pair with [`ServiceExport`](service-export.md) resource, defined in the other clusters. +`ServiceImport` is a resource referring to a Service outside the cluster, paired with [`ServiceExport`](service-export.md) +resource defined in the other clusters. Just like Services, ServiceImports can be a backend reference of HTTPRoutes. Along with the cluster's own Services (and ServiceImports from even more clusters), you can distribute the traffic across multiple VPCs and clusters. -Internally, `ServiceImport` is simply a reference to a VPC Lattice target group. Even if a target group is not created -by ServiceExport, the controller can still recognize it as long as its name matches the ServiceImport. -This way, you can also send traffic to target groups with EC2 or Lambda targets. - Note that ServiceImport is not the implementation of Kubernetes [Multicluster Service APIs](https://multicluster.sigs.k8s.io/concepts/multicluster-services-api/); instead AWS Gateway API Controller uses its own version of the resource for the purpose of Gateway API integration.