cfgdocs

Documentation

Overview

Code generated by "mdtogo"; DO NOT EDIT.

Index

• Variables

Variables

var AnnotateExamples = `` /* 416-byte string literal not displayed */

var AnnotateLong = `
  DIR:
    Path to local directory.
`

var AnnotateShort = `Set an annotation on one or more Resources`

var CatExamples = `
    # print Resource config from a directory
    kpt cfg cat my-dir/
`

var CatLong = `
    kpt cfg cat DIR

  DIR:
    Path to local directory.
`

var CatShort = `Print resources`

var CountExamples = `` /* 160-byte string literal not displayed */

var CountLong = `
    kpt cfg count [DIR]

  DIR:
    Path to local directory.
`

var CountShort = `Print resource counts`

var CreateSetterExamples = `` /* 903-byte string literal not displayed */

var CreateSetterLong = `
    kpt cfg create-setter DIR NAME VALUE

  DIR

    A directory containing Resource configuration.
    e.g. hello-world/

  NAME

    The name of the substitution to create.  This is both the name that will be given
    to the *set* command, and that will be referenced by fields.
    e.g. replicas

  VALUE

    The new value of the setter.
    e.g. 3

#### Field Setters

Field setters are OpenAPI definitions that define how fields may be modified programmatically
using the *set* command.  The OpenAPI definitions for setters are defined in a Kptfile
and referenced by fields which they set through an OpenAPI reference as a line comment
(e.g. # {"$ref":"#/definitions/..."}).

Setters may be manually created by editing the Kptfile, or programmatically created using the
` + "`" + `create-setter` + "`" + ` command.  The ` + "`" + `create-setter` + "`" + ` command will 1) create a new OpenAPI definition
for a setter in the Kptfile, and 2) identify all fields matching the setter value and create
an OpenAPI reference to the setter for each.

    # create or update a setter named replicas
    kpt create-setter hello-world/ replicas 3

Example setter definition in a Kptfile:

	openAPI:
	  definitions:
	    io.k8s.cli.setters.replicas:
	      x-k8s-cli:
	        setter:
	          name: "replicas"
	          value: "3"

This setter is named "replicas" and can be provided to the *set* command to change
all fields which reference it to the setter's value.

Example setter referenced from a field in a configuration file:

	kind: Deployment
	metadata:
	  name: foo
	spec:
	  replicas: 3  # {"$ref":"#/definitions/io.k8s.cli.setters.replicas"}

Setters may have types specified which ensure that the configuration is always serialized
correctly as yaml 1.1 -- e.g. if a string field such as an annotation or arg has the value
"on", then it would need to be quoted otherwise it will be parsed as a bool by yaml 1.1.

A type may be specified using the --type flag, and accepts string,integer,boolean as values.
The resulting OpenAPI definition looks like:

    # create or update a setter named version which sets the "version" annotation
    kpt create-setter hello-world/ version 3 --field "annotations.version" --type string

	openAPI:
	  definitions:
	    io.k8s.cli.setters.version:
	      x-k8s-cli:
	        setter:
	          name: "version"
	          value: "3"
	      type: string

And the configuration looks like:

	kind: Deployment
	metadata:
	  name: foo
	  annotations:
	    version: "3" # {"$ref":"#/definitions/io.k8s.cli.setters.version"}

Setters may be configured to accept enumeration values which map to different values set
on the fields.  For example setting cpu resources to small, medium, large -- and mapping
these to specific cpu values.  This may be done by manually modifying the Kptfile openAPI
definitions as shown here:

	openAPI:
	  definitions:
	    io.k8s.cli.setters.cpu:
	      x-k8s-cli:
	        setter:
	          name: "cpu"
	          value: "small"
	          # enumValues will replace the user provided key with the
	          # map value when setting fields.
	          enumValues:
	            small: "0.5"
	            medium: "2"
	            large: "4"

And the configuration looks like:

	kind: Deployment
	metadata:
	  name: foo
	spec:
	  template:
	    spec:
	      containers:
	      - name: foo
	    resources:
	      requests:
	        cpu: "0.5" # {"$ref":"#/definitions/io.k8s.cli.setters.cpu"}
`

