Skip to content

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.

Sign up for GitHub

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

Open
toumorokoshi wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(planes): porting AEP-111 from AIP-111 #85

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2670a2e
feat(planes): porting AEP-111 from AIP-111
toumorokoshi Jan 28, 2024
4bde4b2
address comments
toumorokoshi Feb 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions aep/general/0111/aep.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Planes
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

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?

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

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

Copy link
Collaborator

@rofrankel rofrankel May 18, 2024 •
edited
Loading

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?


Resources and methods on an API can be divided into the _plane_ that they
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Resources and methods on an API can be divided into the _plane_ that they
Resources and methods in 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
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "uniform" mean here? What would make an API non-uniform?

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in this case I mean AEP-compliant API. will fix.

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

Choose a reason for hiding this comment

The 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.
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Management plane: a uniform, resource-oriented API that primarily configures
and allows retrieval of resources.
- Management plane: contains uniform, resource-oriented APIs that primarily configure
and allow retrieval of resources.

Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The 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
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why "ideally"?

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

Choose a reason for hiding this comment

The 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
plane, such as virtual machines.

Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The 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.

Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The 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 CreateBlobStore and CreateBlob are in the same API? Why wouldn't they be?

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

Choose a reason for hiding this comment

The 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.

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?

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.

What if CreateBlobStore and CreateBlob are in the same API? Why wouldn't they be?

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
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
system and network architecture often defines additional planes (e.g. control
system and network architecture often defines additional plane (e.g. control

If "system and network architecture" is short for "system architecture and network architecture", which I think it is?

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

Choose a reason for hiding this comment

The 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
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.

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
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The 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?

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

across a larger API surface doesn't seem helpful here - will remove.

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
Copy link
Collaborator

@rofrankel rofrankel Jan 30, 2024

Choose a reason for hiding this comment

The 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?

Copy link
Member Author

@toumorokoshi toumorokoshi Feb 5, 2024

Choose a reason for hiding this comment

The 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.
6 changes: 6 additions & 0 deletions aep/general/0111/aep.yaml
View file
Open in desktop
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