-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
18 changed files
with
1,498 additions
and
0 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| ## set | ||
|
|
||
| [Alpha] Set values on Resources fields by substituting values. | ||
|
|
||
| ### Synopsis | ||
|
|
||
| Set values on Resources fields by substituting predefined markers for new values. | ||
|
|
||
| `set` looks for markers specified on Resource fields and substitute a new user defined | ||
| value for the existing value. | ||
|
|
||
| `set` maybe be used to: | ||
|
|
||
| - edit configuration programmatically from the cli or scripts | ||
| - create reusable bundles of configuration | ||
|
|
||
| DIR | ||
|
|
||
| A directory containing Resource configuration. | ||
|
|
||
| NAME | ||
|
|
||
| Optional. The name of the substitution to perform or display. | ||
|
|
||
| VALUE | ||
|
|
||
| Optional. The new value to substitute into the field. | ||
|
|
||
|
|
||
| To print the possible substitutions for the Resources in a directory, run `set` on | ||
| a directory -- e.g. `kustomize config set DIR/`. | ||
|
|
||
| #### Tips | ||
|
|
||
| - A description of the value may be specified with `--description`. | ||
| - An owner for the field's value may be defined with `--owned-by`. | ||
| - Prevent overriding previous substitutions with `--override=false`. | ||
| - Revert previous substitutions with `--revert`. | ||
| - Create substitutions on Kustomization.yaml's, patches, etc | ||
|
|
||
| When overriding or reverting previous substitutions, the description and owner are left | ||
| unmodified unless specified with flags. | ||
|
|
||
| To create a substitution for a field see: `kustomize help config set create` | ||
|
|
||
| ### Examples | ||
|
|
||
| Resource YAML: Name substitution | ||
|
|
||
| # dir/resources.yaml | ||
| ... | ||
| metadata: | ||
| name: PREFIX-app1 # {"substitutions":[{"name":"prefix","marker":"PREFIX-"}]} | ||
| ... | ||
| --- | ||
| ... | ||
| metadata: | ||
| name: PREFIX-app2 # {"substitutions":[{"name":"prefix","marker":"PREFIX-"}]} | ||
| ... | ||
|
|
||
| Show substitutions: Show the possible substitutions | ||
|
|
||
| $ config set dir | ||
| NAME DESCRIPTION VALUE TYPE COUNT SUBSTITUTED OWNER | ||
| prefix '' PREFIX- string 2 false | ||
|
|
||
| Perform substitution: set a new value, owner and description | ||
|
|
||
| $ config set dir prefix "test-" --description "test environment" --owned-by "dev" | ||
| performed 2 substitutions | ||
|
|
||
| Show substitutions: Show the new values | ||
|
|
||
| $ config set dir | ||
| NAME DESCRIPTION VALUE TYPE COUNT SUBSTITUTED OWNER | ||
| prefix 'test environment' test- string 2 true dev | ||
|
|
||
| New Resource YAML: | ||
|
|
||
| # dir/resources.yaml | ||
| ... | ||
| metadata: | ||
| name: test-app1 # {"substitutions":[{"name":"prefix","marker":"PREFIX-","value":"test-"}],"ownedBy":"dev","description":"test environment"} | ||
| ... | ||
| --- | ||
| ... | ||
| metadata: | ||
| name: test-app2 # {"substitutions":[{"name":"prefix","marker":"PREFIX-","value":"test-"}],"ownedBy":"dev","description":"test environment"} | ||
| ... | ||
|
|
||
| Revert substitution: | ||
|
|
||
| config set dir prefix --revert | ||
| performed 2 substitutions | ||
|
|
||
| config set dir | ||
| NAME DESCRIPTION VALUE TYPE COUNT SUBSTITUTED OWNER | ||
| prefix 'test environment' PREFIX- string 2 false dev |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,167 @@ | ||
| ## sub-set-marker | ||
|
|
||
| [Alpha] Create a new substitution for a Resource field | ||
|
|
||
| ### Synopsis | ||
|
|
||
| Create a new substitution for a Resource field -- recognized by `kustomize config set`. | ||
|
|
||
| DIR | ||
|
|
||
| A directory containing Resource configuration. | ||
|
|
||
| NAME | ||
|
|
||
| The name of the substitution to create. | ||
|
|
||
| VALUE | ||
|
|
||
| The current value of the field, or a substring of the field. | ||
|
|
||
| #### Tips: Picking Good Marker | ||
|
|
||
| Substitutions may be defined by directly editing yaml **or** by running `kustomize config set create` | ||
| to create a new substitution. | ||
|
|
||
| Given the YAML: | ||
|
|
||
| # resource.yaml | ||
| apiVersion: v1 | ||
| kind: Service | ||
| metadata: | ||
| ... | ||
| spec: | ||
| ... | ||
| ports: | ||
| ... | ||
| - name: http | ||
| port: 8080 | ||
| ... | ||
|
|
||
| Create a new set marker: | ||
|
|
||
| # create a substitution for ports | ||
| $ kustomize config set create dir/ http-port 8080 --type "int" --field "port" | ||
|
|
||
| Modified YAML: | ||
|
|
||
| # resource.yaml | ||
| apiVersion: v1 | ||
| kind: Service | ||
| metadata: | ||
| ... | ||
| spec: | ||
| ... | ||
| ports: | ||
| ... | ||
| - name: http | ||
| port: 8080 # {"substitutions":[{"name":"port","marker":"[MARKER]"}],"type":"int"} | ||
| ... | ||
|
|
||
| Change the value using the `set` command: | ||
|
|
||
| # change the http-port value to 8081 | ||
| $ kustomize config set dir/ http-port 8081 | ||
|
|
||
| Resources fields with a field name matching `--field` and field value matching `VALUE` will | ||
| have a line comment added marking this field as settable. | ||
|
|
||
| Substitution markers may be: | ||
|
|
||
| - valid field values (e.g. `8080` for a port) | ||
| - Note: `008080` would be preferred because it is more recognizable as a marker | ||
| - invalid values that adhere to the schema (e.g. `0000` for a port) | ||
| - values that do not adhere to the schema (e.g. `[PORT]` for port) | ||
|
|
||
| Markers **SHOULD be clearly identifiable as a marker and either**: | ||
|
|
||
| - **adhere to the field schema** -- e.g. use a valid value | ||
|
|
||
|
|
||
| port: 008080 # {"substitutions":[{"name":"port","marker":"008080"}],"type":"int"} | ||
|
|
||
| - **be pre-filled in with a value** -- e.g. set the value when setting the marker | ||
|
|
||
|
|
||
| port: 8080 # {"substitutions":[{"name":"port","marker":"[MARKER]","value":"8080""}],"type":"int"} | ||
|
|
||
| **Note:** The important thing is that in both cases the Resource configuration may be directly | ||
| applied to a cluster and validated by tools without the tool knowing about the substitution | ||
| marker. | ||
|
|
||
| The difference between the preceding examples is that: | ||
|
|
||
| - the former will be shown as `SUBSTITUTED=false` (`config sub dir/` exits non-0) | ||
| - the latter with show up as `SUBSTITUTED=true` (`config sub dir/` exits 0) | ||
|
|
||
| When choosing the which to use, consider that checks for unsubstituted values MAY be | ||
| configured as pre-commit checks -- if you want to these checks to fail if the value | ||
| hasn't been substituted, then don't specify a `value`. | ||
|
|
||
| Markers which are invalid field values MAY be chosen in cases where it is preferred to have | ||
| the create or update request fail rather than succeed if the substitution has not yet been | ||
| performed. | ||
|
|
||
| A substitution may be a substring of the full field: | ||
|
|
||
| $ kustomize config set create dir/ app-image-tag v1.0.01 --type "string" --field "image" | ||
|
|
||
| image: gcr.io/example/app:v1.0.1 # {"substitutions":[{"name":"app-image-tag","marker":"[MARKER]","value":"v1.0.1"}]} | ||
|
|
||
|
|
||
| A single field value may have multiple substitutions applied to it: | ||
|
|
||
| name: PREFIX-app-SUFFIX # {"substitutions":[{"name":"prefix","marker":"PREFIX-"},{"name":"suffix","marker":"-SUFFIX"}]} | ||
|
|
||
| #### Substitution Format | ||
|
|
||
| Substitutions are defined as json encoded FieldMeta comments on fields. | ||
|
|
||
| FieldMeta Schema read by `sub`: | ||
|
|
||
| { | ||
| "title": "FieldMeta", | ||
| "type": "object", | ||
| "properties": { | ||
| "substitutions": { | ||
| "type": "array", | ||
| "description": "Possible substitutions that may be performed against this field.", | ||
| "items": { | ||
| "type": "object", | ||
| "properties": { | ||
| "name": "Name of the substitution.", | ||
| "marker": "Marker for the value to be substituted.", | ||
| "value": "Current substituted value" | ||
| } | ||
| } | ||
| }, | ||
| "type": { | ||
| "type": "string", | ||
| "description": "The value type. Defaults to string." | ||
| "enum": ["string", "int", "float", "bool"] | ||
| }, | ||
| "description": { | ||
| "type": "string", | ||
| "description": "A description of the field's current value. Optional." | ||
| }, | ||
| "ownedBy": { | ||
| "type": "string", | ||
| "description": "The current owner of the field. Optional." | ||
| }, | ||
| } | ||
| } | ||
|
|
||
| ### Examples | ||
|
|
||
| # set a substitution for port fields matching "8080" | ||
| kustomize config sub create dir/ port 8080 --type "int" --field port \ | ||
| --description "default port used by the app" | ||
|
|
||
| # set a substitution for port fields matching "8080", using "0000" as a marker. | ||
| kustomize config sub dir/ port 8080 --marker "0000" --type "int" \ | ||
| --field port --description "default port used by the app" | ||
|
|
||
| # substitute a substring of a field rather than the full field -- e.g. only the | ||
| # image tag, not the full image | ||
| kustomize config sub dir/ app-image-tag v1.0.1 --type "string" --substring \ | ||
| --field port --description "current stable release" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.