When will v1beta2 be fixed?

[l8huang]

v1beta2 is marked as (working version, not fixed), is there a timeline for when it will be?
Additionally, does working version imply that v1beta2 might take incompatible changes?

[s1061123]

Currently we don't have any clear plan it yet. As usual Kubernetes API, we suppose different version might take incompatible changes because we alined with usual consensus.

[l8huang]

we suppose different version might take incompatible changes because we alined with usual consensus.

Just want to clarify that, for the same version(v1beta2), when it's working version, does it take incompatible changes?

[s1061123]

It depends on. Need to discuss in the community first.

[girishmg]

@s1061123 the only change that has gone into v1beta2 is the support for endport. This will bring us close to NetworkPolicy feature wise.

So, can we please ratify v1beta2 and any other changes, if any, can come in subsequent versions of the API.

[s1061123]

@girishmg Currently I don't have a time to proceed v1beta2 release. Appreciated if you could help that.

[girishmg]

Absolutely, we would love to help.

Can you please let us know how to get involved? cc: @l8huang

[s1061123]

Hi @l8huang and @girishmg

We don't have clear formalized process for that, so I just list up what I have. @dougbtv , could you please double check. Feel free to add.

1. Technical Requirements:

• Currently this API is used by several projects, so we cannot deprecate v1beta1. So please support both (v1beta1 and v1beta2) in this repo.
  • for example, as keep current scheme.yml and introduce another yaml file for v1beta2

2. Community Requirements:

• We have bi-weekly community meeting, so please attend that and discuss in the community. Meeting time is in the google doc and next meeting is 6/13.

https://docs.google.com/document/d/1oE93V3SgOGWJ4O1zeD1UmpeToa0ZiiO6LqRAmZBPFWM/edit

[girishmg]

@l8huang can we please open this issue? As we are still discussing this and the path forward.

@s1061123 the existing customers can continue to use v1beta1 CR. When the new CR is applied with storage set to true for v1beta2, the K8s API server will just save that old v1beta1 CR has v1beta2 with endPort not set. Now, the OLD MNP controller, which understands only v1beta1, will ask K8s API server for v1beta1 objects for reconcilation. K8s API server will return v1beta1 object since it knows both the versions.

This is backwards compatible.

[l8huang]

Currently this API is used by several projects, so we cannot deprecate v1beta1. So please support both (v1beta1 and v1beta2) in this repo.
for example, as keep current scheme.yml and introduce another yaml file for v1beta2

Having multiple scheme.ymls could make things complicated, Istio API and k8s/gateway-api uses same same definitions for all versions, all versions are served and only one version has storage: true.

If multi-network policies adopt the same practice, the endPort field should be added into both v1beta1 and v1beta2. The distinctions between the fixed and working versions are conceptual; essentially, they are identical.

Reference: Istio CRD Versioning

[s1061123]

If multi-network policies adopt the same practice, the endPort field should be added into both v1beta1 and v1beta2. The distinctions between the fixed and working versions are conceptual; essentially, they are identical.

If we should, v1beta1 and v1beta2 is pretty same, so we don't have v1beta2, right? In such case, we don't require v1beta2 no longer, to support endPort. So how about to just add endPort to v1beta1?

As you know, endPort is optional, so v1beta1 could add endPort without any conversion, I suppose.

[girishmg]

If multi-network policies adopt the same practice, the endPort field should be added into both v1beta1 and v1beta2.

What is the meaning of versioning then? It doesn't make sense to me atleast.

[l8huang]

TL;DR:

• gateway-api v1 and v1betaN have same definition
• versioning is done at the API level -- k8s gateway-api uses <gateway:experimental> to define experimental fields, istio just simplifies versioning by making all versions(v1, beta, alpha) same
• The promotion of a CRD follows a progression from alpha to beta and v1, rather than incrementing through versions such as v1beta1, v1beta2, v1beta3, and so forth

