Skip to content

Docs: Port effective KRM function guide from #3367 - #4873

Merged
efiacor merged 5 commits into
kptdev:mainfrom
Nordix:doc-effective-krm-guide
Nov 18, 2026
Merged

efiacor merged 5 commits into
kptdev:mainfrom
Nordix:doc-effective-krm-guide

Conversation

@liamfallon

Copy link
Copy Markdown
Contributor

Docs: Port effective KRM function guide from #3367


Description

  • What changed: Adds a new guide page, documentation/content/en/guides/krm-functions/effective.md, titled "Effective KRM functions". It covers reading function configuration, selecting resources with Where/WhereNot, reading and updating fields, working with sub-objects, and decoding into typed structs. The guide is linked from the KRM Function Developer Guide index and from the Next Steps of the Go book chapter (book/05-developing-functions).
  • Why it's needed: This is a port of [WIP] Function SDK guide #3367 by @yuwenma, "[WIP] Function SDK guide", which was opened in 2022 against the old site/ tree. That tree has since been replaced by the Hugo site under documentation/, so the PR can't be rebased. The content is ported here onto the current docs structure. Thanks to @droot and @justinsb for the review comments on [WIP] Function SDK guide #3367, which shaped this version.
  • How it works: The page is a set of patterns on top of the existing Tutorial, Interfaces, Testing and Containerizing pages. It doesn't repeat them. The examples are written against the current krm-functions-sdk API. The original Run signature, *OrDie helpers and fn.IsGVK calls were replaced because they no longer exist or are deprecated.

Review comments on #3367 and how they are addressed

  • @droot: specify a minimum Go version. The Prerequisites now state Go 1.24 or later, the minimum the SDK requires.
  • @droot: the "advanced kpt users" wording may discourage readers. The intro was rewritten to describe what the guide covers and to point to the Tutorial and Interfaces pages first.
  • @droot: the setup steps with kpt pkg get are confusing for Go developers. The port has no setup section. Project setup belongs to the Tutorial.
  • @droot: the multi-line expression is fine for readability. Kept as a formatted multi-line block.
  • @droot: the sidebar placement. The page is placed under the KRM Function Developer Guide with a menu weight, not in the old sidebar.
  • @justinsb: the broken get-started-runner URL. The port uses the current SDK location and no longer references that path.
  • @justinsb: explain that items is modified in place. Added to the Select section.
  • @justinsb: use IsGK rather than IsGVK with an empty-value convention. The page uses fn.IsGroupVersionKind and fn.IsGroupKind, and notes that IsGVK is deprecated.
  • @justinsb: mention IsName as a helper. Added to the Select section.
  • @justinsb: warn that the sub-object copy has to be written back. Added to the Decode section: As copies the sub-object, and changes must be made with the setters.
  • @justinsb: the examples shouldn't be wrapped in Run, since readers would think they do something. The selection and update snippets are fragments, and the one complete Run shows the config-reading pattern.
  • @justinsb: walk through SetImage rather than FunctionX, and show users passing the config as YAML rather than as a ResourceList. The page uses SetImage and shows the config as YAML.
  • @justinsb: SomeBoolValue-style field names and the FnConfig prefix. These no longer apply, because config is read through functionConfig rather than struct fields.
  • @justinsb: Kptfile and ResourceList questions. The page shows config as YAML and doesn't explain ResourceList.

Several code examples were also corrected against the current SDK during the port. They are documented in the commits on this branch.


Related Issue(s)


Type of Change

  • Bug fix
  • New feature
  • Enhancement
  • Refactor
  • Documentation
  • Tests
  • Other: ________

Checklist

  • Code follows project style guidelines
  • Self-reviewed changes
  • Tests added/updated
  • Documentation added/updated
  • All tests and gating checks pass

Testing Instructions (Optional)

  1. Run make serve from documentation/ after npm install. Check that the "Effective KRM functions" page renders under KRM Function Developer Guide and that its links resolve.
  2. Check the Next Steps link in book/05-developing-functions.
  3. Code examples were compiled and run against the current krm-functions-sdk in a scratch module, outside this repo. Snippet compilation isn't part of the repo's test suite.

Additional Notes (Optional)

  • Known issues: The Hugo build was checked before the final review edits. The text changes since then were not rebuilt. Please run the build as part of review.
  • Further improvements: The Testing and Containerizing pages may benefit from matching examples, but that's out of scope here.
  • Review notes: Changes are limited to documentation/content/en/guides/krm-functions/effective.md, krm-functions/_index.md and book/05-developing-functions/_index.md.

AI Disclosure

  • I have used AI in the creation of this PR.

If so, please describe how:

  • Kiro (claude-haiku-5.5) ported the guide from [WIP] Function SDK guide #3367 to the current docs structure, corrected the examples against the current SDK, and drafted this description. Commits carry an Assisted-by trailer.

Port the effective Go KRM function guide from kptdev#3367 to the current
documentation tree. Rewrites examples against the current krm-functions-sdk
API (Run with results and bool return, functionConfig accessors, nested
getters returning value, found, err).

Assisted-by: Kiro:claude-haiku-5.5
Signed-off-by: liamfallon <liam.fallon@est.tech>
Signed-off-by: liamfallon <liam.fallon@est.tech>
Add the minimum Go version, note that items are modified in place, add
fn.IsName, and explain that As decodes a copy of the sub-object.

Assisted-by: Kiro:claude-haiku-5.5
Signed-off-by: liamfallon <liam.fallon@est.tech>
@liamfallon
liamfallon requested review from a team November 13, 2026 11:28
@liamfallon liamfallon added the documentation Improvements or additions to documentation label Nov 13, 2026
Copilot AI balanced review requested due to automatic review settings November 13, 2026 11:28
@netlify

netlify Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for kptdocs ready!

Built without sensitive environment variables

Name Link
🔨 Latest commit 17ed85c
🔍 Latest deploy log https://app.netlify.com/projects/kptdocs/deploys/6af6f7a09aa66978973bada9
😎 Deploy Preview https://deploy-preview-4873--kptdocs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The guide uses SDK APIs that no longer compile and incorrectly implies that filtering a Runner’s local items changes output membership.

2 open issues
What changed in this PR

Ports the effective KRM function guide from #3367 into the current Hugo documentation, adding practical resource-editing patterns alongside the existing developer tutorials.

Changes:

  • Adds examples for reading configuration, selecting resources, updating fields, and decoding sub-objects.
  • Links the guide from the developer guide index and the developing-functions book chapter.
File Description
documentation/​content/​en/​guides/​krm-functions/​effective.md Adds the practical KRM function guide.
documentation/​content/​en/​guides/​krm-functions/​_index.md Adds the guide to the developer guide index.
documentation/​content/​en/​book/​05-developing-functions/​_index.md Links to the guide from Next Steps.

Review effort: Balanced

Signed-off-by: liamfallon <liam.fallon@est.tech>
Signed-off-by: liamfallon <liam.fallon@est.tech>
@efiacor
efiacor merged commit d3ec405 into kptdev:main Nov 18, 2026
24 checks passed
@efiacor
efiacor deleted the doc-effective-krm-guide branch November 18, 2026 08:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: Write a "effective-go-krm-function" guide

6 participants