var CreateSetterShort = `Create or modify a field setter`

var CreateSubstExamples = `` /* 1385-byte string literal not displayed */

var CreateSubstLong = `
    kpt cfg create-subst DIR NAME VALUE --pattern PATTERN --value MARKER=SETTER

  DIR

    A directory containing Resource configuration.
    e.g. hello-world/

  NAME

    The name of the substitution to create.  This is simply the unique key which is referenced
    by fields which have the substitution applied.
    e.g. image-substitution

  VALUE

    The current value of the field that will have PATTERN substituted.
    e.g. nginx:1.7.9

  PATTERN

    A string containing one or more MARKER substrings which will be substituted
    for setter values.  The pattern may contain multiple different MARKERS,
    the same MARKER multiple times, and non-MARKER substrings.
    e.g. IMAGE_SETTER:TAG_SETTER

#### Field Substitutions

Field substitutions are OpenAPI definitions that define how fields may be modified programmatically
using the *set* command.  The OpenAPI definitions for substitutions are defined in a Kptfile
and referenced by fields which they set through an OpenAPI reference as a line comment
(e.g. # {"$ref":"#/definitions/..."}).

Substitutions may be manually created by editing the Kptfile, or programmatically created using the
` + "`" + `create-subst` + "`" + ` command.  The ` + "`" + `create-subst` + "`" + ` command will 1) create a new OpenAPI definition
for a substitution in the Kptfile, and 2) identify all fields matching the provided value and create
an OpenAPI reference to the substitution for each.

Field substitutions are computed by substituting setter values into a pattern.  They are
composed of 2 parts: a pattern and a list of values.

- The pattern is a string containing markers which will be replaced with 1 or more setter values.
- The values are pairs of markers and setter references.  The *set* command retrieves the values
  from the referenced setters, and replaces the markers with the setter values.
 
**The referenced setters MAY exist before creating the substitution, in which case the
existing setters are used instead of recreated.**

    # create or update a substitution + 2 setters
    # the substitution is derived from concatenating the image and tag setter values
    kpt create-subst hello-world/ image-tag nginx:1.7.9 \
      --pattern IMAGE_SETTER:TAG_SETTER \
      --value IMAGE_SETTER=image \
      --value TAG_SETTER=tag

If create-subst cannot infer the setter values from the VALUE + --pattern, and the setters
do not already exist, then it will throw and error, and the setters must be manually created
beforehand.

Example setter and substitution definitions in a Kptfile:

	openAPI:
	  definitions:
	    io.k8s.cli.setters.image:
	      x-k8s-cli:
	        setter:
	          name: "image"
	          value: "nginx"
	    io.k8s.cli.setters.tag:
	      x-k8s-cli:
	        setter:
	          name: "tag"
	          value: "1.7.9"
	    io.k8s.cli.substitutions.image-value:
	      x-k8s-cli:
	        substitution:
	          name: image-value
	          pattern: IMAGE_SETTER:TAG_SETTER
	          values:
	          - marker: IMAGE_SETTER
	            ref: '#/definitions/io.k8s.cli.setters.image'
	          - marker: TAG_SETTER
	            ref: '#/definitions/io.k8s.cli.setters.tag'

This substitution defines how a field value may be produced from the setters ` + "`" + `image` + "`" + ` and ` + "`" + `tag` + "`" + `
by replacing the pattern substring *IMAGE_SETTER* with the value of the ` + "`" + `image` + "`" + ` setter, and
replacing the pattern substring *TAG_SETTER* with the value of the ` + "`" + `tag` + "`" + ` setter.  Any time
either the ` + "`" + `image` + "`" + ` or ` + "`" + `tag` + "`" + ` values are changed via *set*, the substitution value will be
re-calculated for referencing fields.

Example substitution reference from a field in a configuration file:

	kind: Deployment
	metadata:
	  name: foo
	spec:
	  template:
	    spec:
	      containers:
	      - name: nginx
	        image: nginx:1.7.9 # {"$ref":"#/definitions/io.k8s.cli.substitutions.image-value"}

The ` + "`" + `image` + "`" + ` field has a OpenAPI reference to the ` + "`" + `image-value` + "`" + ` substitution definition.  When
the *set* command is called, for either the ` + "`" + `image` + "`" + ` or ` + "`" + `tag` + "`" + ` setter, the substitution will
be recalculated, and the ` + "`" + `image` + "`" + ` field updated with the new value.

**Note**: when setting a field through a substitution, the names of the setters are used
*not* the name of the substitution.  The name of the substitution is *only used in field
references*.
`

