From 222d03cbf43a3f721974d63410e7d969f1327b1b Mon Sep 17 00:00:00 2001 From: Aravindhan Ayyanathan Date: Mon, 27 Jul 2026 14:56:20 +0100 Subject: [PATCH 1/3] Link to metadata.yaml schema reference from developing functions guide Signed-off-by: Aravindhan Ayyanathan --- documentation/content/en/book/05-developing-functions/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/content/en/book/05-developing-functions/_index.md b/documentation/content/en/book/05-developing-functions/_index.md index c4e6cb19e6..14b89bc742 100644 --- a/documentation/content/en/book/05-developing-functions/_index.md +++ b/documentation/content/en/book/05-developing-functions/_index.md @@ -363,3 +363,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/) From 8628403de9c925a522d7302388286373e3e708f4 Mon Sep 17 00:00:00 2001 From: Aravindhan Ayyanathan Date: Mon, 27 Jul 2026 15:23:21 +0100 Subject: [PATCH 2/3] Clarify path annotation semantics Signed-off-by: Aravindhan Ayyanathan --- .../en/book/05-developing-functions/_index.md | 7 +++++++ .../content/en/reference/annotations/_index.md | 13 +++++++++++++ 2 files changed, 20 insertions(+) diff --git a/documentation/content/en/book/05-developing-functions/_index.md b/documentation/content/en/book/05-developing-functions/_index.md index 14b89bc742..97139e724c 100644 --- a/documentation/content/en/book/05-developing-functions/_index.md +++ b/documentation/content/en/book/05-developing-functions/_index.md @@ -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. +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: diff --git a/documentation/content/en/reference/annotations/_index.md b/documentation/content/en/reference/annotations/_index.md index 828ff675e9..527e94912f 100644 --- a/documentation/content/en/reference/annotations/_index.md +++ b/documentation/content/en/reference/annotations/_index.md @@ -25,6 +25,19 @@ 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 DIR. + [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/ From bff76c2fa223a8a05b82b4144c38e03a9051c9d4 Mon Sep 17 00:00:00 2001 From: Aravindhan Ayyanathan Date: Tue, 28 Jul 2026 15:48:58 +0100 Subject: [PATCH 3/3] Address review comments Signed-off-by: Aravindhan Ayyanathan --- .../content/en/book/05-developing-functions/_index.md | 8 ++++---- documentation/content/en/reference/annotations/_index.md | 3 ++- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/documentation/content/en/book/05-developing-functions/_index.md b/documentation/content/en/book/05-developing-functions/_index.md index 97139e724c..36ec3627c6 100644 --- a/documentation/content/en/book/05-developing-functions/_index.md +++ b/documentation/content/en/book/05-developing-functions/_index.md @@ -93,10 +93,10 @@ 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. -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 +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. diff --git a/documentation/content/en/reference/annotations/_index.md b/documentation/content/en/reference/annotations/_index.md index 527e94912f..bc549484b2 100644 --- a/documentation/content/en/reference/annotations/_index.md +++ b/documentation/content/en/reference/annotations/_index.md @@ -36,7 +36,8 @@ 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 DIR. +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/