diff --git a/aip/general/0008.md b/aip/general/0008.md index 8d62fe6a3b..cccf46ec55 100644 --- a/aip/general/0008.md +++ b/aip/general/0008.md @@ -38,10 +38,9 @@ AIPs **must** have appropriate front matter. ```yaml --- -aip: - id: 8 - state: reviewing - created: 2019-05-28 +id: 8 +state: reviewing +created: 2019-05-28 permalink: /8 redirect_from: - /08 diff --git a/aip/general/0111.md b/aip/general/0111.md new file mode 100644 index 0000000000..4deb0ffec3 --- /dev/null +++ b/aip/general/0111.md @@ -0,0 +1,78 @@ +--- +id: 111 +state: approved +created: 2023-06-17 +placement: + category: api-concepts + order: 50 +--- + +# Planes + +Resources and methods on an API can be divided into the *plane* that they reside +or perform operations upon. For the context of APIs, the following planes are +defined: + +- Management plane: a uniform, resource-oriented API that primarily + configures and allows retrieval of resources. +- Data plane: a heterogenous API (ideally resource-oriented) that reads and + write user data. Often connects to entities provisioned by the management + plane, such as virtual machines. + +The term "plane" was originally used in networking architecture. Although system +and network architecure often defines additional planes (e.g. control plane or +power planes), as the AIPs are focused on the interface, they are not defined in +this AIP. + +## Guidance + +### Management Plane + +Management resources and methods exist primarily to provision, configure, and +audit the resources that the data plane interfaces with. + +As an example, the following are considered management resources for a cloud +provider: + +- virtual machines +- virtual private networks +- virtual disks +- a blob store instance +- a project or account + +### Data Plane + +Methods on the data plane operate on user data in a variety of data formats, and +generally interface with a resource provisioned via a management plane API. +Examples of data plane methods include: + +- writing and reading rows in a table +- pushing to or pulling from a message queue +- uploading blobs to or downloading blobs from a blob store instance + +Data plane APIs **may** be heterogenous across a larger API surface, due to +requirements including high throughput, low latency, or the need to adhere to an +existing interface specification (e.g. ANSI SQL). + +- For convenience, resources and methods that operate on the data plane **may** +expose themselves via resource-oriented management APIs. If so, those resources +and methods **must** adhere to the requirements of the management plane as +specified in the other AIPs ([AIP-131][] through [AIP-135][]). + +### Major distinctions between management and data plane + +- [IaC][] tools operate on the management plane exclusively. +- Data planes are often on the critical path of user-facing functionality, and + therefore: + - Have higher availabilty requirements than management planes. + - Are more peformance-sensitive than management planes. + - Require higher-throughput than management planes. + + +[AIP-131]: ./0131.md +[AIP-135]: ./0136.md +[IaC]: ./0009.md#iac + +## Changelog + +- **2023-06-10**: Introduction of this AIP. \ No newline at end of file diff --git a/aip/general/0128.md b/aip/general/0128.md index 2b55cc3379..74fa449d63 100644 --- a/aip/general/0128.md +++ b/aip/general/0128.md @@ -26,20 +26,6 @@ tools requires uniformity, so that integration can be automated. ## Guidance -Services **should** clearly delineate between "control plane" operations and -"data plane" operations, ideally through the use of distinct services with -their own interface definition documents. - -- Control plane operations are responsible for managing the _lifecycle_ of - resources. -- Data plane operations are responsible for managing the _content_ of - resources. - -The same resource **may** have both control plane operations and data plane -operations associated with it. For example, a database API would have -operations to create or delete database tables (control plane) as well as -operations to write and read rows to that table (data plane). - ### Resources Resources that are declarative-friendly **must** use only strongly-consistent @@ -111,5 +97,6 @@ is a comprehensive reference to declarative-friendly guidance in other AIPs: ## Changelog -- **2023-05-11**: removed must on resource_id, which was upstreamd to a general - must \ No newline at end of file +- **2023-06-17**: Definition of plane was removed and incorporated into AIP-111. +- **2023-05-11**: Removed must on resource_id, which was upstreamed to a general + must. \ No newline at end of file diff --git a/aip/general/0133.md b/aip/general/0133.md index 2422c3e8ee..d625c55b8b 100644 --- a/aip/general/0133.md +++ b/aip/general/0133.md @@ -126,8 +126,18 @@ to done if the request is effectively immediate. ### User-specified IDs -An API **must** allow a client to specify the ID component -of a resource (the last segment of the resource name) on creation. An API +An API **must** allow a user to specify the ID component of a resource (the last +segment of the resource name) on creation if the API is operating on the +[Management Plane][]. + +On the [Data Plane][], an API **should** allow a user to specify the ID. +Exceptional cases should have the following behavior: + +- The data plane resource allows identical records without a need to + disambiguate between the two (e.g. rows in a table with no primary key). +- The data plane resource will not be exposed in [IaC][] clients. + +An API **may** allow the `{resource}_id` field have the [field_behavior][] `OPTIONAL`, and generate a system-generated ID if one is not specified. @@ -193,6 +203,8 @@ name and use it in references from other resources. [aip-155]: ./0155.md [aip-203]: ./0203.md [aip-210]: ./0210.md +[Data Plane]: ./0111.md#data-plane +[Management Plane]: ./0111.md#management-plane [errors]: ./0193.md [field_behavior]: ./203.md [IaC]: ./0009.md#iac @@ -201,7 +213,8 @@ name and use it in references from other resources. ## Changelog - **2023-05-11**: Changing guidance around resource_id to a must. -- **2022-11-04**: Referencing aggregated error guidance in AIP-193, similar to other CRUDL AIPs. +- **2022-11-04**: Referencing aggregated error guidance in AIP-193, similar to + other CRUDL AIPs. - **2022-06-02**: Changed suffix descriptions to eliminate superfluous "-". - **2020-10-06**: Added declarative-friendly guidance. - **2020-08-14**: Updated error guidance to use permission denied over diff --git a/aip/general/scope.yaml b/aip/general/scope.yaml index 8308506da6..74fd2b66e3 100644 --- a/aip/general/scope.yaml +++ b/aip/general/scope.yaml @@ -4,6 +4,8 @@ order: 0 categories: - code: meta - code: process + - code: api-concepts + title: API Concepts - code: resource-design title: Resource Design - code: operations