var CreateSubstShort = `Create or modify a field substitution`

var FmtExamples = `` /* 290-byte string literal not displayed */

var FmtLong = `` /* 937-byte string literal not displayed */

var FmtShort = `Format configuration files`

var GrepExamples = `` /* 475-byte string literal not displayed */

var GrepLong = `` /* 363-byte string literal not displayed */

var GrepShort = `Find resources by field value`

var ListSettersExamples = `` /* 241-byte string literal not displayed */

var ListSettersLong = `` /* 142-byte string literal not displayed */

var ListSettersShort = `List configured field setters`

var READMEExamples = `` /* 1011-byte string literal not displayed */

var READMELong = `` /* 1137-byte string literal not displayed */

var READMEShort = `Examine and modify configuration files`

var SetExamples = `` /* 597-byte string literal not displayed */

var SetLong = `
    kpt cfg set DIR NAME VALUE

  DIR

    A directory containing Resource configuration.
    e.g. hello-world/

  NAME

    The name of the setter
    e.g. replicas

  VALUE

    The new value to set on fields
    e.g. 3

#### Setters

The *set* command modifies configuration fields using setters defined as OpenAPI definitions
in a Kptfile.  Setters are referenced by fields using line commands on the fields.  Fields
referencing a setter will have their value modified to match the setter value when the *set*
command is called.

If multiple fields may reference the same setter, all of the field's values will be
changed when the *set* command is called for that setter.

The *set* command must be run on a directory containing a Kptfile with setter definitions.
The list of setters configured for a package may be found using ` + "`" + `kpt cfg list-setters` + "`" + `.

    kpt cfg set hello-world/ replicas 3

Example setter definition in a Kptfile:

	openAPI:
	  definitions:
	    io.k8s.cli.setters.replicas:
	      x-k8s-cli:
	        setter:
	          name: "replicas"
	          value: "3"

This setter is named "replicas" and can be provided to the *set* command to change
all fields which reference it to the setter's value.

Example setter referenced from a field in a configuration file:

	kind: Deployment
	metadata:
	  name: foo
	spec:
	  replicas: 3  # {"$ref":"#/definitions/io.k8s.cli.setters.replicas"}

#### Description

Setters may have a description of the current value.  This may be defined along with
the value by specifying the ` + "`" + `--description` + "`" + ` flag.

#### SetBy

Setters may record who set the current value.  This may be defined along with the
value by specifying the ` + "`" + `--set-by` + "`" + ` flag.  If unspecified the current value for
set-by will be cleared from the setter.

#### Substitutions

Substitutions define field values which may be composed of one or more setters substituted
into a string pattern.  e.g. setting only the tag portion of the ` + "`" + `image` + "`" + ` field.

Anytime set is called for a setter used by a substitution, it will also modify the fields
referencing that substitution.

See ` + "`" + `kpt cfg create-subst` + "`" + ` for more information on substitutions.
`

var SetShort = `Set one or more field values using setters`

var TreeExamples = `` /* 1071-byte string literal not displayed */

var TreeLong = `` /* 751-byte string literal not displayed */

var TreeShort = `Print resources as a tree`