feat(AIP-111): introducing AIP around planes. (#1132)

The term data plane have been used in the AIPs without a clear
definition.

Introducing the term "management" and "data" plane, as these are
industry-standard terms and are also well defined in the context of
Google APIs.

These definitions are also helpful in:

- providing fine-grained API guidance depending on the plane
- help inform new annotations on resources and methods, which can be
  used for auditing and determining coverage
- further help clarify classifications of methods (AIP-130)

Also removing the redundant text in AIP-128.

Author: toumorokoshi

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

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.

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
+- **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.

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

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