A table of contents is helpful for quickly jumping to sections of a KEP and for highlighting any additional information provided beyond the standard KEP template.
Table of Contents
Kubeadm uses MasterConfiguraton for two distinct but similar operations: Initialising a new cluster and upgrading an existing cluster.
The former is typically created by hand by an administrator.
It is stored on disk and passed to
kubeadm init via command line flag.
The latter is produced by kubeadm using supplied configuration files, command line options, and internal defaults.
It will be stored in a ConfigMap so upgrade operations can find.
Right now the configuration format is unversioned. This means configuration file formats can change between kubeadm versions and there’s no safe way to update the configuration format.
We propose a stable versioning of this configuration,
v1alpha2 and eventually
Version information will be mandatory going forward, both for user-generated configuration files and machine-generated configuration maps.
There as an existing document describing current Kubernetes best practices around component configuration.
After 1.10.0, we discovered a bug in the upgrade process.
MasterConfiguraton embedded a struct that had changed, which caused a backwards-incompatible change to the configuration format.
kubeadm upgrade to fail, because a newer version of kubeadm was attempting to deserialise an older version of the struct.
Because the configuration is often written and read by different versions of kubeadm compiled by different versions of kubernetes, it’s very important for this configuration file to be well-versioned.
The concrete proposal is as follows.
v1alpha2directory mirroring the existing
v1alpha1, which matches the 1.10 schema. This version need not duplicate the file as well.
In the past, the haphazard nature of the versioning system has meant it was hard to provide strong guarantees between versions. Implementing strong version guarantees mean any given configuration generated in the past by kubeadm will work with a future version of kubeadm. Deprecations can happen in the future in well-regulated ways.
Having a configuration file that changes without notice makes it very difficult to write software that integrates with kubeadm. By providing strong version guarantees, we can guarantee that the files these tools produce will work with a given version of kubeadm.
The incident that caused the breakage in alpha wasn’t a field changed it Kubeadm, it was a struct referenced inside the
By completely owning our own configuration, changes in the rest of the project can’t unknowingly affect us.
When we do need to interface with the rest of the project, we will do so explicitly in code and be protected by the compiler.
Moving to a strongly versioned configuration from a weakly versioned one must be done carefully so as not break kubeadm for existing users.
We can start requiring versions of the existing
v1alpha1 format, issuing warnings to users when Version and Kind aren’t present.
These fields can be used today, they’re simply ignored.
In the future, we could require them, and transition to using
This KEP can be considered complete once all currently supported versions of Kubeadm write out
Rather than creating our own copies of all structs in the
MasterConfiguration struct, we could instead continue embedding the structs.
To provide our guarantees, we would have to invest a lot more in automated testing for upgrades.