From 5e5e3b19f535ee399657adc6146aca4a0f79b018 Mon Sep 17 00:00:00 2001 From: Frank Farzan Date: Tue, 10 Dec 2019 12:01:50 -0800 Subject: [PATCH 1/3] Expand and format Configuration IO API Semantics. --- cmd/config/docs/api-conventions/config-io.md | 75 +++++++++++--------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/cmd/config/docs/api-conventions/config-io.md b/cmd/config/docs/api-conventions/config-io.md index 37a99a4e0..5237ef837 100644 --- a/cmd/config/docs/api-conventions/config-io.md +++ b/cmd/config/docs/api-conventions/config-io.md @@ -1,49 +1,58 @@ # Configuration IO API Semantics - Resource Configuration may be read / written from / to sources such as directories, - stdin|out or network. Tools may be composed using pipes such that the tools writing - Resource Configuration may be a different tool from the one that read the configuration. - In order for tools to be composed in this way, while preserving origin information -- - such as the original file, index, etc. +Resource Configuration may be read / written from / to sources such as directories, +stdin|out or network. Tools may be composed using pipes such that the tools writing +Resource Configuration may be a different tool from the one that read the configuration. +In order for tools to be composed in this way, while preserving origin information -- +such as the original file, index, etc. - Tools **SHOULD** write the following annotations when reading from sources, - and **SHOULD** respect the annotations when writing to syncs. +Tools **SHOULD** write the following annotations when reading from sources, +and **SHOULD** respect the annotations when writing to sinks. ### `config.kubernetes.io/path` - `config.kubernetes.io/path` records a relative path on a Resource. This annotation - **SHOULD** be set when reading Resources from files. - When writing Resources to a directory, the Resource **SHOULD** be written to the corresponding - path relative to that directory. +Records the slash-delimited, OS-agnostic, relative file path to a Resource. - Example: +This annotation **SHOULD** be set when reading Resources from files. +When writing Resources to a directory, the Resource **SHOULD** be written to the corresponding +path relative to that directory. - metadata: - annotations: - config.kubernetes.io/path: "relative/file/path.yaml" +Example: + +```yaml +metadata: + annotations: + config.kubernetes.io/path: "relative/file/path.yaml" +``` ### `config.kubernetes.io/index` - `config.kubernetes.io/index` records the index of a Resource into a file which may contain - multiple Resource. This annotation **SHOULD** be set when reading Resources from files. - When writing multiple Resources to the same file, the Resource **SHOULD** be written in the - relative order matching the index. +Records the index of a Resource in file. In a multi-object files YAML file, Resources are separated +by three dashes (`---`), and the index represents the positon of the Resource starting from zero. - Example: +This annotation **SHOULD** be set when reading Resources from files. +When writing multiple Resources to the same file, the Resource **SHOULD** be written in the +relative order matching the index. - metadata: - annotations: - config.kubernetes.io/index: "0" +Example: + +```yaml +metadata: + annotations: + config.kubernetes.io/index: "0" +``` ### `config.kubernetes.io/local-config` - `config.kubernetes.io/local-config` declares that the configuration is to local tools - rather than a remote Resource. e.g. The `Kustomization` config in a `kustomization.yaml` - **SHOULD** contain this annotation so that tools know it is not intended to be sent to - the Kubernetes api server. - - Example: - - metadata: - annotations: - config.kubernetes.io/local-config: "true" +`config.kubernetes.io/local-config` declares that the configuration is to local tools +rather than a remote Resource. e.g. The `Kustomization` config in a `kustomization.yaml` +**SHOULD** contain this annotation so that tools know it is not intended to be sent to +the Kubernetes api server. + +Example: + +```yaml +metadata: + annotations: + config.kubernetes.io/local-config: "true" +``` From 8c037ba109ed4374c8da89fe5d63538f739a851c Mon Sep 17 00:00:00 2001 From: Frank Farzan Date: Tue, 10 Dec 2019 12:15:28 -0800 Subject: [PATCH 2/3] Index is a number not a string --- cmd/config/docs/api-conventions/config-io.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/config/docs/api-conventions/config-io.md b/cmd/config/docs/api-conventions/config-io.md index 5237ef837..07c4b2f51 100644 --- a/cmd/config/docs/api-conventions/config-io.md +++ b/cmd/config/docs/api-conventions/config-io.md @@ -39,7 +39,7 @@ Example: ```yaml metadata: annotations: - config.kubernetes.io/index: "0" + config.kubernetes.io/index: 0 ``` ### `config.kubernetes.io/local-config` From b0f1f66d9a6b7fdcc51f7552e9e585ad5fd377c5 Mon Sep 17 00:00:00 2001 From: Frank Farzan Date: Tue, 10 Dec 2019 12:27:02 -0800 Subject: [PATCH 3/3] Document the default value --- cmd/config/docs/api-conventions/config-io.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/cmd/config/docs/api-conventions/config-io.md b/cmd/config/docs/api-conventions/config-io.md index 07c4b2f51..27efdd0ec 100644 --- a/cmd/config/docs/api-conventions/config-io.md +++ b/cmd/config/docs/api-conventions/config-io.md @@ -34,14 +34,19 @@ This annotation **SHOULD** be set when reading Resources from files. When writing multiple Resources to the same file, the Resource **SHOULD** be written in the relative order matching the index. +When this annotation is not specified, it implies a value of `0`. + Example: ```yaml metadata: annotations: - config.kubernetes.io/index: 0 + config.kubernetes.io/path: "relative/file/path.yaml" + config.kubernetes.io/index: 2 ``` +This represents the thrid Resource in the file. + ### `config.kubernetes.io/local-config` `config.kubernetes.io/local-config` declares that the configuration is to local tools