search

kubernetes / k8s.io

Code and configuration to manage Kubernetes project infrastructure, including various *.k8s.io sites
https://git.k8s.io/community/sig-k8s-infra
Apache License 2.0
735 stars 822 forks source link

API Groups registry #2183

Open aojea opened 3 years ago

aojea commented 3 years ago

Following up on https://github.com/kubernetes-sigs/gateway-api/issues/690

After some discussion with @thockin, @liggitt, and an earlier Slack thread with @aojea, it sounds like we should be moving to the k8s.io API group as part of the v1alpha2 release.

API groups on k8s.io are special, they require API review and they may be used for internal APIs or CRDs.

Since the project is growing and there are more subprojects using or wanting to use the k8s.io API group, having a central registry for all them can avoid possible conflicts or naming issues and provide a single source of truth for users and developers.

Should we create a registry with all the official api groups? How can we "enforce" using it?

aojea commented 3 years ago

/assign @thockin @liggitt

thockin commented 3 years ago

This has been on my TODO list forever. We do something internally like this. In fact, let me copy from the internal doc. I was hoping to institute something like this

Kubernetes allows “fully qualified” names for various things, to allow 3rd-party extension with lower risks of collisions (e.g. “ foo.example.com/bar” vs “bar”). In particular this is used for labels and annotations (applicable to all API objects), resources (for nodes and pods), and API groups (all extensions via CRD or EAS). We have historically had few conventions for how to name these things, which has led to myriad forms of names in use.

Goal

This doc describes a convention for managing Kubernetes identifiers.

The Standard

Domain: k8s.io

<explain what this is for>

Domain: kubernetes.io

<explain what this is for>

Domain: x-k8s.io

<explain what this is for>

Style: embrace dashes

Both the prefix portion of label/annotation names and API group names must be a DNS subdomain (lower-case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character).

The suffix portion of label/annotation names is more free-form. We use lower-case characters and digits, with logical words separated by dashes. We do not use periods, upper-case characters, or underscores.

<examples>

Curation: source control

All identifiers will be curated via revision-controlled files in git, hosted under <TBD> The directory structure is a Java-style (reverse-DNS) hierarchy representing the identifier prefix. The files are named identifiers.yaml in each directory, and each file contains a single record of the following schema (expressed here in Go syntax):

struct {
   Description string   // short justification for this prefix
    Names []struct {
        Key string // exact name being claimed
        Type string // data type of the value (int, string, JSON-encoded
list, etc)
        Context string // where it is used (Node annotation, API group, etc)
        Description string // short description of what it is for
        DocsLink string // a link to relevant code/docs (github, etc)
    }
}

TBD: Should this dir attempt to accumulate existing identifiers?

Sub-Scoping

We do not want all identifiers to be directly under these domains, though we may want some. The question then arises of what convention to use for sub-scoped prefixes. Again, lack of convention has led to many different forms being used.

Sub-scoping is intended to delegate authority to relevant teams/organizations.

Example: networking.k8s.io

While the details of exact names within sub-scopes are left to the owning organizations, there are some guidelines that should be followed:

1) Do not embed development lifecycle information (e.g. alpha/beta) into names. Historically we have rarely abandoned features, but the name pattern forces users to update their clusters without providing any real value.

It's less of a big deal alpha->beta because people SHOULDN'T be using alpha for "real" (but they do). For beta->GA though, many users use beta things for real. If we force them to go and find and change the places they used a beta-named annotation, it's likely to end up in a breakage for them if they forget or they miss the window. This is aligned with the move away from annotations as pre-GA would-be fields.

Counter-example: alpha.group.k8s.io/new-feature

2) Do not embed particular resource names (e.g. ingress, pod) into label/annotation names. It doesn’t clarify what the label/annotation means, and it’s not uncommon to use the same annotation on multiple resources.

Counter-example: ingress.networking.k8s.io/ingress-feature

3) Do not embed values into keys (e.g. policies, namespace names). The net cardinality of names should be relatively low, while the cardinality of the values can be high.

Counter-example: something.k8s.io/my-namespace = “true”

sftim commented 3 years ago

This sounds like something that would be good to mirror into https://k8s.dev/ The assigned identifiers list could enhance or replace https://kubernetes.io/docs/reference/labels-annotations-taints/

aojea commented 3 years ago

I was hoping to institute something like this

how can we put the ball rolling then, who has to approve and where should we store the registry?

thockin commented 3 years ago

I think we should make a new git repo, e.g. "kubernetes/names" or something like that, document the schema, and start seeding it with all the apigroups and labels that we can find. And add OWNERS files along the way. :)

spiffxp commented 3 years ago

/priority backlog

k8s-triage-robot commented 2 years ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

k8s-triage-robot commented 2 years ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

ameukam commented 2 years ago

/remove-lifecycle rotten /lifecycle frozen