Add service export/import documentations #551
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
Comment on lines
+8
to
+10
Contributor
There was a problem hiding this comment. A second thought on it, I dont think we should advertise TG creation with ServiceExports, because TG now "ephemeral" with random suffix. It will break use of TG outside of controller.
Contributor
Author
There was a problem hiding this comment. Target groups are not ephemeral, especially when created from ServiceExports. The only exception is when users intentionally change immutable fields, but that happens regardless of random suffix anyways. |
||
|
|
||
| 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. | ||
|
Contributor
There was a problem hiding this comment. What this mean? Sounds like we support multiple ServiceExports per Service?
Contributor
Author
There was a problem hiding this comment. we don't, we need as many services as serviceexport. |
||
|
|
||
| ### 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" | ||
|
Contributor
There was a problem hiding this comment. Can we show a list of comma-separated port in here, e.g.,
Contributor
Author
There was a problem hiding this comment. There is almost no chance that users will need comma-separated list behavior here, tbh I don't like that feature and I think it only causes confusion. I don't want to highlight that use case as an example. |
||
| spec: {} | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) | ||
mikhail-aws marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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. | ||
|
|
||
|
Contributor
There was a problem hiding this comment. Should we mention these 2 annotations are optional? The controller is able to automatically identify cluster name and vpc if not specified?
Contributor
Author
There was a problem hiding this comment. I can update this. btw the fields are optional but it is not like the controller automatically identifies them. They are like an additional sanity check when finding exported TG |
||
| ## 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 | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: trailing space
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is actually intended to create a line break. Seems like backslash doesn't work in mkdocs so this is an alternative to it