diff --git a/commands/fncmd.go b/commands/fncmd.go index d7e2a93aa3..7305e6a04a 100644 --- a/commands/fncmd.go +++ b/commands/fncmd.go @@ -32,7 +32,6 @@ func GetFnCommand(ctx context.Context, name string) *cobra.Command { Use: "fn", Short: fndocs.FnShort, Long: fndocs.FnLong, - Example: fndocs.FnExamples, Aliases: []string{"functions"}, RunE: func(cmd *cobra.Command, args []string) error { h, err := cmd.Flags().GetBool("help") diff --git a/commands/livecmd.go b/commands/livecmd.go index 712bb19998..39c5dfb372 100644 --- a/commands/livecmd.go +++ b/commands/livecmd.go @@ -78,7 +78,6 @@ func GetLiveCommand(_, version string) *cobra.Command { _ = applyCmd.Flags().MarkHidden("no-prune") applyCmd.Short = livedocs.ApplyShort applyCmd.Long = livedocs.ApplyShort + "\n" + livedocs.ApplyLong - applyCmd.Example = livedocs.ApplyExamples previewCmd := preview.GetPreviewRunner(p, l, ioStreams).Command previewCmd.Short = livedocs.PreviewShort diff --git a/commands/pkgcmd.go b/commands/pkgcmd.go index 95b2047067..2d818a092f 100644 --- a/commands/pkgcmd.go +++ b/commands/pkgcmd.go @@ -32,7 +32,6 @@ func GetPkgCommand(ctx context.Context, name string) *cobra.Command { Use: "pkg", Short: pkgdocs.PkgShort, Long: pkgdocs.PkgLong, - Example: pkgdocs.PkgExamples, Aliases: []string{"package"}, RunE: func(cmd *cobra.Command, args []string) error { h, err := cmd.Flags().GetBool("help") diff --git a/internal/docs/generated/fndocs/docs.go b/internal/docs/generated/fndocs/docs.go index 2af860fa8b..04835c894f 100644 --- a/internal/docs/generated/fndocs/docs.go +++ b/internal/docs/generated/fndocs/docs.go @@ -1,29 +1,10 @@ // Code generated by "mdtogo"; DO NOT EDIT. package fndocs -var FnShort = `Generate, transform, and validate configuration files.` +var FnShort = `Transform and validate packages using containerized functions.` var FnLong = ` -| Configuration Read From | Configuration Written To | -| ----------------------- | ------------------------ | -| local files or stdin | local files or stdout | - -Functions are executables (that you can [write][Functions Developer Guide]) -which accept a collection of Resource configuration as input, and emit a -collection of Resource configuration as output. - -Functions can be packaged as container images, starlark scripts, or binary -executables. -` -var FnExamples = ` - # run the function defined by gcr.io/example.com/my-fn as a local container - # against the configuration in DIR - kpt fn run DIR/ --image gcr.io/example.com/my-fn - - # run the functions declared in files under FUNCTIONS_DIR/ - kpt fn run DIR/ --fn-path FUNCTIONS_DIR/ - - # run the functions declared in files under DIR/ - kpt fn run DIR/ +The ` + "`" + `fn` + "`" + ` command group contains subcommands for transforming and validating ` + "`" + `kpt` + "`" + ` packages +using containerized functions. ` var DocShort = `Display the documentation for a function` diff --git a/internal/docs/generated/livedocs/docs.go b/internal/docs/generated/livedocs/docs.go index 97e64fee24..736dcc3304 100644 --- a/internal/docs/generated/livedocs/docs.go +++ b/internal/docs/generated/livedocs/docs.go @@ -1,37 +1,67 @@ // Code generated by "mdtogo"; DO NOT EDIT. package livedocs -var LiveShort = `Reconcile configuration files with the live state` +var LiveShort = `Deploy local packages to a cluster.` var LiveLong = ` -| Reads From | Writes To | -|-------------------------|--------------------------| -| local files | cluster | -| cluster | stdout | - -Live contains the next-generation versions of apply related commands for -deploying local configuration packages to a cluster. +The ` + "`" + `live` + "`" + ` command group contains subcommands for deploying local +` + "`" + `kpt` + "`" + ` packages to a cluster. ` -var ApplyShort = `Apply a package to the cluster (create, update, delete)` +var ApplyShort = `Apply a package to the cluster (create, update, prune).` var ApplyLong = ` - kpt live apply DIR [flags] + kpt live apply [PKG_PATH|-] [flags] Args: - - DIR: - Path to a package directory. The directory must contain exactly - one ConfigMap with the inventory object annotation. + PKG_PATH|-: + Path to the local package which should be applied to the cluster. It must + contain a Kptfile with inventory information. Defaults to the current working + directory. + Using '-' as the package path will cause kpt to read resources from stdin. Flags: - + --field-manager: + Identifier for the **owner** of the fields being applied. Only usable + when --server-side flag is specified. Default value is kubectl. + + --force-conflicts: + Force overwrite of field conflicts during apply due to different field + managers. Only usable when --server-side flag is specified. + Default value is false (error and failure when field managers conflict). + + --install-resource-group: + Install the ResourceGroup CRD into the cluster if it isn't already + available. Default is false. + + --inventory-policy: + Determines how to handle overlaps between the package being currently applied + and existing resources in the cluster. The available options are: + + * strict: If any of the resources already exist in the cluster, but doesn't + belong to the current package, it is considered an error. + * adopt: If a resource already exist in the cluster, but belongs to a + different package, it is considered an error. Resources that doesn't belong + to other packages are adopted into the current package. + + The default value is ` + "`" + `strict` + "`" + `. + + --output: + Determines the output format for the status information. Must be one of the following: + + * events: The output will be a list of the status events as they become available. + * json: The output will be a list of the status events as they become available, + each formatted as a json object. + * table: The output will be presented as a table that will be updated inline + as the status of resources become available. + + The default value is ‘events’. + --poll-period: The frequency with which the cluster will be polled to determine - the status of the applied resources. The default value is every 2 seconds. + the status of the applied resources. The default value is 2 seconds. - --reconcile-timeout: - The threshold for how long to wait for all resources to reconcile before - giving up. If this flag is not set, kpt live apply will not wait for - resources to reconcile. + --prune-propagation-policy: + The propagation policy that should be used when pruning resources. The + default value here is 'Background'. The other options are 'Foreground' and 'Orphan'. --prune-timeout: The threshold for how long to wait for all pruned resources to be @@ -39,217 +69,244 @@ Flags: wait. In most cases, it would also make sense to set the --prune-propagation-policy to Foreground when this flag is set. - --prune-propagation-policy: - The propagation policy kpt live apply should use when pruning resources. The - default value here is Background. The other options are Foreground and Orphan. - - --output: - This determines the output format of the command. The default value is - events, which will print the events as they happen. The other option is - table, which will show the output in a table format. + --reconcile-timeout: + The threshold for how long to wait for all resources to reconcile before + giving up. If this flag is not set, kpt live apply will not wait for + resources to reconcile. --server-side: - Boolean which sends the entire resource to the server during apply instead of - calculating a client-side patch. Default value is false (client-side). Available - in version v0.36.0 and above. If not available, the user will see: "error: unknown flag". - - --field-manager: - String specifying the **owner** of the fields being applied. Only usable - when --server-side flag is specified. Default value is kubectl. Available in - version v0.36.0 and above. If not available, the user will see: "error: unknown flag". - - --force-conflicts: - Boolean which forces overwrite of field conflicts during apply due to - different field managers. Only usable when --server-side flag is specified. - Default value is false (error and failure when field managers conflict). - Available in v0.36.0 and above. If not available, the user will see: "error: unknown flag". -` -var ApplyExamples = ` - # apply resources and prune - kpt live apply my-dir/ - - # apply resources and wait for all the resources to be reconciled before pruning - kpt live apply --reconcile-timeout=15m my-dir/ - - # apply resources and specify how often to poll the cluster for resource status - kpt live apply --reconcile-timeout=15m --poll-period=5s my-dir/ + Perform the apply operation server-side rather than client-side. + Default value is false (client-side). ` var DestroyShort = `Remove all previously applied resources in a package from the cluster` var DestroyLong = ` - kpt live destroy DIR + kpt live destroy [PKG_PATH|-] Args: - DIR: - Path to a package directory. The directory must contain exactly - one ConfigMap with the grouping object annotation. + PKG_PATH|-: + Path to the local package which should be deleted from the cluster. It must + contain a Kptfile with inventory information. Defaults to the current working + directory. + Using '-' as the package path will cause kpt to read resources from stdin. + +Flags: + --inventory-policy: + Determines how to handle overlaps between the package being currently applied + and existing resources in the cluster. The available options are: + + * strict: If any of the resources already exist in the cluster, but doesn't + belong to the current package, it is considered an error. + * adopt: If a resource already exist in the cluster, but belongs to a + different package, it is considered an error. Resources that doesn't belong + to other packages are adopted into the current package. + + The default value is ` + "`" + `strict` + "`" + `. + + --output: + Determines the output format for the status information. Must be one of the following: + + * events: The output will be a list of the status events as they become available. + * json: The output will be a list of the status events as they become available, + each formatted as a json object. + * table: The output will be presented as a table that will be updated inline + as the status of resources become available. + + The default value is ‘events’. ` var DestroyExamples = ` - # remove all resources in a package from the cluster - kpt live destroy my-dir/ + # remove all resources in the current package from the cluster. + kpt live destroy ` -var DiffShort = `Diff the local package config against the live cluster resources` +var DiffShort = `Display the diff between the local package and the live cluster resources.` var DiffLong = ` - kpt live diff DIR - - Output is always YAML. - - KUBECTL_EXTERNAL_DIFF environment variable can be used to select your own diff command. By default, the "diff" command - available in your path will be run with "-u" (unicode) and "-N" (treat new files as empty) options. + kpt live diff [PKG_PATH|-] Args: - - DIR: - Path to a package directory. The directory must contain exactly one ConfigMap with the inventory annotation. - -Exit Status: - - The following exit values shall be returned: - - 0 No differences were found. 1 Differences were found. >1 kpt live or diff failed with an error. + PKG_PATH|-: + Path to the local package which should be diffed against the cluster. It must + contain a Kptfile with inventory information. Defaults to the current working + directory. + Using '-' as the package path will cause kpt to read resources from stdin. + +Environment Variables: + KUBECTL_EXTERNAL_DIFF: + Commandline diffing tool ('diff; by default) that will be used to show + changes. + + # Use meld to show changes + KPT_EXTERNAL_DIFF=meld kpt live diff + +Exit statuses: + The following exit values are returned: - Note: KUBECTL_EXTERNAL_DIFF, if used, is expected to follow that convention. + * 0: No differences were found. + * 1: Differences were found. + * >1 kpt live or diff failed with an error. ` var DiffExamples = ` - # diff the config in "my-dir" against the live cluster resources - kpt live diff my-dir/ - - # specify the local diff program to use - export KUBECTL_EXTERNAL_DIFF=meld; kpt live diff my-dir/ -` - -var FetchK8sSchemaShort = `Fetch the OpenAPI schema from the cluster` -var FetchK8sSchemaLong = ` - kpt live fetch-k8s-schema [flags] - -Flags: - - --pretty-print - Format the output before printing -` -var FetchK8sSchemaExamples = ` - # print the schema for the cluster given by the current context - kpt live fetch-k8s-schema + # diff the config in the current directory against the live cluster resources. + kpt live diff - # print the schema after formatting using a named context - kpt live fetch-k8s-schema --context=myContext --pretty-print + # specify the local diff program to use. + export KUBECTL_EXTERNAL_DIFF=meld; kpt live diff my-dir ` -var InitShort = `Initialize a package with a object to track previously applied resources` +var InitShort = `Initialize a package with the information needed for inventory tracking.` var InitLong = ` - kpt live init DIRECTORY [flags] + kpt live init [PKG_PATH] [flags] Args: - - DIR: - Path to a package directory. The directory must contain exactly - one ConfigMap with the grouping object annotation. + PKG_PATH: + Path to the local package which should be updated with inventory information. + It must contain a Kptfile. Defaults to the current working directory. Flags: - + --force: + Forces the inventory values to be updated, even if they are already set. + Defaults to false. + --inventory-id: - Identifier for group of applied resources. Must be composed of valid label characters. + Inventory identifier for the package. This is used to detect overlap between + packages that might use the same name and namespace for the inventory object. + Defaults to an auto-generated value. + + --name: + The name for the ResourceGroup resource that contains the inventory + for the package. Defaults to the name of the package. + --namespace: - namespace for the inventory object. If not provided, kpt will check if all the resources - in the package belong in the same namespace. If they are, that namespace will be used. If - they are not, the namespace in the user's context will be chosen. + The namespace for the ResourceGroup resource that contains the inventory + for the package. If not provided, kpt will check if all the resources + in the package belong in the same namespace. If they do, that namespace will + be used. If they do not, the namespace in the user's context will be chosen. ` var InitExamples = ` - # initialize a package - kpt live init my-dir/ - + # initialize a package in the current directory. + kpt live init - - # initialize a package with a specific name for the group of resources - kpt live init --namespace=test my-dir/ + # initialize a package with a specific name for the group of resources. + kpt live init --namespace=test my-dir ` -var PreviewShort = `Preview prints the changes apply would make to the cluster` +var PreviewShort = `Preview the changes apply would make to the cluster` var PreviewLong = ` - kpt live preview DIRECTORY [flags] + kpt live preview [PKG_PATH|-] [flags] Args: - DIRECTORY: - One directory that contain k8s manifests. The directory - must contain exactly one ConfigMap with the grouping object annotation. + PKG_PATH|-: + Path to the local package for which a preview of the operations of apply + or destroy should be displayed. It must contain a Kptfile with inventory + information. Defaults to the current working directory. + Using '-' as the package path will cause kpt to read resources from stdin. Flags: --destroy: - If true, dry-run deletion of all resources. - - --server-side: - Boolean which performs the dry-run by sending the resource to the server. - Default value is false (client-side dry-run). Available - in version v0.36.0 and above. If not available, the user will see: - "error: unknown flag". + If true, preview deletion of all resources. --field-manager: - String that can be set if --server-side flag is also set, which defines - the resources field owner during dry-run. Available - in version v0.36.0 and above. If not available, the user will see: - "error: unknown flag". + Identifier for the **owner** of the fields being applied. Only usable + when --server-side flag is specified. Default value is kubectl. --force-conflicts: - Boolean that can be set if --server-side flag is also set, which overrides - field ownership conflicts during dry-run. Available - in version v0.36.0 and above. If not available, the user will see: - "error: unknown flag". + Force overwrite of field conflicts during apply due to different field + managers. Only usable when --server-side flag is specified. + Default value is false (error and failure when field managers conflict). + + --install-resource-group: + Install the ResourceGroup CRD into the cluster if it isn't already + available. Default is false. + + --inventory-policy: + Determines how to handle overlaps between the package being currently applied + and existing resources in the cluster. The available options are: + + * strict: If any of the resources already exist in the cluster, but doesn't + belong to the current package, it is considered an error. + * adopt: If a resource already exist in the cluster, but belongs to a + different package, it is considered an error. Resources that doesn't belong + to other packages are adopted into the current package. + + The default value is ` + "`" + `strict` + "`" + `. + + --output: + Determines the output format for the status information. Must be one of the following: + + * events: The output will be a list of the status events as they become available. + * json: The output will be a list of the status events as they become available, + each formatted as a json object. + * table: The output will be presented as a table that will be updated inline + as the status of resources become available. + + The default value is ‘events’. + + --server-side: + Perform the apply operation server-side rather than client-side. + Default value is false (client-side). ` var PreviewExamples = ` - # preview apply for a package - kpt live preview my-dir/ + # preview apply for the package in the current directory. + kpt live preview - # preview destroy for a package - kpt live preview --destroy my-dir/ + # preview destroy for a package in the my-dir directory. + kpt live preview --destroy my-dir ` -var StatusShort = `Status shows the status for the resources in the cluster` +var StatusShort = `Display shows the status for the resources in the cluster` var StatusLong = ` - kpt live status (DIR | STDIN) [flags] + kpt live status [PKG_PATH|-] [flags] Args: - DIR | STDIN: - Path to a directory if an argument is provided or reading from stdin if left - blank. In both situations one of the manifests must contain exactly one - ConfigMap with the inventory template annotation. + PKG_PATH|-: + Path to the local package for which the status of the package in the cluster + should be displayed. It must contain a Kptfile with inventory information. + Defaults to the current working directory. + Using '-' as the package path will cause kpt to read resources from stdin. Flags: - --poll-period (duration): + --output: + Determines the output format for the status information. Must be one of the following: + + * events: The output will be a list of the status events as they become available. + * json: The output will be a list of the status events as they become available, + each formatted as a json object. + * table: The output will be presented as a table that will be updated inline + as the status of resources become available. + + The default value is ‘events’. + + --poll-period: The frequency with which the cluster will be polled to determine the status - of the applied resources. The default value is every 2 seconds. + of the applied resources. The default value is 2 seconds. - --poll-until (string): + --poll-until: When to stop polling for status and exist. Must be one of the following: - known: Exit when the status for all resources have been found. - current: Exit when the status for all resources have reached the Current status. - deleted: Exit when the status for all resources have reached the NotFound - status, i.e. all the resources have been deleted from the live state. - forever: Keep polling for status until interrupted. + + * known: Exit when the status for all resources have been found. + * current: Exit when the status for all resources have reached the Current status. + * deleted: Exit when the status for all resources have reached the NotFound + status, i.e. all the resources have been deleted from the live state. + * forever: Keep polling for status until interrupted. + The default value is ‘known’. - --output (string): - Determines the output format for the status information. Must be one of the following: - events: The output will be a list of the status events as they become available. - table: The output will be presented as a table that will be updated inline - as the status of resources become available. - The default value is ‘events’. - - --timeout (duration): + --timeout: Determines how long the command should run before exiting. This deadline will be enforced regardless of the value of the --poll-until flag. The default is to wait forever. ` var StatusExamples = ` - # Monitor status for a set of resources based on manifests. Wait until all - # resources have reconciled. - kpt live status my-app/ + # Monitor status for the resources belonging to the package in the current + # directory. Wait until all resources have reconciled. + kpt live status - # Monitor status for a set of resources based on manifests. Output in table format: - kpt live status my-app/ --poll-until=forever --output=table + # Monitor status for the resources belonging to the package in the my-app + # directory. Output in table format: + kpt live status my-app --poll-until=forever --output=table ` diff --git a/internal/docs/generated/overview/docs.go b/internal/docs/generated/overview/docs.go index d61901af23..e4f1e7c02a 100644 --- a/internal/docs/generated/overview/docs.go +++ b/internal/docs/generated/overview/docs.go @@ -3,39 +3,15 @@ package overview var ReferenceShort = `Overview of kpt commands` var ReferenceLong = ` -kpt functionality is subdivided into the following command groups, each of +Usage: kpt \ \ \ [PKG_PATH] [flags] + +kpt functionality is divided into the following command groups, each of which operates on a particular set of entities, with a consistent command syntax and pattern of inputs and outputs. -| Command Group | Description | Reads From | Writes To | -| ------------- | ------------------------------------------------------------------------------- | --------------- | --------------- | -| [pkg] | fetch, update, and sync configuration files using git | remote git | local directory | -| [fn] | generate, transform, validate configuration files using containerized functions | local directory | local directory | -| [live] | reconcile the live state with configuration files | local directory | remote cluster | -` -var ReferenceExamples = ` - # get a package - $ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld-set@next helloworld - fetching package /package-examples/helloworld-set from \ - https://github.com/GoogleContainerTools/kpt to helloworld - - # list setters and set a value - $ kpt cfg list-setters helloworld - NAME DESCRIPTION VALUE TYPE COUNT SETBY - http-port 'helloworld port' 80 integer 3 - image-tag 'hello-world image tag' v0.3.0 string 1 - replicas 'helloworld replicas' 5 integer 1 - - $ kpt cfg set helloworld replicas 3 --set-by pwittrock --description 'reason' - set 1 fields - - # get a package and run a validation function - kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-sdk.git/example-configs example-configs - mkdir results/ - kpt fn run example-configs/ --results-dir results/ --image gcr.io/kpt-functions/validate-rolebinding:results -- subject_name=bob@foo-corp.com - - # apply the package to a cluster - $ kpt live apply --reconcile-timeout=10m helloworld - ... - all resources has reached the Current status +| Group | Description | +| --------| ------------------------------------------------------------------------| +| pkg | get, update, and describe packages with resources. | +| fn | generate, transform, validate packages using containerized functions. | +| live | deploy local configuration packages to a cluster. | ` diff --git a/internal/docs/generated/pkgdocs/docs.go b/internal/docs/generated/pkgdocs/docs.go index 67a8c107ce..3fd2acc568 100644 --- a/internal/docs/generated/pkgdocs/docs.go +++ b/internal/docs/generated/pkgdocs/docs.go @@ -1,13 +1,10 @@ // Code generated by "mdtogo"; DO NOT EDIT. package pkgdocs -var PkgShort = `Fetch, update, and sync configuration files using git` +var PkgShort = `Get, update, and describe packages with resources` var PkgLong = ` -The ` + "`" + `pkg` + "`" + ` command group contains subcommands for fetching and updating ` + "`" + `kpt` + "`" + ` package +The ` + "`" + `pkg` + "`" + ` command group contains subcommands for fetching, updating and describing ` + "`" + `kpt` + "`" + ` packages from git repositories. -` -var PkgExamples = ` - ` var CatShort = `Print the resources in a file/directory` diff --git a/run/run.go b/run/run.go index 1e544405b8..19a294a2e1 100644 --- a/run/run.go +++ b/run/run.go @@ -41,7 +41,6 @@ func GetMain(ctx context.Context) *cobra.Command { Use: "kpt", Short: overview.ReferenceShort, Long: overview.ReferenceLong, - Example: overview.ReferenceExamples, SilenceUsage: true, // We handle all errors in main after return from cobra so we can // adjust the error message coming from libraries diff --git a/site/reference/README.md b/site/reference/README.md index 83027b8a62..49a6b7bc3a 100755 --- a/site/reference/README.md +++ b/site/reference/README.md @@ -7,186 +7,25 @@ menu: main: weight: 3 description: > - Overview of kpt commands + Overview of kpt commands --- -{{< asciinema key="kpt" rows="10" preload="1" >}} - -kpt functionality is subdivided into the following command groups, each of +Usage: kpt \ \ \ [PKG_PATH] [flags] + +kpt functionality is divided into the following command groups, each of which operates on a particular set of entities, with a consistent command syntax and pattern of inputs and outputs. -| Command Group | Description | Reads From | Writes To | -| ------------- | ------------------------------------------------------------------------------- | --------------- | --------------- | -| [pkg] | fetch, update, and sync configuration files using git | remote git | local directory | -| [fn] | generate, transform, validate configuration files using containerized functions | local directory | local directory | -| [live] | reconcile the live state with configuration files | local directory | remote cluster | - - - -### Examples - -The following are examples of running each kpt command group. - - - -```shell -# get a package -$ kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/helloworld-set@next helloworld -fetching package /package-examples/helloworld-set from \ - https://github.com/GoogleContainerTools/kpt to helloworld -``` - -```shell -# list setters and set a value -$ kpt cfg list-setters helloworld -NAME DESCRIPTION VALUE TYPE COUNT SETBY -http-port 'helloworld port' 80 integer 3 -image-tag 'hello-world image tag' v0.3.0 string 1 -replicas 'helloworld replicas' 5 integer 1 - -$ kpt cfg set helloworld replicas 3 --set-by pwittrock --description 'reason' -set 1 fields -``` - -```shell -# get a package and run a validation function -kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-sdk.git/example-configs example-configs -mkdir results/ -kpt fn run example-configs/ --results-dir results/ --image gcr.io/kpt-functions/validate-rolebinding:results -- subject_name=bob@foo-corp.com -``` - -```shell -# apply the package to a cluster -$ kpt live apply --reconcile-timeout=10m helloworld -... -all resources has reached the Current status -``` +| Group | Description | +| --------| ------------------------------------------------------------------------| +| pkg | get, update, and describe packages with resources. | +| fn | generate, transform, validate packages using containerized functions. | +| live | deploy local configuration packages to a cluster. | - -### OpenAPI schema - -Kpt relies on the OpenAPI schema for Kubernetes to understand the structure -of kubernetes manifests. Kpt already comes with a builtin -OpenAPI schema, but that will obviously not include any CRDs. So in some -situations it might be beneficial to use a schema that accurately reflects both -the correct version of Kubernetes and the CRDs used. Kpt provides a few global -flags to allows users to specify the schema that should be used. - -By default, kpt will use the builtin schema. - -```shell ---k8s-schema-source - Set the source for the OpenAPI schema. Allowed values are cluster, file, or - builtin. If an OpenAPI schema can't be find at the given source, kpt will - return an error. - ---k8s-schema-path - The path to an OpenAPI schema file. The default value is ./openapi.json -``` - -### Global flags - -Kpt exposes many global flags in addition to the ones listed above to allow -customization of how kpt works. This is primarily around logging and how kpt -connects to your kubernetes cluster. Some flags that are unlikely to be useful -to most users are hidden in the cli, but this section lists all flags accepted -by kpt. - -``` ---add_dir_header - If true, adds the file directory to the header ---alsologtostderr - log to standard error as well as files ---as string - Username to impersonate for the operation ---as-group stringArray - Group to impersonate for the operation, this flag can be repeated to - specify multiple groups. ---cache-dir string - Default HTTP cache directory (default "/Users//.kube/http-cache") ---certificate-authority string - Path to a cert file for the certificate authority ---client-certificate string - Path to a client certificate file for TLS ---client-key string - Path to a client key file for TLS ---cluster string - The name of the kubeconfig cluster to use ---context string - The name of the kubeconfig context to use --h, --help - Help for kpt ---insecure-skip-tls-verify - If true, the servers certificate will not be checked for validity. - This will make your HTTPS connections insecure ---install-completion - Install shell completion ---k8s-schema-path string - Path to the kubernetes openAPI schema file (default "./openapi.json") ---k8s-schema-source string - Source for the kubernetes openAPI schema (default "builtin") ---kubeconfig string - Path to the kubeconfig file to use for CLI requests. ---log-flush-frequency duration - Maximum number of seconds between log flushes (default 5s) ---log_backtrace_at traceLocation - When logging hits line file:N, emit a stack trace (default :0) ---log_dir string - If non-empty, write log files in this directory ---log_file string - If non-empty, use this log file ---log_file_max_size uint - Defines the maximum size a log file can grow to. Unit is megabytes. - If the value is 0, the maximum file size is unlimited. (default 1800) ---logtostderr - Log to standard error instead of files (default true) ---match-server-version - Require server version to match client version --n, --namespace string - If present, the namespace scope for this CLI request ---password string - Password for basic authentication to the API server ---request-timeout string - The length of time to wait before giving up on a single server request. - Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). - A value of zero means don't timeout requests. (default "0") --s, --server string - The address and port of the Kubernetes API server ---skip_headers - If true, avoid header prefixes in the log messages ---skip_log_headers - If true, avoid headers when opening log files ---stack-trace - Print a stack-trace on failure ---stderrthreshold severity - Logs at or above this threshold go to stderr (default 2) ---token string - Bearer token for authentication to the API server ---user string - The name of the kubeconfig user to use ---username string - Username for basic authentication to the API server --v, --v Level - Number for the log level verbosity ---vmodule moduleSpec - Comma-separated list of pattern=N settings for file-filtered logging -``` - -### Next Steps - -- Learn about kpt concepts and usage by reading the kpt [book] -- Consult the [FAQ] for answers to common questions. - -[pkg]: /reference/pkg/ -[fn]: /reference/fn/ -[live]: /reference/live/ -[book]: /book/ -[FAQ]: /faq/ diff --git a/site/reference/fn/README.md b/site/reference/fn/README.md index eedbc44fb8..6dd08ef8e6 100644 --- a/site/reference/fn/README.md +++ b/site/reference/fn/README.md @@ -1,101 +1,17 @@ --- -title: "Fn" +title: "`fn`" linkTitle: "fn" type: docs weight: 4 description: > - Generate, transform, and validate configuration files. + Transform and validate packages using containerized functions. --- - -| Configuration Read From | Configuration Written To | -| ----------------------- | ------------------------ | -| local files or stdin | local files or stdout | - -Functions are executables (that you can [write][Functions Developer Guide]) -which accept a collection of Resource configuration as input, and emit a -collection of Resource configuration as output. - -Functions can be packaged as container images, starlark scripts, or binary -executables. - - - -Functions may be used to: - -- Generate configuration from templates, DSLs, CRD-style abstractions, - key-value pairs, etc.-- e.g. expand Helm charts, JSonnet, Jinja, etc. -- Inject fields or otherwise modify configuration -- e.g.add init-containers, - side-cars, etc -- Rollout configuration changes across an organization -- e.g.similar to - -- Validate configuration -- e.g.ensure organizational policies are enforced - -Functions may be run at different times depending on the function and -the organizational needs: - -- as part of the build and development process -- as pre-commit checks -- as PR checks -- as pre-release checks -- as pre-rollout checks - -### Examples - - - -```shell -# run the function defined by gcr.io/example.com/my-fn as a local container -# against the configuration in DIR -kpt fn run DIR/ --image gcr.io/example.com/my-fn -``` - -```shell -# run the functions declared in files under FUNCTIONS_DIR/ -kpt fn run DIR/ --fn-path FUNCTIONS_DIR/ -``` - -```shell -# run the functions declared in files under DIR/ -kpt fn run DIR/ -``` - - - -#### Using Functions - -The [catalog] documents config functions implemented using different toolchains -like starlark, typescript, and golang. - -#### Developing Functions - -See the [Functions Developer Guide] for more on producing functions. - -| Language | Documentation | Examples | -| ---------- | --------------------------- | --------------------------- | -| Typescript | [Typescript SDK] | [examples][sdk-ts-examples] | -| Go | [Golang Libraries] | [example][golang-example] | -| Shell | Use builtin shell functions | [example][shell-example] | -| Starlark | [Starlark SDK] | [example][starlark-example] | - -## Next Steps - -- Learn how to [run functions]. -- Find out how to structure a pipeline of functions from the - [functions concepts] page. - -[Functions Developer Guide]: /book/05-developing-functions/ -[Typescript SDK]: https://kpt.dev#todo -[sdk-ts-examples]: https://github.com/GoogleContainerTools/kpt-functions-sdk/tree/master/ts/demo-functions/src/ -[Golang Libraries]: https://kpt.dev#todo -[golang-example]: https://github.com/GoogleContainerTools/kpt-functions-catalog/tree/master/functions/go/set-namespace/ -[shell-example]: https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/template-heredoc-cockroachdb/image/cockroachdb-template.sh -[Starlark SDK]: https://kpt.dev#todo -[starlark-example]: https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/starlark/set_namespace.star -[run functions]: /book/04-using-functions/01-running-functions-imperatively -[functions concepts]: /book/04-using-functions/ +The `fn` command group contains subcommands for transforming and validating `kpt` packages +using containerized functions. + \ No newline at end of file diff --git a/site/reference/live/README.md b/site/reference/live/README.md index 94860c5db4..1113522458 100644 --- a/site/reference/live/README.md +++ b/site/reference/live/README.md @@ -4,13 +4,13 @@ linkTitle: "live" weight: 3 type: docs description: > - Reconcile configuration files with the live state + Deploy local packages to a cluster. --- -`live` contains functionality for deploying local configuration -packages to a cluster. +The `live` command group contains subcommands for deploying local +`kpt` packages to a cluster. diff --git a/site/reference/pkg/README.md b/site/reference/pkg/README.md index 20bc16623a..4b2f048e63 100644 --- a/site/reference/pkg/README.md +++ b/site/reference/pkg/README.md @@ -4,16 +4,13 @@ linkTitle: "pkg" weight: 1 type: docs description: > - Fetch, update, and sync configuration files using git + Get, update, and describe packages with resources --- -The `pkg` command group contains subcommands for fetching and updating `kpt` package +The `pkg` command group contains subcommands for fetching, updating and describing `kpt` packages from git repositories. - - -