This document is a deep dive into the reasoning and design for Service APIs.
-In the original design of Kubernetes, Ingress and Service resources were -based on a self-service model of usage; developers who create Services and -Ingresses control all aspects of defining and exposing their applications to -their users.
-We have found that the self-service model does not fully capture some of the -more complex deployment and team structures that our users are seeing. The -Gateway/Routes API will target the following personas:
+There are 3 primary roles in the API:
We expect that each persona will map approximately to a Role in the Kubernetes
-Role-Based Authentication (RBAC) system and will define resource model
-responsibility and separation.
Depending on the environment, multiple roles can map to the same user. -For example, giving the user all the above roles replicates the self-service -model.
-For more information on the roles and personas considered in the Service API -design, refer to the Security Model.
+There could be a fourth role of Application Admin in some use cases.
+Please refer to the roles and personas section +in the Security model for details.
Note: Resources will initially live in the
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -networking.x-k8s.ioAPI group as diff --git a/docs/cookbook/index.html b/docs/cookbook/index.html deleted file mode 100644 index d6af8b4408..0000000000 --- a/docs/cookbook/index.html +++ /dev/null @@ -1,530 +0,0 @@ - - - - - - -API cookbook - Kubernetes Service APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Skip to content - - - -- - - -- - - - -- - - - - - - - \ No newline at end of file diff --git a/docs/devguide/index.html b/docs/devguide/index.html index 76fad51408..8a397e7044 100644 --- a/docs/devguide/index.html +++ b/docs/devguide/index.html @@ -254,20 +254,8 @@- - - - - -- - - - - - - - ----- - - - -API Cookbook
-TODO: Cookbook will be a page w/ examples for common tasks (exposing -an HTTP service, configuring TLS, etc).
- - - - - - - - - - -- - User guide - - - - - - - - - -- - API cookbook + + Introduction @@ -314,8 +302,8 @@- - Releases + + API specification @@ -326,8 +314,8 @@- - API specification + + Releases @@ -567,7 +555,7 @@Publishing
diff --git a/docs/enhancement-requests/index.html b/docs/enhancement-requests/index.html index b77c6aa102..bf500b5389 100644 --- a/docs/enhancement-requests/index.html +++ b/docs/enhancement-requests/index.html @@ -254,20 +254,8 @@- - User guide - - - - - - - - - -- - API cookbook + + Introduction @@ -314,8 +302,8 @@- - Releases + + API specification @@ -326,8 +314,8 @@- - API specification + + Releases diff --git a/docs/faq/index.html b/docs/faq/index.html index f875b4276d..f4203ab6f0 100644 --- a/docs/faq/index.html +++ b/docs/faq/index.html @@ -254,20 +254,8 @@- - User guide - - - - - - - - - -- - API cookbook + + Introduction @@ -314,8 +302,8 @@- - Releases + + API specification @@ -326,8 +314,8 @@- - API specification + + Releases diff --git a/docs/userguide/index.html b/docs/guides/index.html similarity index 94% rename from docs/userguide/index.html rename to docs/guides/index.html index 4726e899be..32597a4fe1 100644 --- a/docs/userguide/index.html +++ b/docs/guides/index.html @@ -36,7 +36,7 @@ -User guide - Kubernetes Service APIs +Introduction - Kubernetes Service APIs @@ -75,7 +75,7 @@ - + Skip to content @@ -101,7 +101,7 @@ - User guide + Introduction @@ -264,8 +264,8 @@ - - User guide + + Introduction @@ -276,18 +276,6 @@ -- - API cookbook - - - - - - - - -TLS @@ -325,8 +313,8 @@ - - Releases + + API specification @@ -337,8 +325,8 @@- - API specification + + Releases @@ -448,8 +436,12 @@ -API user guide
-TODO
+Guides
+Guides demonstrate and provide examples of how to use the API. +Please checkout one of the following guides:
+ @@ -486,13 +478,13 @@API user guide
- +diff --git a/docs/index.html b/docs/index.html index bc59b357fa..77d180de62 100644 --- a/docs/index.html +++ b/docs/index.html @@ -202,8 +202,22 @@
- - - Resources + + Get started + + +
+ +- + + Guides + + +
+ +- + + References
@@ -299,20 +313,8 @@- - - User guide - -
- - - - - - - -- - - API cookbook + + Introduction
@@ -359,8 +361,8 @@- - - Releases + + API specification
@@ -371,8 +373,8 @@- - - API specification + + Releases
@@ -475,8 +477,22 @@
- - - Resources + + Get started + + +
+ +- + + Guides + + +
+ +- + + References
@@ -506,29 +522,26 @@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. -Use the following resources to learn more about Service APIs.Resources
-If you are a user:
- -If you are a developer:
- -For everyone:
+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. Use the following resources to learn more about +Service APIs.Get started
+To get started, please read through API concepts and +Security model. These documents give the necessary background +to understand the API and the use-cases it targets.
+Guides
+Once you have a good understanding of the API at a higher-level, please +follow one of our guides to dive deeper into different parts of +the API.
+References
+Finally, for a complete API reference, please refer to:
-
- Concepts and detailed descriptions
-- API specification
-- Releases
-- Security Model
-- Enhancement requests
+- API reference
+- Go docs for the package
Contacts
+Please reach out to the maintainers for clarifications or feedback:
@@ -582,7 +570,7 @@
- Slack: #sig-network-service-apis
- Project Owners
diff --git a/docs/releases/index.html b/docs/releases/index.html index aad34e1705..6c98057bec 100644 --- a/docs/releases/index.html +++ b/docs/releases/index.html @@ -254,20 +254,8 @@- - - User guide - -
- - - - - - - -- - - API cookbook + + Introduction
@@ -314,6 +302,18 @@ + +- + + API specification + +
+ + + + + + @@ -374,18 +374,6 @@ - - - - - -- - - API specification - -
- -Other Official Custom Resources
- +diff --git a/docs/security-model/index.html b/docs/security-model/index.html index bb4bea2295..408f50b163 100644 --- a/docs/security-model/index.html +++ b/docs/security-model/index.html @@ -274,8 +274,8 @@- - - Roles + + Roles and personas
@@ -410,20 +410,8 @@- - - User guide - -
- - - - - - - -- - - API cookbook + + Introduction
@@ -470,8 +458,8 @@- - - Releases + + API specification
@@ -482,8 +470,8 @@- - - API specification + + Releases
@@ -613,8 +601,8 @@- - - Roles + + Roles and personas
@@ -746,8 +734,14 @@Additional Configuration
- Which namespaces Routes can be targeted in by Gateways of the specified GatewayClass.
-Roles
-For the purposes of this security model, 3 common roles have been identified:
+Roles and personas
+In the original design of Kubernetes, Ingress and Service resources were +based on a self-service model of usage; developers who create Services and +Ingresses control all aspects of defining and exposing their applications to +their users.
+We have found that the self-service model does not fully capture some of the +more complex deployment and team structures that our users are seeing. The +Service APIs are designed to target the following personas:
- Infrastructure provider: The infrastructure provider (infra) is responsible for the overall environment that the cluster(s) are operating in. @@ -758,7 +752,7 @@
Roles
application permissions.- Application developer: The application developer (dev) is responsible for defining their application configuration (e.g. timeouts, request - matching/filter) and Service composition (e.g. path routing to backends).
+ matching/filter) and Service composition (e.g. path routing to backends).Although these roles can cover a wide variety of use cases, some organizations may be structured slightly differently. Many organizations may also have a @@ -767,6 +761,12 @@
Roles
- Application admin: The application admin has administrative access to some namespaces within a cluster, but not the cluster as a whole.
+We expect that each persona will map approximately to a
+Rolein the Kubernetes +Role-Based Authentication (RBAC) system and will define resource model +responsibility and separation.Depending on the environment, multiple roles can map to the same user. +For example, giving the user all the above roles replicates the self-service +model.
The Security Model
There are two primary components to the Service APIs security model: RBAC and namespace restrictions.
@@ -958,13 +958,13 @@Validating Webhook
- +diff --git a/docs/spec/index.html b/docs/spec/index.html index 44c2bd8b0f..a76d1fe327 100644 --- a/docs/spec/index.html +++ b/docs/spec/index.html @@ -250,20 +250,8 @@- - - User guide - -
- - - - - - - -- - - API cookbook + + Introduction
@@ -310,18 +298,6 @@ - -- - - Releases - -
- - - - - - @@ -337,6 +313,18 @@ + + + + + +- + + Releases + +
+ + @@ -4314,7 +4302,7 @@UDPRouteStatus - +
diff --git a/docs/tls/index.html b/docs/tls/index.html index b9b3846156..37ec09ae85 100644 --- a/docs/tls/index.html +++ b/docs/tls/index.html @@ -256,20 +256,8 @@- - - User guide - -
- - - - - - - -- - - API cookbook + + Introduction
@@ -442,8 +430,8 @@- - - Releases + + API specification
@@ -454,8 +442,8 @@- - - API specification + + Releases
@@ -979,7 +967,7 @@Extensions
- +diff --git a/mkdocs.yml b/mkdocs.yml index 356c056a8c..0e5ef5e3a5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,12 +14,11 @@ nav: API concepts: concepts.md Security Model: security-model.md - Guides: - - User guide: userguide.md - - API cookbook: cookbook.md + - Introduction: guides.md - TLS: tls.md - References: - - Releases: releases.md - API specification: spec.md + - Releases: releases.md - Contributing: - Developer guide: devguide.md - Enhancement requests: enhancement-requests.md