component-base: make LoggingConfiguration a single-version API #105797
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
k8s-ci-robot
added
release-note-none
k8s-ci-robot
added
sig/api-machinery
pohly
force-pushed
the
log-configuration-feature-gates
branch
from
0fb71f7
to
02acd54
Compare
|
This PR may require API review. If so, when the changes are ready, complete the pre-review checklist and request an API review. Status of requested reviews is tracked in the API Review project. |
pohly
force-pushed
the
log-configuration-feature-gates
branch
from
02acd54
to
8640e36
Compare
|
/remove-sig api-machinery |
k8s-ci-robot
removed
the
sig/api-machinery
liggitt
reviewed
Jun 17, 2022
liggitt
reviewed
Jun 17, 2022
liggitt
reviewed
Jun 17, 2022
pohly
force-pushed
the
log-configuration-feature-gates
branch
from
7d7cd6f
to
581b948
Compare
After the removal of the dynamic kubelet configuration feature it became
possible to initialize logging directly after configuration parsing. The
advantage is that logs emitted by
kubeletconfigvalidation.ValidateKubeletConfiguration and
`klog.InfoS("unsupported configuration ...` already use the intended log
output.
After the code was originally added, Run was replaced by RunE. Taking advantage
of that and returning an error is cleaner.
StartFlushDaemon can be called more than once. We can take advantage of that an eliminate the tracking of where we need to start it.
|
lgtm, just needs the rebase. I'd probably leave the distinct commits rather than squashing this one |
Making the LoggingConfiguration part of the versioned component-base/config API
had the theoretic advantage that components could have offered different
configuration APIs with experimental features limited to alpha versions (for
example, sanitization offered only in a v1alpha1.KubeletConfiguration). Some
components could have decided to only use stable logging options.
In practice, this wasn't done. Furthermore, we don't want different components
to make different choices regarding which logging features they offer to
users. It should always be the same everywhere, for the sake of consistency.
This can be achieved with a saner Go API by dropping the distinction between
internal and external LoggingConfiguration types. Different stability levels of
indidividual fields have to be covered by documentation (done) and potentially
feature gates (not currently done).
Advantages:
- everything related to logging is under component-base/logs;
previously this was scattered across different packages and
different files under "logs" (why some code was in logs/config.go
vs. logs/options.go vs. logs/logs.go always confused me again
and again when coming back to the code):
- long-term config and command line API are clearly separated
into the "api" package underneath that
- logs/logs.go itself only deals with legacy global flags and
logging configuration
- removal of separate Go APIs like logs.BindLoggingFlags and
logs.Options
- LogRegistry becomes an implementation detail, with less code
and less exported functionality (only registration needs to
be exported, querying is internal)
It is useful to have the ability to control whether alpha or beta features are enabled. We can group features under LoggingAlphaOptions and LoggingBetaOptions because the configuration is designed so that each feature individually must be enabled via its own option. Currently, the JSON format itself is beta (graduated in 1.23) but additional options for it were only added in 1.23 and thus are still alpha: $ go run ./staging/src/k8s.io/component-base/logs/example/cmd/logger.go --logging-format=json --log-json-split-stream --log-json-info-buffer-size 1M --feature-gates LoggingBetaOptions=false [format: Forbidden: Log format json is BETA and disabled, see LoggingBetaOptions feature, options.json.splitStream: Forbidden: Feature LoggingAlphaOptions is disabled, options.json.infoBufferSize: Forbidden: Feature LoggingAlphaOptions is disabled] $ go run ./staging/src/k8s.io/component-base/logs/example/cmd/logger.go --logging-format=json --log-json-split-stream --log-json-info-buffer-size 1M [options.json.splitStream: Forbidden: Feature LoggingAlphaOptions is disabled, options.json.infoBufferSize: Forbidden: Feature LoggingAlphaOptions is disabled] This is the same approach that was taken for CPUManagerPolicyAlphaOptions and CPUManagerPolicyBetaOptions. In order to test this without modifying the global feature gate in a test file, ValidateKubeletConfiguration must take a feature gate as argument.
API types are only supposed to have methods related to serialization.
pohly
force-pushed
the
log-configuration-feature-gates
branch
from
581b948
to
4c6338a
Compare
k8s-ci-robot
removed
the
needs-rebase
|
/lgtm |
k8s-ci-robot
added
the
lgtm
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: liggitt, pohly The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
Agreed. The commit messages have the rationale behind each commit, which is easier to correlate with the code when the commits are kept separate. I've rebased, let's see whether I caught all new code that needed changes (like staging/src/k8s.io/component-base/logs/json/klog_test.go and test/integration/logs/functional/json/output_test.go, which had new references to the old config.VerbosityLevel). |
|
As an api change, shouldn't this have a release note? |
no, there were no externally visible changes to existing accepted config file content |
k8s-ci-robot
added
release-note
|
There seem to be different opinions about "api change". I was told in https://kubernetes.slack.com/archives/C2C40FMNF/p1650979139995909 that "API change" also includes Go API changes in our staging repos. From that perspective, a release note would be needed here, so I added one. I don't think that this is done consistently and I keep forgetting about it myself, not the least because I, as a developer who consumes Kubernetes code, don't read the changelog for a release to figure out if my code breaks when I update dependencies. I rather expect obvious compile errors and then figure out by reading the code what I need to change. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
/kind cleanup
/kind api-change
What this PR does / why we need it:
Making the LoggingConfiguration part of the versioned component-base/config API
had the theoretic advantage that components could have offered different
configuration APIs with experimental features limited to alpha versions (for
example, sanitization offered only in a v1alpha1.KubeletConfiguration). Some
components could have decided to only use stable logging options.
In practice, this wasn't done. Furthermore, we don't want different components
to make different choices regarding which logging features they offer to
users. It should always be the same everywhere, for the sake of consistency.
This can be achieved by dropping the distinction between
internal and external LoggingConfiguration types. The Go API becomes simpler, too.
Different stability levels of individual fields have to be covered by documentation and
feature gates.
Advantages:
everything related to logging is under component-base/logs;
previously this was scattered across different packages and
different files under "logs" (why some code was in logs/config.go
vs. logs/options.go vs. logs/logs.go always confused me again
and again when coming back to the code):
long-term config and command line API are clearly separated
into the "api" package underneath that
logs/logs.go itself only deals with legacy global flags and
logging configuration
removal of separate Go APIs like logs.BindLoggingFlags and
logs.Options
LogRegistry becomes an implementation detail, with less code
and less exported functionality (only registration needs to
be exported, querying is internal)
Special notes for your reviewer:
This is an alternative to PR #105448
Feature checking is implemented as in other components by accessing the global default feature gate. For that, that instance has to be moved to component-base to avoid circular dependencies. The alternative is to pass in a gate instance for checking, but that means changing the API without providing any tangible advantage. That approach has been implemented for comparison in https://github.com/pohly/kubernetes/commits/log-configuration-feature-gates-optional and (for some other PR) in https://github.com/pohly/kubernetes/commits/log-contextual-feature-gate-optional. See https://kubernetes.slack.com/archives/C0EG7JC6T/p1644329116043899?thread_ts=1643908087.471269&cid=C0EG7JC6T
Does this PR introduce a user-facing change?