KEP-2337: k8s.io Group Protection

Implementation History
STABLE Implemented
Created 2019-06-12
Updated 2019-07-03
Latest 0.0
Ownership
Owning SIG
SIG API Machinery
Participating SIGs
SIG API MachinerySIG Architecture
Primary Authors
@deads2k

k8s.io Group Protection

Table of Contents

Summary

API groups are organized by namespace, similar to java packages. authorization.k8s.io is one example. When users create CRDs, they get to specify an API group and their type will be injected into that group by the kube-apiserver.

The *.k8s.io or *.kubernetes.io groups are owned by the Kubernetes community and protected by API review (see What APIs need to be reviewed , to ensure consistency and quality. To avoid confusion in our API groups and prevent accidentally claiming a space inside of the kubernetes API groups, the kube-apiserver needs to be updated to protect these reserved API groups.

This KEP proposes adding an api-approved.kubernetes.io annotation to CustomResourceDefinition. This is only needed if the CRD group is k8s.io, kubernetes.io, or ends with .k8s.io, .kubernetes.io. The value should be a link to a to a URL where the current spec was approved, so updates to the spec should also update the URL.

metadata:
  annotations:
    "api-approved.kubernetes.io": "https://github.com/kubernetes/kubernetes/pull/78458"

Motivation

  • Prevent accidentally including an unapproved API in community owned API groups

Goals

  • Ensure API consistency.
  • Prevent accidentally claiming reserved named.

Non-Goals

  • Prevent malicious users from claiming reserved names.

Proposal

This KEP proposes adding an api-approved.kubernetes.io annotation to CustomResourceDefinition. This is only needed if the CRD group is k8s.io, kubernetes.io, or ends with .k8s.io, .kubernetes.io. The value should be a link to the pull request where the API has been approved. If the API is unapproved, you may set the annotation to a string starting with "unapproved". For instance, "unapproved, temporarily squatting or "unapproved, experimental-only". This is discouraged.

metadata:
  annotations:
    "api-approved.kubernetes.io": "https://github.com/kubernetes/kubernetes/pull/78458"

metadata:
  annotations:
    "api-approved.kubernetes.io": "unapproved, experimental-only"

This field is used by new kube-apiservers to set the KubeAPIApproved condition.

  1. If a new server sees a CRD for a resource in a kube group and sees the annotation set to a URL, it will set the KubeAPIApproved condition to true.
  2. If a new server sees a CRD for a resource in a kube group and sees the annotation set to "unapproved.*", it will set the KubeAPIApproved condition to false.
  3. If a new server sees a CRD for a resource in a kube group and does not see the annotation, it will set the KubeAPIApproved condition to false.
  4. If a new server sees a CRD for a resource outside a kube group, it does not set the KubeAPIApproved condition at all.

In v1, this annotation will be required in order to create a CRD for a resource in one of the kube API groups. If the KubeAPIApproved condition is false, the condition message will include a link to https://github.com/kubernetes/enhancements/pull/1111 for reference.

Behavior of new clusters

  1. Current CRD for a resource in the kube group already in API is missing valid api-approved.kubernetes.io or has set the value to "unapproved.*" - KubeAPIApproved condition will be false.
  2. CRD for a resource in the kube group creating via CRD.v1beta1 is missing valid api-approved.kubernetes.io - create as normal. This ensures compatibility. KubeAPIApproved condition will be false.
  3. CRD for a resource in the kube group creating via CRD.v1 is missing valid api-approved.kubernetes.io - fail validation and do not store in etcd.
  4. CRD for a resource outside the kube group creating via CRD.v1 is contains the api-approved.kubernetes.io - fail validation and do not store in etcd.
  5. In CRD.v1, remove a required api-approved.kubernetes.io - fail validation.
  6. In all versions, any update that does not change the api-approved.kubernetes.io will go through our current validation rules.

Behavior of old clusters

  1. Nothing changes. The old clusters will persist and keep the annotation

This doesn’t actively prevent bad actors from simply setting the annotation, but it does prevent accidentally claiming an inappropriate name.

What to do if you accidentally put an unapproved API in a protected group

  1. Get the current state and future changes approved. For community projects, this is the best choice if the current state is approvable.
  2. If there are structural problems with the API’s current state that prevent approval, you have two choices.
    1. restructure in a new version, maintaining a conversion webhook, and plan to stop serving the old version. There are some cases where this may not work if the changes are not roundtrippable, but they should be rare.
    2. restructure in a new API group. There will be no connection to existing data. This may be disruptive for non-alpha APIs, but these names are reserved and the process of API review has been in place for some time. The expectation is that this is the exceptional case of an exceptional case.
  3. Indicate that your API is unapproved by setting the "api-approved.kubernetes.io" annotation to something starting with unapproved. For instance, "unapproved, temporarily squatting or "unapproved, experimental-only".

References

Test Plan

blockers for GA:

  • Document in the release notes. The impact is very low

Graduation Criteria

  • the test plan is fully implemented for the respective quality level

Upgrade / Downgrade Strategy

  • annotations and conditions are always persisted. If set, they remain consistent. If unset, they also remain consistent.

Version Skew Strategy

  • annotations and conditions are always persisted. If set, they remain consistent. If unset, they also remain consistent.

Alternatives considered

Implementation History