kustomize/cmd/config/internal/generateddocs/commands/docs.go

// Copyright 2019 The Kubernetes Authors.
// SPDX-License-Identifier: Apache-2.0

// Code generated by "mdtogo"; DO NOT EDIT.
package commands

var CatShort = `[Alpha] Print Resource Config from a local directory.`
var CatLong = `
[Alpha]  Print Resource Config from a local directory.

  DIR:
    Path to local directory.
`
var CatExamples = `
    # print Resource config from a directory
    kustomize config cat my-dir/

    # wrap Resource config from a directory in an ResourceList
    kustomize config cat my-dir/ --wrap-kind ResourceList --wrap-version config.kubernetes.io/v1alpha1 --function-config fn.yaml

    # unwrap Resource config from a directory in an ResourceList
    ... | kustomize config cat`

var CompletionShort = `Install shell completion.`
var CompletionLong = `
Install shell completion for kustomize commands and flags -- supports bash, fish and zsh.

    kustomize install-completion

Registers the completion command with known shells (e.g. .bashrc, .bash_profile, etc):

    complete -C /Users/USER/go/bin/kustomize kustomize

Because the completion command is embedded in kustomize directly, there is no need to update
it separately from the kustomize binary.

To uninstall shell completion run:

    COMP_UNINSTALL=1 kustomize install-completion`

var CountShort = `[Alpha] Count Resources Config from a local directory.`
var CountLong = `
[Alpha] Count Resources Config from a local directory.

  DIR:
    Path to local directory.
`
var CountExamples = `
    # print Resource counts from a directory
    kustomize config count my-dir/`

var FmtShort = `[Alpha] Format yaml configuration files.`
var FmtLong = `
[Alpha] Format yaml configuration files.

Fmt will format input by ordering fields and unordered list items in Kubernetes
objects.  Inputs may be directories, files or stdin, and their contents must
include both apiVersion and kind fields.

- Stdin inputs are formatted and written to stdout
- File inputs (args) are formatted and written back to the file
- Directory inputs (args) are walked, each encountered .yaml and .yml file
  acts as an input

For inputs which contain multiple yaml documents separated by \n---\n,
each document will be formatted and written back to the file in the original
order.

Field ordering roughly follows the ordering defined in the source Kubernetes
resource definitions (i.e. go structures), falling back on lexicographical
sorting for unrecognized fields.

Unordered list item ordering is defined for specific Resource types and
field paths.

- .spec.template.spec.containers (by element name)
- .webhooks.rules.operations (by element value)
`
var FmtExamples = `
	# format file1.yaml and file2.yml
	kustomize config fmt file1.yaml file2.yml

	# format all *.yaml and *.yml recursively traversing directories
	kustomize config fmt my-dir/

	# format kubectl output
	kubectl get -o yaml deployments | kustomize config fmt

	# format kustomize output
	kustomize build | kustomize config fmt`

var GrepShort = `[Alpha] Search for matching Resources in a directory or from stdin`
var GrepLong = `
[Alpha] Search for matching Resources in a directory or from stdin.

  QUERY:
    Query to match expressed as 'path.to.field=value'.
    Maps and fields are matched as '.field-name' or '.map-key'
    List elements are matched as '[list-elem-field=field-value]'
    The value to match is expressed as '=value'
    '.' as part of a key or value can be escaped as '\.'

  DIR:
    Path to local directory.
`
var GrepExamples = `
    # find Deployment Resources
    kustomize config grep "kind=Deployment" my-dir/

    # find Resources named nginx
    kustomize config grep "metadata.name=nginx" my-dir/

    # use tree to display matching Resources
    kustomize config grep "metadata.name=nginx" my-dir/ | kustomize config tree

    # look for Resources matching a specific container image
    kustomize config grep "spec.template.spec.containers[name=nginx].image=nginx:1\.7\.9" my-dir/ | kustomize config tree`

var MergeShort = `[Alpha] Merge Resource configuration files`
var MergeLong = `
[Alpha] Merge Resource configuration files

Merge reads Kubernetes Resource yaml configuration files from stdin or sources packages and write
the result to stdout or a destination package.

Resources are merged using the Resource [apiVersion, kind, name, namespace] as the key.  If any of
these are missing, merge will default the missing values to empty.

Resources specified later are high-precedence (the source) and Resources specified
earlier are lower-precedence (the destination).

For information on merge rules, run:

	kustomize config docs merge
`
var MergeExamples = `
    cat resources_and_patches.yaml | kustomize config merge > merged_resources.yaml`

var RunFnsShort = `[Alpha] Reoncile config functions to Resources.`
var RunFnsLong = `
[Alpha] Reconcile config functions to Resources.

run sequentially invokes all config functions in the directory, providing Resources
in the directory as input to the first function, and writing the output of the last
function back to the directory.

The ordering of functions is determined by the order they are encountered when walking the
directory.  To clearly specify an ordering of functions, multiple functions may be
declared in the same file, separated by '---' (the functions will be invoked in the
order they appear in the file).

#### Arguments:

  DIR:
    Path to local directory.

#### Config Functions:

  Config functions are specified as Kubernetes types containing a metadata.configFn.container.image
  field.  This field tells run how to invoke the container.

  Example config function:

	# in file example/fn.yaml
	apiVersion: fn.example.com/v1beta1
	kind: ExampleFunctionKind
	metadata:
	  configFn:
	    container:
	      # function is invoked as a container running this image
	      image: gcr.io/example/examplefunction:v1.0.1
	  annotations:
	    config.kubernetes.io/local-config: "true" # tools should ignore this
	spec:
	  configField: configValue

  In the preceding example, 'kustomize config run example/' would identify the function by
  the metadata.configFn field.  It would then write all Resources in the directory to
  a container stdin (running the gcr.io/example/examplefunction:v1.0.1 image).  It
  would then write the container stdout back to example/, replacing the directory
  file contents.

  See ` + "`" + `kustomize help config docs-fn` + "`" + ` for more details on writing functions.
`
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.

kustomize config tree may be used to print Resources in a directory or cluster, preserving structure

Args:

  DIR:
    Path to local directory directory.

Resource fields may be printed as part of the Resources by specifying the fields as flags.

kustomize config tree has build-in support for printing common fields, such as replicas, container images,
container names, etc.

kustomize config tree supports printing arbitrary fields using the '--field' flag.

By default, kustomize config tree uses the directory structure for the tree structure, however when printing
from the cluster, the Resource graph structure may be used instead.
`
var TreeExamples = `
    # print Resources using directory structure
    kustomize config tree my-dir/

    # print replicas, container name, and container image and fields for Resources
    kustomize config tree my-dir --replicas --image --name

    # print all common Resource fields
    kustomize config tree my-dir/ --all

    # print the "foo"" annotation
    kustomize config tree my-dir/ --field "metadata.annotations.foo"

    # print the "foo"" annotation
    kubectl get all -o yaml | kustomize config tree \
      --field="status.conditions[type=Completed].status"

    # print live Resources from a cluster using owners for graph structure
    kubectl get all -o yaml | kustomize config tree --replicas --name --image \
      --graph-structure=owners

    # print live Resources with status condition fields
    kubectl get all -o yaml | kustomize config tree \
      --name --image --replicas \
      --field="status.conditions[type=Completed].status" \
      --field="status.conditions[type=Complete].status" \
      --field="status.conditions[type=Ready].status" \
      --field="status.conditions[type=ContainersReady].status"`