kustomize/cmd/config/docs/commands/subset.md

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."
    },
    "setBy": {
      "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"