kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-09-15 12:18:57 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Expand and format Configuration IO API Semantics.

Browse Source
This commit is contained in:
Frank Farzan
2019-12-10 12:01:50 -08:00
parent ad94f2c0eb
commit 5e5e3b19f5
1 changed files with 42 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
cmd/config/docs/api-conventions/config-io.md
View File

@@ -1,49 +1,58 @@
# Configuration IO API Semantics # Configuration IO API Semantics
Resource Configuration may be read / written from / to sources such as directories, 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 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. 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 -- In order for tools to be composed in this way, while preserving origin information --
such as the original file, index, etc. such as the original file, index, etc.
Tools **SHOULD** write the following annotations when reading from sources, Tools **SHOULD** write the following annotations when reading from sources,
and **SHOULD** respect the annotations when writing to syncs. and **SHOULD** respect the annotations when writing to sinks.
### `config.kubernetes.io/path` ### `config.kubernetes.io/path`
`config.kubernetes.io/path` records a relative path on a Resource. This annotation Records the slash-delimited, OS-agnostic, relative file path to a Resource.
**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.
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: Example:
annotations:
config.kubernetes.io/path: "relative/file/path.yaml" ```yaml
metadata:
annotations:
config.kubernetes.io/path: "relative/file/path.yaml"
```
### `config.kubernetes.io/index` ### `config.kubernetes.io/index`
`config.kubernetes.io/index` records the index of a Resource into a file which may contain Records the index of a Resource in file. In a multi-object files YAML file, Resources are separated
multiple Resource. This annotation **SHOULD** be set when reading Resources from files. by three dashes (`---`), and the index represents the positon of the Resource starting from zero.
When writing multiple Resources to the same file, the Resource **SHOULD** be written in the
relative order matching the index.
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: Example:
annotations:
config.kubernetes.io/index: "0" ```yaml
metadata:
annotations:
config.kubernetes.io/index: "0"
```
### `config.kubernetes.io/local-config` ### `config.kubernetes.io/local-config`
`config.kubernetes.io/local-config` declares that the configuration is to local tools `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` 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 **SHOULD** contain this annotation so that tools know it is not intended to be sent to
the Kubernetes api server. the Kubernetes api server.
Example: Example:
metadata: ```yaml
annotations: metadata:
config.kubernetes.io/local-config: "true" annotations:
config.kubernetes.io/local-config: "true"
```