diff --git a/docs-src/images/api-model.png b/docs-src/images/api-model.png new file mode 100644 index 0000000000..8c3ed5d6f3 Binary files /dev/null and b/docs-src/images/api-model.png differ diff --git a/docs-src/index.md b/docs-src/index.md index 06c903b5d6..871e3e2552 100644 --- a/docs-src/index.md +++ b/docs-src/index.md @@ -1,35 +1,80 @@ # Introduction -Service APIs is the evolution of Kubernetes APIs that relate to `Services`, -e.g. `Ingress`. The project is part of Kubernetes, working under -[SIG-NETWORK][sig-network]. Use the following resources to learn more about -Service APIs. +Service APIs is an open source project, working under +[SIG-NETWORK][sig-network], that is evolving service networking APIs within +the Kubernetes ecosystem. Service APIs are the user interfaces you use to expose +your Kubernetes applications - Services, Ingress, and more. + +### What is the goal of Service APIs? + +Service APIs aims to improve these interfaces by making them +more expressive, extensible, and role-oriented while remaining as +generic routing APIs that have many implementations and broad industry support. + +Service APIs are really a collection of API resources - `Service`, +`GatewayClass`, `Gateway`, `HTTPRoute`, `TCPRoute`, and so on. These resources +are used together to model a wide variety of different networking use-cases. See +[API Concepts](concepts.md) to learn more about the API model. + +![Service API Model](./images/api-model.png) -[sig-network]: https://github.com/kubernetes/community/tree/master/sig-network +How do the Service APIs improve upon current standards like Ingress? -### Get started +- **More expressive** - They express more core functionality for things like +header-based matching, traffic weighting, and other capabilities that were only +possible through custom means in the Ingress spec. +- **More extensible** - They allow for custom resources to be linked at multiple +layers within its resources. This allows for more granular customization at the +appropriate places within the API structure. +- **Role oriented** - They are broken into API resources that map to the types +of roles that commonly deploy and configure load balancing. +- **Generic** - This isn't an improvement but rather something +that should stay the same. Just as Ingress is a universal specification with +[numerous implementations](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), +Service APIs are designed to be a portable specification for many +implementations. -To get started, please read through the [API overview](api-overview.md) and -[Security model](security-model.md). These documents give the necessary background -to understand the API and use-cases it targets. +Some other notable capabilities include … -### Guides +- **Shared Gateways** - They allow the sharing of load balancers and VIPs by +permitting independent Route resources to bind to the same Gateway. This allows +teams to share infrastructure safely without requiring direct coordination. +- **Typed backend references** - With typed backend references Routes can +reference Kubernetes Services, but also any kind of Kubernetes resource that is +designed to be a Gateway backend. +- **Cross-Namespace references** - Routes across different Namespaces can bind +to Gateways. This allows for shared networking infrastructure despite Namespace +segmentation for workloads. +- **Classes** - GatewayClasses formalize types of load balancing implementations. +These classes make it easy and explicit for users to understand what kind of +capabilities are available as a resource model itself. -Once you have a good understanding of the API at a higher-level, please -follow one of our [guides](guides.md) to dive deeper into different parts of -the API. +[sig-network]: https://github.com/kubernetes/community/tree/master/sig-network + +### Where to get started -### References +To get started, please read through [API overview](api-overview.md). These +documents give the necessary background to understand the API and the use-cases +it targets. Once you have a good understanding of the API at a higher-level, +please follow one of our [guides](guides.md) to dive deeper into different parts +of the API. -Finally, for a complete API reference, please refer to: +For a complete API reference, please refer to: -- [API reference](spec.md) +- [API reference](spec.md) - [Go docs for the package](https://pkg.go.dev/sigs.k8s.io/service-apis/apis/v1alpha1) -## Contacts +### How to get involved + +This project has many contributors and we welcome anybody and everybody to get +involved. Join our weekly meetings, file issues, or ask questions in Slack. No +contribution is too small - even opinions matter! + +- [Weekly meeting schedule](community.md#meetings) +- [Service APIs Slack](https://kubernetes.slack.com/messages/sig-network-service-apis) +- [Enhancement requests](enhancement-requests.md) +- [Project owners](https://raw.githubusercontent.com/kubernetes-sigs/service-apis/master/OWNERS) + -Please reach out to the maintainers for clarifications or feedback: -- Slack: [#sig-network-service-apis](https://kubernetes.slack.com/messages/sig-network-service-apis) -- [Project Owners](https://raw.githubusercontent.com/kubernetes-sigs/service-apis/master/OWNERS) diff --git a/docs/images/api-model.png b/docs/images/api-model.png new file mode 100644 index 0000000000..8c3ed5d6f3 Binary files /dev/null and b/docs/images/api-model.png differ diff --git a/docs/index.html b/docs/index.html index 74a7307b2b..ceb22c6d33 100644 --- a/docs/index.html +++ b/docs/index.html @@ -202,29 +202,22 @@