Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

component-base: make LoggingConfiguration a single-version API #105797

Merged
merged 6 commits into from Jun 17, 2022

Conversation

pohly
Copy link
Contributor

@pohly pohly commented Oct 20, 2021

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?

The Go API for logging configuration in k8s.io/component-base was moved to k8s.io/component-base/logs/api/v1. The configuration file format and command line flags are the same as before.

@k8s-ci-robot k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/cleanup Categorizes issue or PR as related to cleaning up code, process, or technical debt. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API do-not-merge/needs-kind Indicates a PR lacks a `kind/foo` label and requires one. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. needs-priority Indicates a PR lacks a `priority/foo` label and requires one. area/dependency Issues or PRs related to dependency changes area/kubelet and removed do-not-merge/needs-kind Indicates a PR lacks a `kind/foo` label and requires one. labels Oct 20, 2021
@k8s-ci-robot k8s-ci-robot requested review from andyxning, damemi and a team October 20, 2021 17:43
@k8s-ci-robot k8s-ci-robot added sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. sig/cluster-lifecycle Categorizes an issue or PR as relevant to SIG Cluster Lifecycle. sig/instrumentation Categorizes an issue or PR as relevant to SIG Instrumentation. sig/node Categorizes an issue or PR as relevant to SIG Node. sig/scheduling Categorizes an issue or PR as relevant to SIG Scheduling. wg/structured-logging Categorizes an issue or PR as relevant to WG Structured Logging. and removed do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. labels Oct 20, 2021
@pohly pohly force-pushed the log-configuration-feature-gates branch from 0fb71f7 to 02acd54 Compare October 20, 2021 18:08
@k8s-triage-robot
Copy link

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 pohly force-pushed the log-configuration-feature-gates branch from 02acd54 to 8640e36 Compare October 20, 2021 19:23
@fedebongio
Copy link
Contributor

/remove-sig api-machinery

@k8s-ci-robot k8s-ci-robot removed the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Oct 21, 2021
@ehashman ehashman added this to Triage in SIG Node PR Triage Nov 1, 2021
@wgahnagl wgahnagl moved this from Triage to Needs Reviewer in SIG Node PR Triage Nov 3, 2021
@liggitt liggitt moved this from Changes requested to In progress in API Reviews Jun 13, 2022
Copy link
Member

@liggitt liggitt left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

all the updates look good. a couple questions on the flag wrapper nil cases, a couple nits, and a rebase needed, then this is good to go

thanks for all the work on this, I'm pretty happy with where this ended up

staging/src/k8s.io/component-base/logs/api/v1/options.go Outdated Show resolved Hide resolved
staging/src/k8s.io/component-base/logs/api/v1/options.go Outdated Show resolved Hide resolved
@liggitt liggitt moved this from In progress to API review completed, 1.25 in API Reviews Jun 17, 2022
@pohly pohly force-pushed the log-configuration-feature-gates branch from 7d7cd6f to 581b948 Compare June 17, 2022 18:04
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.
@liggitt
Copy link
Member

liggitt commented Jun 17, 2022

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 pohly force-pushed the log-configuration-feature-gates branch from 581b948 to 4c6338a Compare June 17, 2022 18:23
@pohly
Copy link
Contributor Author

pohly commented Jun 17, 2022

@k8s-ci-robot k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 17, 2022
@liggitt
Copy link
Member

liggitt commented Jun 17, 2022

/lgtm
/approve

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 17, 2022
@k8s-ci-robot
Copy link
Contributor

[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 /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jun 17, 2022
@pohly
Copy link
Contributor Author

pohly commented Jun 17, 2022

I'd probably leave the distinct commits rather than squashing this one

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).

@k8s-ci-robot k8s-ci-robot merged commit 26348b7 into kubernetes:master Jun 17, 2022
SIG Node PR Triage automation moved this from Needs Reviewer to Done Jun 17, 2022
@jberkus
Copy link

jberkus commented Jun 21, 2022

As an api change, shouldn't this have a release note?

@csantanapr

@liggitt
Copy link
Member

liggitt commented Jun 21, 2022

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 k8s-ci-robot added release-note Denotes a PR that will be considered when it comes time to generate release notes. and removed release-note-none Denotes a PR that doesn't merit a release note. labels Jun 22, 2022
@pohly
Copy link
Contributor Author

pohly commented Jun 22, 2022

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
Labels
api-review Categorizes an issue or PR as actively needing an API review. approved Indicates a PR has been approved by an approver from all required OWNERS files. area/apiserver area/code-generation area/dependency Issues or PRs related to dependency changes area/kubelet area/test cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API kind/cleanup Categorizes issue or PR as related to cleaning up code, process, or technical debt. lgtm "Looks good to me", indicates that a PR is ready to be merged. priority/important-longterm Important over the long term, but may not be staffed and/or may need multiple releases to complete. release-note Denotes a PR that will be considered when it comes time to generate release notes. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. sig/cluster-lifecycle Categorizes an issue or PR as relevant to SIG Cluster Lifecycle. sig/instrumentation Categorizes an issue or PR as relevant to SIG Instrumentation. sig/node Categorizes an issue or PR as relevant to SIG Node. sig/scheduling Categorizes an issue or PR as relevant to SIG Scheduling. sig/testing Categorizes an issue or PR as relevant to SIG Testing. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. triage/accepted Indicates an issue or PR is ready to be actively worked on. wg/structured-logging Categorizes an issue or PR as relevant to WG Structured Logging.
Projects
Status: API review completed, 1.25
Archived in project
Development

Successfully merging this pull request may close these issues.

None yet