mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-10 08:20:59 +00:00
cmd/config set: Support for setting fields imperatively from the cli
This commit is contained in:
Phillip Wittrock
@@ -185,6 +185,263 @@ order they appear in the file).
|
||||
var RunFnsExamples = `
|
||||
kustomize config run example/`
|
||||
|
||||
var SubShort = `[Alpha] Set values on Resources fields by substituting values.`
|
||||
var SubLong = `
|
||||
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` + "`" + `
|
||||
`
|
||||
var SubExamples = `
|
||||
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 `
|
||||
|
||||
var SubsetShort = `[Alpha] Create a new substitution for a Resource field`
|
||||
var SubsetLong = `
|
||||
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."
|
||||
},
|
||||
}
|
||||
}
|
||||
`
|
||||
var SubsetExamples = `
|
||||
# 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"`
|
||||
|
||||
var TreeShort = `[Alpha] Display Resource structure from a directory or stdin.`
|
||||
var TreeLong = `
|
||||
[Alpha] Display Resource structure from a directory or stdin.
|
||||
|
||||
Reference in New Issue
Block a user