From 135ff327f1c4e117bebe3087834d034558f4bc02 Mon Sep 17 00:00:00 2001 From: Clayton Coleman Date: Wed, 22 Feb 2017 15:18:57 -0500 Subject: [PATCH] Describe API groups and spec/status for simple kinds --- contributors/devel/api-conventions.md | 34 +++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/contributors/devel/api-conventions.md b/contributors/devel/api-conventions.md index 0c57f7dd3..e183bdb5b 100644 --- a/contributors/devel/api-conventions.md +++ b/contributors/devel/api-conventions.md @@ -1,7 +1,7 @@ API Conventions =============== -Updated: 4/22/2016 +Updated: 2/23/2017 *This document is oriented at users who want a deeper understanding of the Kubernetes API structure, and developers wanting to extend the Kubernetes API. @@ -74,6 +74,9 @@ kinds would have different attributes and properties) via HTTP to the server. Resources are exposed via: * Collections - a list of resources of the same type, which may be queryable * Elements - an individual resource, addressable via a URL +* **API Group** a set of resources that are exposed together at the same. Along +with the version is exposed in the "apiVersion" field as "GROUP/VERSION", e.g. +"policy.k8s.io/v1". Each resource typically accepts and returns data of a single kind. A kind may be accepted or returned by multiple resources that reflect specific use cases. For @@ -82,8 +85,17 @@ to create, update, and delete pods, while a separate "pod status" resource (that acts on "Pod" kind) allows automated processes to update a subset of the fields in that resource. +Resources are bound together in API groups - each group may have one or more +versions that evolve independent of other API groups, and each version within +the group has one or more resources. Group names are typically in domain name +form - the Kubernetes project reserves use of the empty group, all single +word names ("extensions", "apps"), and any group name ending in "*.k8s.io" for +its sole use. When choosing a group name, we recommend selecting a subdomain +your group or organization owns, such as "widget.mycompany.com". + Resource collections should be all lowercase and plural, whereas kinds are -CamelCase and singular. +CamelCase and singular. Group names must be lower case and be valid DNS +subdomains. ## Types (Kinds) @@ -156,6 +168,16 @@ API endpoints may deviate from the strict REST pattern and return resources that are not singular JSON objects, such as streams of JSON objects or unstructured text log data. +A common set of "meta" API objects are used across all API groups and are +thus considered part of the server group named `meta.k8s.io`. These types may +evolve independent of the API group that uses them and API servers may allow +them to be addressed in their generic form. Examples are `ListOptions`, +`DeleteOptions`, `List`, `Status`, `WatchEvent`, and `Scale`. For historical +reasons these types are part of each existing API group. Generic tools like +quota, garbage collection, autoscalers, and generic clients like kubectl +leverage these types to define consistent behavior across different resource +types, like the interfaces in programming languages. + The term "kind" is reserved for these "top-level" API types. The term "type" should be used for distinguishing sub-categories within objects or subobjects. @@ -276,6 +298,14 @@ cannot vary from the user's desired intent MAY have only "spec", and MAY rename Objects that contain both spec and status should not contain additional top-level fields other than the standard metadata fields. +Some objects which are not persisted in the system - such as `SubjectAccessReview` +and other webhook style calls - may choose to add spec and status to encapsulate +a "call and response" pattern. The spec is the request (often a request for +information) and the status is the response. For these RPC like objects the only +operation may be POST, but having a consistent schema between submission and +response reduces the complexity of these clients. + + ##### Typical status properties **Conditions** represent the latest available observations of an object's