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..c5be6489 --- /dev/null +++ b/docs/api-types/service-export.md @@ -0,0 +1,39 @@ +# ServiceExport API Reference + +## Introduction + +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. + +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. + +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). + +### 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..01679c48 --- /dev/null +++ b/docs/api-types/service-import.md @@ -0,0 +1,55 @@ +# 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. + +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). + +### 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` + (Optional) When specified, the controller will only find target groups exported from the cluster. +* `application-networking.k8s.aws/aws-vpc` + (Optional) When specified, the controller will only find target groups exported from the cluster with the provided VPC ID. + +## 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: