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
98
cmd/config/docs/commands/sub.md
Normal file
98
cmd/config/docs/commands/sub.md
Normal file
@@ -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
|
||||
167
cmd/config/docs/commands/subset.md
Normal file
167
cmd/config/docs/commands/subset.md
Normal file
@@ -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"
|
||||
Reference in New Issue
Block a user