gateway-api follows The Kubernetes API, the Alpha, Beta, and Stable Versions represent the API's maturity level, and versioning is done at the API level

API groups and versioning

Versioning is done at the API level rather than at the resource or field level to ensure that the API presents a clear, consistent view of system resources and behavior, and to enable controlling access to end-of-life and/or experimental APIs.
API resources are distinguished by their API group, resource type, namespace (for namespaced resources), and name. The API server handles the conversion between API versions transparently: all the different versions are actually representations of the same persisted data. The API server may serve the same underlying data through multiple API versions.

For example, suppose there are two API versions, v1 and v1beta1, for the same resource. If you originally created an object using the v1beta1 version of its API, you can later read, update, or delete that object using either the v1beta1 or the v1 API version, until the v1beta1 version is deprecated and removed. At that point you can continue accessing and modifying the object using the v1 API.

An gateway-api API is promoted from Alpha to Beta and Stable, e.g. Gateway is gateway.networking.k8s.io/v1, its CRD has same schema for v1 and v1beta1; TCPRoute is gateway.networking.k8s.io/v1alpha2, its CRD only has version v1alpha2, v1alpha2 CRD are in experimental folder.

gateway-api has a way to define an experimental field in v1/v1beta1 API, e.g Gateway field Infrastructure:

	// Infrastructure defines infrastructure level attributes about this Gateway instance.
	//
	// Support: Core
	//
	// <gateway:experimental>
	// +optional
	Infrastructure *GatewayInfrastructure `json:"infrastructure,omitempty"`

it appears in crd/experimental/gateway.networking.k8s.io_gateways.yaml's v1 and v1beta1, but not in crd/standard/gateway.networking.k8s.io_gateways.yaml

[zeeke]

If multi-network policies adopt the same practice, the endPort field should be added into both v1beta1 and v1beta2.

What is the meaning of versioning then? It doesn't make sense to me atleast.

@l8huang @girishmg @s1061123
If I understood correctly, we can add the endPort field to v1beta1 and delete v1beta2.
As it is an optional field, any controller that currently works with v1beta1 should not be affected.

Also, deleting the v1beta2 version from scheme.yml and related Go files should not be a problem since no controller is supposed to be using that API ATM, right?

[s1061123]

Currently 'v1beta2' is just recognized as 'master' branch. Working and reserved the name as 'next version'. Currently v1beta1 and v1beta2 is identical and no detailed timeline to publish v1beta2 as well as v2. Once we have incompatible changes, then we may suppose to introduce 'v1beta2' as 'new version', but not for now because we don't have such feature yet.

@l8huang I suppose you seems to have new feature for v1beta2 and that's why you asks us about the timeline. Could you please let us know the feature for v1beta2?

[zeeke]

Thanks @s1061123 for clarifying that! I didn't notice that in scheme.yml, both v1beta1 and v1beta2 have the endport field.

This is not true if we look at go files:

multi-networkpolicy/pkg/apis/k8s.cni.cncf.io/v1beta1/types.go

Lines 95 to 101 in f76867e

	type MultiNetworkPolicyPort struct {
	// +optional
	Protocol *v1.Protocol `json:"protocol,omitempty"`
	// +optional
	Port *intstr.IntOrString `json:"port,omitempty"`
	}

multi-networkpolicy/pkg/apis/k8s.cni.cncf.io/v1beta2/types.go

Lines 95 to 104 in f76867e

	type MultiNetworkPolicyPort struct {
	// +optional
	Protocol *v1.Protocol `json:"protocol,omitempty"`
	// +optional
	Port *intstr.IntOrString `json:"port,omitempty"`
	// +optional
	EndPort *int32 `json:"endPort,omitempty"`
	}

Maybe adding the endport field to v1beta1 types would solve this?

[s1061123]

@zeeke Currently I don't have not so much time for that, so please bring it to NPWG to discuss how to proceed that.