diff --git a/keps/sig-cluster-lifecycle/0014-20180707-componentconfig-api-types-to-staging.md b/keps/sig-cluster-lifecycle/0014-20180707-componentconfig-api-types-to-staging.md index 3c12dbf9e..ec2212945 100644 --- a/keps/sig-cluster-lifecycle/0014-20180707-componentconfig-api-types-to-staging.md +++ b/keps/sig-cluster-lifecycle/0014-20180707-componentconfig-api-types-to-staging.md @@ -1,7 +1,7 @@ --- kep-number: 17 title: Moving ComponentConfig API types to staging repos -status: provisional +status: implementable authors: - "@luxas" - "@sttts" @@ -25,7 +25,7 @@ approvers: editor: name: "@luxas" creation-date: 2018-07-07 -last-updated: 2018-07-07 +last-updated: 2018-08-10 --- # Moving ComponentConfig API types to staging repos @@ -127,7 +127,7 @@ types of the core components’ ComponentConfig in a top-level `config/` package ### Non-goals * Graduate the API versions - * For v1.12, we’re working incrementally and will keep the versions of the existing ComponentConfigs. + * For v1.12, we’re working incrementally and will keep the API versions of the existing ComponentConfigs. * Do major refactoring of the ComponentConfigs. This PR is about code moves, not about re-defining the structure. We will do the latter in follow-ups. * Change the components to support reading a config file, do flag precedence correctly or add e2e testing * Further, the "load-versioned-config-from-flag" feature in this proposal *should not* be confused with the @@ -143,7 +143,14 @@ types of the core components’ ComponentConfig in a top-level `config/` package make the command support loading configuration files. * The new repo can reuse the generic types from the to-be-created, `k8s.io/controller-manager` repo eventually. * Meanwhile, the cloud-controller-manager will reference the parts it needs from the main repo, and live privately in `cmd/cloud-controller-manager` -* Add further defaulting for the external types. The defaulting strategy decision is post-poned, outside of this KEP. +* Expose defaulting functions for the external ComponentConfig types in `k8s.io/{component}/config` packages. + * Defaulting functions will still live local to the component in e.g. `k8s.io/kubernetes/pkg/{component}/apis/config/{version}` and be + registered in the default scheme, but won't be publicly exposed in the `k8s.io/{component}` repo. + * The only defaulting functions that are published to non-core repos are for the shared config types, in other words in + `k8s.io/{apimachinery,apiserver,controller-manager}/pkg/apis/config/{version}`, but **they are not registered in the scheme by default** + (with the normal `SetDefault_Foo` method and the `addDefaultingFunc(scheme *runtime.Scheme) { return RegisterDefaults(scheme) }` function). + Instead, there will be `RecommendedDefaultFoo` methods exposed, which the consumer of the shared types may or may not manually run in + `SetDefaults_Bar` functions (where `Bar` wraps `Foo` as a field). ### Related proposals and further references @@ -167,7 +174,7 @@ types of the core components’ ComponentConfig in a top-level `config/` package * Like `k8s.io/api` * Internal types: `k8s.io/kubernetes/pkg/{component}/apis/config` * Alternatives, if applicable - * `k8s.io/{component}/pkg/apis/config` (preferred) + * `k8s.io/{component}/pkg/apis/config` (preferred, in the future) * `k8s.io/kubernetes/cmd/{component}/app/apis/config` * If dependencies allow it, we can move them to `k8s.io/{component}/pkg/apis/config/types.go`. Not having the external types there is intentional because the `pkg/` package tree is considered as "on-your-own-risks / no code compatibility guarantees", while `config/` is considered as a code API. * Internal scheme package: `k8s.io/kubernetes/pkg/{component}/apis/config/scheme/scheme.go` @@ -175,15 +182,22 @@ types of the core components’ ComponentConfig in a top-level `config/` package * For the move to a staging repo to be possible, the external API package must not depend on the core repo. * Hence, all non-staging repo dependencies need to be removed/resolved before the package move. * Conversions from the external type to the internal type will be kept in `{internal_api_path}/{external_version}`, like for `k8s.io/api` - * Defaulting code will be kept in this package, next to the conversions, if it already exists. We keep the decision about the destiny of defaulting open in this KEP. + * Defaulting code will be kept in this package, besides the conversion functions. + * The defaulting code here is specific for the usage of the component, and internal by design. If there are defaulting functions we + feel would be generally useful, they might be exposed in `k8s.io/{component}/config/{version}/defaults.go` as `RecommendedDefaultFoo` + functions that can be used by various consumers optionally. + * Add at least some kind of minimum validation coverage for the types (e.g. ranges for integer values, URL scheme/hostname/port parsing, + DNS name/label/domain validation) in the `{internal_api_path}/validation` package, targeting the internal API version. The consequence of + these validations targeting the internal type is that they can't be exposed in the `k8s.io/{component}` repo, but publishing more + functionality like that is out of scope for this KEP and left as a future task. * Create a "shared types"-package with structs generic to all or many componentconfig API groups, in the `k8s.io/apimachinery`, `k8s.io/apiserver` and `k8s.io/controller-manager` repos, depending on the struct. * Location: `k8s.io/{apimachinery,apiserver,controller-manager}/pkg/apis/config/{,v1alpha1}` - * These aren’t "real" API groups, but have both internal and external versions + * These aren’t "real" API groups, but they have both internal and external versions * Conversions and internal types are published to the staging repo. - * Defaults are moved into the leaf groups using them as much as possible. -* Remove the monolithic `componentconfig/v1alpha1` API group + * Defaulting functions are of the `RecommendedDefaultFoo` format and opt-ins for consumers. No defaulting functions are registered in the scheme. +* Remove the monolithic `componentconfig/v1alpha1` API group (`pkg/apis/componentconfig`) * Enable the staging bot to create the Github repos -* We do not add further defaulting, but merely keep the minimum defaulting in-place to keep the current behaviour, but remove those defaulting funcs which are not used today. +* Add API roundtrip (fuzzing), defaulting, conversion, JSON tag consistency and validation tests. ### Migration strategy per component or k8s.io repo @@ -192,7 +206,7 @@ types of the core components’ ComponentConfig in a top-level `config/` package * **Not a "real" API group, instead shared packages only with both external and internal types.** * **External Package with defaulting (where absolutely necessary) & conversions**: `k8s.io/apimachinery/pkg/apis/config/v1alpha1/types.go` * **Internal Package**: `k8s.io/apimachinery/pkg/apis/config/types.go` -* Structs to be hosted: +* Structs to be hosted initially: * ClientConnectionConfiguration * Assignee: @hanxiaoshuai @@ -201,9 +215,9 @@ types of the core components’ ComponentConfig in a top-level `config/` package * **Not a "real" API group, instead shared packages only with both external and internal types.** * **External Package with defaulting (where absolutely necessary) & conversions**: `k8s.io/apiserver/pkg/apis/config/v1alpha1/types.go` * **Internal Package**: `k8s.io/apiserver/pkg/apis/config/types.go` -* Structs to be hosted: - * LeaderElectionConfiguration - * DebuggingConfiguration +* Structs to be hosted initially: + * `LeaderElectionConfiguration` + * `DebuggingConfiguration` * later to be created: SecureServingConfiguration, AuthenticationConfiguration, AuthorizationConfiguration, etc. * Assignee: @hanxiaoshuai @@ -245,7 +259,7 @@ types of the core components’ ComponentConfig in a top-level `config/` package * **External Package with defaulting (where absolutely necessary) & conversions**: `k8s.io/controller-manager/pkg/apis/config/v1alpha1/types.go` * **Internal Package**: `k8s.io/controller-manager/pkg/apis/config/types.go` * Will host structs: - * GenericComponentConfiguration (should be renamed to GenericControllerManagerConfiguration at the same time) + * `GenericComponentConfiguration` (which will be renamed to `GenericControllerManagerConfiguration`) * Assignee: @stewart-yu #### kube-controller-manager changes @@ -304,13 +318,15 @@ Dep supports the import of sub-packages without inheriting dependencies from out Objective: Done for v1.12 Implementation order: -* Start with the apiserver and apimachinery shared config repos, copy over the necessary structs as needed and create the external and internal API packages. -* Start with the scheduler as the first component. -* One PR for moving `KubeSchedulerConfiguration` to `staging/src/k8s.io/kube-scheduler/config/v1alpha1/types.go`, and the internal type to `pkg/scheduler/apis/config/types.go`. - * Set up the conversion for the external type by creating the package `pkg/scheduler/apis/config/v1alpha1`, without `types.go`, like how `k8s.io/api` is set up. - * This should be a pure code move. +* Start with copying over the necessary structs to the `k8s.io/apiserver` and `k8s.io/apimachinery ` shared config packages, with external and internal API versions. The defaulting pattern for these types are of the `RecommendedDefaultFoo` form, in other words defaulting is not part of the scheme. +* Remove as many unnecessary references to `pkg/apis/componentconfig` from the rest of the core repo as possible +* Make the types in `pkg/apis/componentconfig` reuse the newly-created types in `k8s.io/apiserver` and `k8s.io/apimachinery `. +* Start with the scheduler as the first component to be moved out. + * One PR for moving `KubeSchedulerConfiguration` to `staging/src/k8s.io/kube-scheduler/config/v1alpha1/types.go`, and the internal type to `pkg/scheduler/apis/config/types.go`. + * Set up the conversion for the external type by creating the package `pkg/scheduler/apis/config/v1alpha1`, without `types.go`, like how `k8s.io/api` is set up. + * This should be a pure code move. * Set up staging publishing bot (async, non-critical) -* The kubelet, kube-proxy and controller-manager follow, each one independently. +* The kubelet, kube-proxy and kube-controller-manager types follow, each one independently. ### OWNERS files for new packages and repos