How to Organize API Types

[danehans]

Currently, EG API types reside in 2 locations:

• Envoy Gateway and Envoy Proxy configuration: api/config/v1alpha1.
• Extended functionality: api/v1alpha1.

This makes imports a bit confusing:

import (
	egv1a1 "github.com/envoyproxy/gateway/api/v1alpha1"
	egcfgv1a1 "github.com/envoyproxy/gateway/api/config/v1alpha1"
)

It's unclear what API types are being imported from github.com/envoyproxy/gateway/api/v1alpha1.

[danehans]

From the 5/13/22 EG community call, @youngnick proposes:

I recommend keeping all the types in the version directory (eg v1alpha1), with validation, helper, or utility code in subdirectories.

[danehans]

My recommendation slightly differs from the above. I suggest having separate config and extension API groups. Helper functions, validation, etc. will live within each group for the associated types. This allows versioning the extension types separately from the config types. For example, the EnvoyProxy type can graduate faster than extension API types since they may be more widely used. Additionally, it simplifies transitioning the extension APIs into a separate repo.

Thoughts @youngnick

[zirain]

+1 to egv1 "github.com/envoyproxy/gateway/api/v1alpha1" or egv1alpha1 "github.com/envoyproxy/gateway/api/v1alpha1"

[youngnick]

@danehans, I think that's fine, although I suggest standardizing the import names to make reading the code easier.

[danehans]

@arkodg @AliceProxy @Xunzhuo @skriss please comment if you have issue with the approach in #809 (comment).

[arkodg]

@danehans i think theres a typo in the issue description - Extended functionality: api/v1alpha1
as @zirain suggested I prefer all EG APIs to live under api/v1alpha1 under the same group for now so there are lesser groups to revision

[danehans]

i think theres a typo in the issue description

@arkodg thanks for catching this. I updated the description.

I prefer all EG APIs to live under api/v1alpha1 under the same group for now so there are lesser groups to revision

If our long-term intention is for extensions to live outside of the EG repo, they'll be revisioned separately.

[arkodg]

this was discussed in the community meeting today
@AliceProxy and I are in agreement to move the Group from config.gateway.envoyproxy.io to gateway.envoyproxy.io
https://github.com/envoyproxy/gateway/blob/main/api/config/v1alpha1/groupversion_info.go#L15 in v0.5.0.

This will be a breaking change for users using the EnvoyProxy resource today.

@envoyproxy/gateway-maintainers, would be great if you can 👍 👎 ?

[kflynn]

Until we're at 1.0.0, we should not be afraid of breaking changes. Go for it.

[Alice-Lilith]

Until we're at 1.0.0, we should not be afraid of breaking changes. Go for it.

+1 for callpsing everything into gateway.envoyproxy.io and making the breaking change without a deprecation policy or any kind of "migration". Nobody should be running this in production right now.

[zirain]

@envoyproxy/gateway-steering-committee @envoyproxy/nighthawk-maintainers we need a certain policy for support and deprecation.

[arkodg]

@zirain deprecation policy is being tracked with #714