Skip to content

Commit 2670a2e

Browse files
committed
feat(planes): porting AEP-111 from AIP-111
No major changes, besides removing refrerences to AIPs.
1 parent 2eb0c24 commit 2670a2e

File tree

2 files changed

+72
-0
lines changed

2 files changed

+72
-0
lines changed

aep/general/0111/aep.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Planes
2+
3+
Resources and methods on an API can be divided into the _plane_ that they
4+
reside or perform operations upon. For the context of APIs, the following
5+
planes are defined:
6+
7+
- Management plane: a uniform, resource-oriented API that primarily configures
8+
and allows retrieval of resources.
9+
- Data plane: a heterogenous API (ideally resource-oriented) that reads and
10+
write user data. Often connects to entities provisioned by the management
11+
plane, such as virtual machines.
12+
13+
The term "plane" was originally used in networking architecture. Although
14+
system and network architecture often defines additional planes (e.g. control
15+
plane or power planes), as the AEPs are focused on the interface, they are not
16+
defined in this AEP.
17+
18+
## Guidance
19+
20+
### Management Plane
21+
22+
Management resources and methods exist primarily to provision, configure, and
23+
audit the resources that the data plane interfaces with.
24+
25+
As an example, the following are considered management resources for a cloud
26+
provider:
27+
28+
- virtual machines
29+
- virtual private networks
30+
- virtual disks
31+
- a blob store instance
32+
- a project or account
33+
34+
### Data Plane
35+
36+
Methods on the data plane operate on user data in a variety of data formats,
37+
and generally interface with a resource provisioned via a management plane API.
38+
Examples of data plane methods include:
39+
40+
- writing and reading rows in a table
41+
- pushing to or pulling from a message queue
42+
- uploading blobs to or downloading blobs from a blob store instance
43+
44+
Data plane APIs **may** be heterogenous across a larger API surface, due to
45+
requirements including high throughput, low latency, or the need to adhere to
46+
an existing interface specification (e.g. ANSI SQL).
47+
48+
- For convenience, resources and methods that operate on the data plane **may**
49+
expose themselves via resource-oriented management APIs. If so, those
50+
resources and methods **must** adhere to the requirements of the management
51+
plane as specified in the other AEPs.
52+
53+
### Major distinctions between management and data plane
54+
55+
- [Declarative clients][] operate on the management plane exclusively.
56+
- Data planes are often on the critical path of user-facing functionality, and
57+
therefore:
58+
- Have higher availabilty requirements than management planes.
59+
- Are more peformance-sensitive than management planes.
60+
- Require higher-throughput than management planes.
61+
62+
[Declarative clients]: ./0003.md#declarative-clients
63+
64+
## Changelog
65+
66+
- **2024-01-27**: initial fork of this AEP from https://google.aip.dev/111.

aep/general/0111/aep.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
id: 111
2+
state: approved
3+
slug: planes
4+
created: 2024-01-27
5+
placement:
6+
category: general

0 commit comments

Comments
 (0)