✨ (go/v4): Add custom k8s linter for logs to promote better observability by camilamacedo86 · Pull Request #5396 · kubernetes-sigs/kubebuilder

camilamacedo86 · 2026-01-26T09:29:34Z

What this PR does

Adds the custom linter sigs.k8s.io/logtools/logcheck to validate logs in Kubebuilder scaffolds.

This linter checks for common problematic logging scenarios and fails CI with actionable errors. Example failure output:
https://github.com/kubernetes-sigs/kubebuilder/actions/runs/21430987832/job/61710036984?pr=5396

Why we’re doing this

We checked with the logcheck maintainers and, while adoption is relatively low, the project appears stable and maintained:
https://kubernetes.slack.com/archives/C020CCMUEAX/p1769592452395209

Given there have been no reported bugs since 2024, it seems like a good fit for improving the quality of scaffolded logging patterns in Kubebuilder.

Links

Fixes: #5330

camilamacedo86 · 2026-01-28T09:55:06Z

docs/book/src/multiversion-tutorial/testdata/project/internal/controller/cronjob_controller.go

 				log.Error(err, "unable to delete old successful job", "job", job)
 			} else {
-				log.V(0).Info("deleted old successful job", "job", job)
+				log.V(1).Info("deleted old successful job", "job", job)


Fix issue found in the docs samples within

camilamacedo86 · 2026-01-28T09:55:12Z

docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller.go

 				log.Error(err, "unable to delete old successful job", "job", job)
 			} else {
-				log.V(0).Info("deleted old successful job", "job", job)
+				log.V(1).Info("deleted old successful job", "job", job)


Fix issue found in the docs samples within

camilamacedo86 · 2026-01-28T09:55:20Z

hack/docs/internal/cronjob-tutorial/controller_implementation.go

 				log.Error(err, "unable to delete old successful job", "job", job)
 			} else {
-				log.V(0).Info("deleted old successful job", "job", job)
+				log.V(1).Info("deleted old successful job", "job", job)


Fix issue found in the docs samples within

mloskot

Great stuff, thank you!

mloskot · 2026-01-28T10:23:06Z

pkg/plugins/golang/v4/scaffolds/init.go

-				log.Warn("Unable to find boilerplate file. "+
-					"This file is used to generate the license header in the project. "+
-					"Note that controller-gen will also use this. Therefore, ensure that you "+
-					"add the license file or configure your project accordingly.",
+				log.Warn("Unable to find boilerplate file "+
+					"used to generate the license header in the project "+
+					"Note that controller-gen will also use this Therefore ensure that you "+
+					"add the license file or configure your project accordingly",


This seems like a dup change from PR #5406
See also my #5406 (comment)

Thank you .. it should not be part of the changes in this PR.
Out of scope.

…ability Assisted-by: Cursor

camilamacedo86 · 2026-01-29T11:43:28Z

@vitorfloriano any reason for we not LGTM this one?
WDYT?

vitorfloriano

I was a bit unsure at first because we use log/slog in Kubebuilder itself, but turns out the scaffolds use the logger from controller-runtime, which use logr and klog, so the linter works for the scaffolds.

\lgtm

k8s-ci-robot · 2026-01-29T12:13:05Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86, vitorfloriano

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

camilamacedo86 · 2026-01-29T12:38:20Z

I was a bit unsure at first because we use log/slog in Kubebuilder itself, but turns out the scaffolds use the logger from controller-runtime, which use logr and klog, so the linter works for the scaffolds.

We were able to reproduce the issue as well, and it shows up in our logs, so the current setup appears to be working correctly on our side.
That said, I’m going to raise a question for C+R: why aren’t we using klog here? Since Kubernetes uses klog, we often prefer to align with Kubernetes standards—so understanding the reasoning would help.

mloskot · 2026-01-29T12:48:33Z

@camilamacedo86

why aren’t we using klog here? Since Kubernetes uses klog

Long ago I asked similar question on the Slack channel #klog and I think you may find the answers I received there from @pohly (*) informative in the context here, quoting:

In Kubernetes we are moving away from using "traditional" klog towards structured, contextual logging via the go-logr API.
See https://github.com/kubernetes/component-base/tree/master/logs/example for an example that enables -v/-vmodule and JSON log output.
(...) klog has lots of command line flags and function calls which are not used and not recommended by Kubernetes.

(*) I hope Patrick doesn't mind the mention, but I wanted to include persistent reference to source of that quote - I'm not 100% if the history of the Kubernetes Slack space persist.

camilamacedo86 · 2026-01-29T13:17:51Z

@mloskot I understand the the linter still valid right?
I will ask for its mantainers too but let me know if you see any reason for not

camilamacedo86 · 2026-01-29T14:41:05Z

/override pull-kubebuilder-e2e-k8s-1-34-0

k8s-ci-robot · 2026-01-29T14:41:09Z

@camilamacedo86: Overrode contexts on behalf of camilamacedo86: pull-kubebuilder-e2e-k8s-1-34-0

Details

In response to this:

/override pull-kubebuilder-e2e-k8s-1-34-0

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

mloskot · 2026-01-29T16:43:43Z

@camilamacedo86 I'd expect the linter to be still valid, but I don't know for sure as I did not dig the topic of future of klog in K8s any further.

vitorfloriano · 2026-01-29T17:25:41Z

I believe logr+klog was preferred in Kubernetes to avoid breaking changes. It seems that by passing the logger by context (contextual logging), they could work around that constraint. That's what I understood from KEP 3077.

log/slog was not considered a viable alternative because it would represent a breaking change in the API of tools like controller-runtime, as per this consideration in KEP 3077:

Use log/slog instead of klog+logr

This isn't viable because slog doesn't provide a mechanism to pass a logger through a context. Therefore it would not be possible to support contextual logging in packages like client-go where adding an explicit logger parameter would be a major API break.

But that's just my reading of the whole thing.

mloskot · 2026-01-29T17:31:06Z

@vitorfloriano Thanks for those references. It looks like there was a plan, that had changed along the way. Here is the part that, I think, can be considered as an update to the quote I posted in #5396 (comment), in this section:

Clean separation of contextual logging and traditional klog logging:

The initial revision of this KEP described a plan for moving all code for contextual logging into a k8s.io/klogr repository (...) However, that transition would have been complicated (...) Therefore the scope of the KEP was reduced from "remove dependency on klog" to "remove dependency on global logger in klog".

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 26, 2026

k8s-ci-robot requested review from varshaprasad96 and vitorfloriano January 26, 2026 09:29

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. approved Indicates a PR has been approved by an approver from all required OWNERS files. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jan 26, 2026

camilamacedo86 force-pushed the log-linter-check branch from bf6b0ac to 541aa84 Compare January 28, 2026 06:44

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jan 28, 2026

camilamacedo86 force-pushed the log-linter-check branch from 541aa84 to 81c71c5 Compare January 28, 2026 07:08

k8s-ci-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jan 28, 2026

camilamacedo86 force-pushed the log-linter-check branch 2 times, most recently from 9b1bdaf to f9f164b Compare January 28, 2026 08:08

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jan 28, 2026

camilamacedo86 force-pushed the log-linter-check branch 2 times, most recently from 1261225 to 72064ab Compare January 28, 2026 08:11

camilamacedo86 changed the title ~~WIP: (chore): Add linter for logs~~ ✨ (go/v4): Add custom k8s linter for logs to promote better observability Jan 28, 2026

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 28, 2026

camilamacedo86 changed the title ~~✨ (go/v4): Add custom k8s linter for logs to promote better observability~~ ✨ (go/v4): Add custom k8s linter for logs to promote better observability Jan 28, 2026

camilamacedo86 force-pushed the log-linter-check branch from 72064ab to 83868c2 Compare January 28, 2026 08:34

camilamacedo86 changed the title ~~✨ (go/v4): Add custom k8s linter for logs to promote better observability~~ WIP ✨ (go/v4): Add custom k8s linter for logs to promote better observability Jan 28, 2026

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 28, 2026

camilamacedo86 force-pushed the log-linter-check branch 3 times, most recently from d1006e6 to 4f14542 Compare January 28, 2026 09:23

camilamacedo86 changed the title ~~WIP ✨ (go/v4): Add custom k8s linter for logs to promote better observability~~ ✨ (go/v4): Add custom k8s linter for logs to promote better observability Jan 28, 2026

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 28, 2026

camilamacedo86 commented Jan 28, 2026

View reviewed changes

mloskot reviewed Jan 28, 2026

View reviewed changes

camilamacedo86 force-pushed the log-linter-check branch from 4f14542 to ff2b12b Compare January 29, 2026 08:15

chore(go/v4): Add custom k8s linter for logs to promote better observ…

75d7e96

…ability Assisted-by: Cursor

camilamacedo86 force-pushed the log-linter-check branch from ff2b12b to 75d7e96 Compare January 29, 2026 10:02

vitorfloriano approved these changes Jan 29, 2026

View reviewed changes

camilamacedo86 added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jan 29, 2026

k8s-ci-robot merged commit 15eb316 into kubernetes-sigs:master Jan 29, 2026
40 of 41 checks passed

camilamacedo86 deleted the log-linter-check branch January 29, 2026 14:56

camilamacedo86 mentioned this pull request Feb 8, 2026

Release v4.12.0: Help test changes and review before the release + planner #5451

Closed

maker2413 mentioned this pull request Feb 20, 2026

Generated lint workflow failing due to golangci-lint-action using version 8 #5492

Closed

Conversation

camilamacedo86 commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Why we’re doing this

Links

Uh oh!

camilamacedo86 Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

mloskot left a comment

Choose a reason for hiding this comment

Uh oh!

mloskot Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 commented Jan 29, 2026

Uh oh!

vitorfloriano left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Jan 29, 2026

Uh oh!

camilamacedo86 commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mloskot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camilamacedo86 commented Jan 29, 2026

Uh oh!

camilamacedo86 commented Jan 29, 2026

Uh oh!

k8s-ci-robot commented Jan 29, 2026

Uh oh!

Uh oh!

mloskot commented Jan 29, 2026

Uh oh!

vitorfloriano commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Use log/slog instead of klog+logr

Uh oh!

mloskot commented Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

camilamacedo86 commented Jan 26, 2026 •

edited

Loading

camilamacedo86 commented Jan 29, 2026 •

edited

Loading

mloskot commented Jan 29, 2026 •

edited

Loading

vitorfloriano commented Jan 29, 2026 •

edited

Loading