docs: add third-party dependency update guide for agents - #18749
Open
rifelpet wants to merge 7 commits into
Open
docs: add third-party dependency update guide for agents#18749rifelpet wants to merge 7 commits into
rifelpet wants to merge 7 commits into
Conversation
Contributor
|
Skipping CI for Draft Pull Request. |
kubernetes-prow
Bot
added
the
do-not-merge/work-in-progress
Contributor
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
kubernetes-prow
Bot
added
cncf-cla: yes
Member
Author
|
/hold for feedback cc @hakman |
kubernetes-prow
Bot
added
the
do-not-merge/hold
Adds docs/dependency-updates.md, a reference for updating the third-party dependencies kOps pins, aimed at automated agents. Covers each pinning surface — Go modules and toolchain, build/lint tooling, GitHub Actions, addon manifests, node components, etcd, Kubernetes version support, OS images, and e2e scenario charts — naming for each the file that holds the version, the files coupled to it, the regeneration command, and the verification command. Two mechanisms are documented up front because nearly every recipe ends in one of them: pkg/assets/assetdata/, where a version bumped without a matching hash fails at "kops update cluster" time rather than at compile time, and hack/update-expected.sh for golden-file regeneration. Also documents the commit and PR conventions these changes follow, and the failure modes that have cost past dependency PRs. References are kept generic — no line numbers or specific versions — so the document stays accurate as pins move.
There is no pull-kops-verify job running `make verify`. Each Prow check is its own job invoking a single make target, and pull-kops-verify-generated resolves to just verify-crds. The GitHub Actions quick-ci job and the Prow presubmits are complementary rather than overlapping, so describe which verify targets each one actually covers. Verified against test-infra/config/jobs/kubernetes/kops.
The guide said these header comments are frequently stale and told the reader to fix the header to match the image tag. That is backwards. The header records which upstream revision the manifest body was derived from. Bumping a vendored addon is supposed to mean re-deriving the body from the new release and moving the header with it, so the two staying in agreement is the invariant. When they disagree the manifest has drifted and may be missing upstream changes that shipped with the newer image. Editing the header to match the image would assert a re-derivation that never happened and destroy the only record of what the body corresponds to. Say to re-derive instead, and warn against the shortcut.
The cleanup PRs changed several of the things this guide described: - the gofumpt scripts were removed, so both mentions go - the ko version is now single-sourced in the Makefile rather than repeated in two scripts - the @latest invocations are pinned, so the "known debt, leave them alone" note becomes "do not introduce one" - the tools module that imports k8s.io/kops now has a replace to the root
rifelpet
force-pushed
the
dep-updates-agents
branch
from
August 26, 2026 20:22
cb2e7e5 to
9938852
Compare
docs/contributing/vendoring.md described running make gomod and committing vendor/, go.mod and go.sum together, and keeping the dependency PR separate from feature work. All of that is in the Go modules section of the new dependency guide, which additionally covers the nested modules, the k8s.io staging set, the code-generator pin, and the verification commands. Rather than maintain two descriptions of the same workflow, drop the older one and its nav entry.
The old checklist was written for dep and Gopkg.toml, told the reader to update the default Docker version, and pointed at kube-up scripts for the CNI version and admission plugins. Most of its headings had no body. Replace it with the recipe the recent commits actually follow. The key point the old doc missed is that adding a minor is not one change: there is no allowlist of Kubernetes versions, so support arrives as several independent pull requests landing as each upstream artifact appears, while dropping the oldest minor is one large sweep. Point the dependency guide's Kubernetes section here rather than summarising the same procedure twice, and drop its claim that adding a minor is only a channel change.
The convention still holds; it does not need stating in the document.
rifelpet
marked this pull request as ready for review
August 27, 2026 10:42
kubernetes-prow
Bot
removed
the
do-not-merge/work-in-progress
Contributor
|
@rifelpet: The following test failed, say
Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR. DetailsInstructions 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. I understand the commands that are listed here. |
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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 this PR does / why we need it:
Adds
docs/dependency-updates.md, a reference for updating the third-party dependencies kOps pins, aimed at automated agents, plus a pointer to it fromAGENTS.md(mirroring howdocs/e2e-failure-troubleshooting.mdis wired up).kOps pins third-party versions across a lot of unrelated places, and most of them have coupled files that must change in the same PR. Dependabot covers only the
github-actionsecosystem, so everything else is a manual change. This documents each surface: the file holding the version, the files coupled to it, the regeneration command, and the verification command.Two mechanisms are documented up front because nearly every recipe ends in one of them:
pkg/assets/assetdata/— a version bumped without a matching hash entry compiles fine and fails atkops update clustertime.hack/update-expected.sh— golden-file regeneration, including that it never deletes stale goldens and that a diff touching only the addon manifest means it wasn't actually run.It also captures the commit/PR conventions these changes follow (the bump/regeneration commit split, cherry-pick expectations) and the failure modes that have cost past dependency PRs — for example that AWS load balancer controller, CSI, and Karpenter bumps usually need a matching
pkg/model/iam/iam_builder.gochange.References are deliberately generic — no line numbers or specific version strings — so the document does not go stale as pins move.
Which issue(s) this PR fixes:
Special notes for your reviewer:
Draft, opened for feedback on scope and placement before polishing.
Docs-only; no code or generated output changes.
The content was derived from reading the current pinning surfaces and the last 12 months of merged dependency PRs. A couple of pre-existing inconsistencies turned up while writing it (diverged pins of the same tool across scripts, a few stale docs). Those are deliberately left out of this guide, which describes only the steady state, and are worth handling separately.
Assisted by Claude Opus.