Skip to content

fix(AIP-128): clarify usage of annotations field for Declarative-friendly resources #1298

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
amirkaromashkin wants to merge 4 commits into
base: master
Choose a base branch
from
Open

fix(AIP-128): clarify usage of annotations field for Declarative-friendly resources #1298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0b78ac9
fix(AIP-128): clarify usage of `annotations` field
amirkaromashkin Jan 29, 2024
5e0e54c
fix(AIP-148): clatify guide for annotations regarding Declarative-fri…
amirkaromashkin Jan 29, 2024
3a2d269
fix(AIP-148): fix should to must in regard to annotations for declara…
amirkaromashkin Jan 29, 2024
56f1c61
Add changelog for AIP-0148
amirkaromashkin Jan 29, 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
9 changes: 4 additions & 5 deletions aip/general/0128.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,14 +75,13 @@ is a comprehensive reference to declarative-friendly guidance in other AIPs:
- Resources **should** provide change validation: see AIP-163.
- Resources **should not** implement soft-delete. If the id cannot be re-used,
the resource **must** implement soft-delete and the undelete RPC: see AIP-164


### Annotations

See [AIP-148 annotations][].
- Resources **must** include a
`map<string, string> annotations` field to allow clients to store small amounts
of arbitrary data: see AIP-148
Comment on lines +78 to +80
Copy link

@yordis yordis Feb 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Would you say that this field has a similar intent as https://stripe.com/docs/api/metadata

Useful for correlation or putting extra metadata that could be used late.

Copy link
Contributor

@bgrant0607 bgrant0607 Feb 2, 2024

Choose a reason for hiding this comment

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

They are intended to have the same purpose as https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/

Copy link
Author

@amirkaromashkin amirkaromashkin Feb 2, 2024

Choose a reason for hiding this comment

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

I can only agree with both comments above :)

Copy link

@yordis yordis Feb 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I understand the usage of annotations in the context of Kubernetes, but I am trying to find the usefulness from the AIP perspective outside that given Domain.

It should be a less technical-focused product and more general in the public domain (fintech, education, etc.).

Related to #1288 (comment)

The topic of transient data and/or user-controlled (external clients own the data) instead of system-controlled (internal to systems, not intended outside programmers that own the system).

The AIPs can clarify and help with the decision-making here.


## Changelog

- **2024-01-29**: Clarify usage of `annotations`.
- **2023-07-13**: Move `annotations` from AIP-148.
- **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
Expand Down
5 changes: 3 additions & 2 deletions aip/general/0148.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ field **may** be added.

The `annotations` field **must** use the [Kubernetes limits][] to maintain wire
compatibility, and **should** require dot-namespaced annotation keys to prevent
tools from trampling over one another.
tools from trampling over one another. [Declarative-friendly resources][] **must** include this field.

Examples of information that might be valuable to store in annotations include:

Expand Down Expand Up @@ -175,6 +175,7 @@ Before 2023-07, `purge_time` for soft-deleted resources was also called

## Changelog

- **2024-01-29**: Clarify usage of `annotations` in `Declarative-friendly resources`.
- **2023-10-05**: Introduce well known string fields with IP Address and `uid`.
- **2023-08-14**: Introduce the term `annotations` from AIP-128.
- **2023-07-13**: Introduce the term `purge_time`.
Expand All @@ -185,4 +186,4 @@ Before 2023-07, `purge_time` for soft-deleted resources was also called
[aip-202]: ./0202.md
[declarative-friendly resources]: ./0128.md#resources
[kubernetes limits]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
[uuid4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)
[uuid4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)