-
Notifications
You must be signed in to change notification settings - Fork 18
feat(planes): porting AEP-111 from AIP-111 #85
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,66 @@ | ||||||||||
# Planes | ||||||||||
|
||||||||||
Resources and methods on an API can be divided into the _plane_ that they | ||||||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
reside or perform operations upon. For the context of APIs, the following | ||||||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
planes are defined: | ||||||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
- Management plane: a uniform, resource-oriented API that primarily configures | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What does "uniform" mean here? What would make an API non-uniform? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. in this case I mean AEP-compliant API. will fix. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. this is in contrast to a data plane API (e.g. SQL server the API is via SQL statements). |
||||||||||
and allows retrieval of resources. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Corresponding grammatical change for data plane, if you agree. |
||||||||||
- Data plane: a heterogenous API (ideally resource-oriented) that reads and | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why "ideally"? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. cases where you can't adhere to the AEPs are explained in the data-plane section. Do you think I should re-iterate that here? |
||||||||||
write user data. Often connects to entities provisioned by the management | ||||||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
plane, such as virtual machines. | ||||||||||
|
||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I made a bunch of local suggestions above, but on the whole, I'm confused by the point this is trying to make. The management plane reads and configures resources; the data plan is for reading and writing user data (also "ideally" in the form of resources). I'm not sure that someone with no context could easily categorize APIs into the right plane given these definitions. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ...I'm not even sure that I can. Would creating a Facebook group be a management plane or data plane method? The group name/description/etc. are UGC, but if individual posts in the group are part of the data plane then does that place group management in the management plane? If these resources are all in the same API, and APIs as a whole are categorized as data plane or management plane, does that mean this API is in the data plane? What if There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think on the whole we probably should discuss these in-person - would be a lot easier. But answering your questions: Facebook group would be management plane. Planes are somewhat contextual, but you create a facebook group and users post in them.
I don't think APIs have to be categorized as completely data / management. I think this could be done on the operation level. WDYT? I can update the doc.
Yep that's fine, see above. |
||||||||||
The term "plane" was originally used in networking architecture. Although | ||||||||||
system and network architecture often defines additional planes (e.g. control | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
If "system and network architecture" is short for "system architecture and network architecture", which I think it is? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yep! That's correct. I'm going to remove this section though - I don't think it's particularly relevant information, although maybe context is helpful? |
||||||||||
plane or power planes), as the AEPs are focused on the interface, they are not | ||||||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
defined in this AEP. | ||||||||||
|
||||||||||
## Guidance | ||||||||||
|
||||||||||
### Management Plane | ||||||||||
|
||||||||||
Management resources and methods exist primarily to provision, configure, and | ||||||||||
audit the resources that the data plane interfaces with. | ||||||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
||||||||||
As an example, the following are considered management resources for a cloud | ||||||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
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 | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What does it mean for an API to be heterogenous? Not entirely resource-oriented? What is a "larger API surface"? Larger than what? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I probably can be more precise that heterogeneity - I mean that there's more leeway in the requirements of data plane vs those for management APIs, up to being completely non-AEP compliant (e.g. SQL or a protocol for blob storage). |
||||||||||
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 AEPs. | ||||||||||
Comment on lines
+55
to
+56
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Which other AEPs do (or will) talk about the requirements of a management plane API for its corresponding data plane APIs? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. https://google.aip.dev/search?q=plane. Primarily management plane operations have additional requirements around CRUDL. |
||||||||||
|
||||||||||
### Major distinctions between management and data plane | ||||||||||
|
||||||||||
- [Declarative clients][] 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. | ||||||||||
|
||||||||||
[Declarative clients]: ./0003.md#declarative-clients | ||||||||||
|
||||||||||
## Changelog | ||||||||||
|
||||||||||
- **2024-01-27**: initial fork of this AEP from https://google.aip.dev/111. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
id: 111 | ||
state: approved | ||
slug: planes | ||
created: 2024-01-27 | ||
placement: | ||
category: general |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a bunch of comments below, some just proofreading and others more about the content, but my big question is: what guidance does this AEP actually contain? It doesn't seem like there's anything actionable. I don't know what lint rules I'd write, or when I'd refer to it as part of API design. What API design problem is this AEP addressing?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
at Google, there was a large debate about the type of design guidance that would be needed to provide really high-quality declarative APIs (e.g. for Terraform or Kubernetes), at odds with more flexible API needs (generally because of existing precedent, but also sometimes a matter of convenience).
To begin to help address those, we started adding this notion of API planes, and attached various guidance to the management plane in the AIPs: https://google.aip.dev/search?q=management.
to be fair this aligned with some terminology primarily used at Google. Many APIs at least differentiate between a "control plane" and a "data plane": https://docs.aws.amazon.com/whitepapers/latest/aws-fault-isolation-boundaries/control-planes-and-data-planes.html.
I think it's important for us to add some clarity on the various planes of operations and how to differentiate them, given it is common nomenclature for many APIs (especially in the cloud).
I think the content here is actually pretty solid, but it was definitely a work in progress
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's all useful context...but it doesn't actually answer the question about what actionable guidance is in this AEP. What would a violation of this AEP look like?