Skip to content

Clarify path annotation semantics and link to metadata schema reference #4666

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.

Sign up for GitHub

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

Open
aravindtga wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Clarify path annotation semantics and link to metadata schema reference #4666

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
222d03c
Link to metadata.yaml schema reference from developing functions guide
aravindtga Jul 27, 2026
8628403
Clarify path annotation semantics
aravindtga Jul 27, 2026
bff76c2
Address review comments
aravindtga Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions documentation/content/en/book/05-developing-functions/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,13 @@ Understanding this specification enables you to have a deeper understanding of
how things work under the hood. It also enables to create your own toolchain for
function development if you so desire.

When kpt reads resources from disk, each resource in the `ResourceList` carries an
`internal.config.kubernetes.io/path` annotation indicating its file path relative to
the package directory. When a function creates new resources, it should set this
annotation to a path relative to the same package directory. See the
[annotations reference](/reference/annotations/#path-annotation-details)
for full details.

As an example, you can see the `ResourceList` containing resources in the
`wordpress` package:

Expand Down Expand Up @@ -363,3 +370,4 @@ kpt fn eval ./testdata/noop-passthrough/resources.yaml --image ${FN_CONTAINER_RE

- See other [go documentation examples](https://pkg.go.dev/github.com/kptdev/krm-functions-sdk/go/fn/examples) to use KubeObject.
- To contribute to KRM catalog functions, please follow the [contributor guide](https://github.com/kptdev/krm-functions-catalog/blob/main/CONTRIBUTING.md)
- For the `metadata.yaml` schema reference (required fields, allowed tags), see the [metadata schema documentation](https://catalog.kpt.dev/metadata-schema/)
14 changes: 14 additions & 0 deletions documentation/content/en/reference/annotations/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,20 @@ The following annotations are used by kpt internally:
| `internal.config.kubernetes.io/index` | specifies the index of the resource in a file when formatted as a ResourceList |
| `config.kubernetes.io/merge-source` | specifies the source of the resource during a three way merge |

## Path annotation details

The `internal.config.kubernetes.io/path` annotation specifies the file path of a
resource relative to the package directory (the directory containing the Kptfile
whose pipeline invoked the function).

When kpt reads resources from disk, it sets this annotation on each resource.
When a function creates new resources, it should set this annotation to a path
relative to the same package directory. kpt handles adjusting paths to be
relative to the root package before writing to disk.

For `kpt fn eval DIR`, the path is relative to the package directory DIR
(the directory passed as the evaluation target).

[config.kubernetes.io/depends-on]: /reference/annotations/depends-on/
[config.kubernetes.io/apply-time-mutation]: /reference/annotations/apply-time-mutation/
[config.kubernetes.io/local-config]: /reference/annotations/local-config/