diff --git a/site/reference/TEMPLATE.md b/site/reference/TEMPLATE.md index 76aef6e3c6..8f3b85e71a 100644 --- a/site/reference/TEMPLATE.md +++ b/site/reference/TEMPLATE.md @@ -14,6 +14,7 @@ not be capitalized, for example `get`, `update`, `fn`. The documentation for each command should be focused and concise. Any fundamental concepts or concerns cutting across many command should be covered in the kpt book and the reference docs should provide deep links to the relevant content. +Args, flags, and env vars should be listed in alphabetical order. ### Synopsis diff --git a/site/reference/live/README.md b/site/reference/live/README.md index 9439ca6765..94860c5db4 100644 --- a/site/reference/live/README.md +++ b/site/reference/live/README.md @@ -1,5 +1,5 @@ --- -title: "Live" +title: "`live`" linkTitle: "live" weight: 3 type: docs @@ -10,14 +10,7 @@ description: > Reconcile configuration files with the live state --> -{{< asciinema key="live" rows="10" preload="1" >}} - -| 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. +`live` contains functionality for deploying local configuration +packages to a cluster. diff --git a/site/reference/live/apply/README.md b/site/reference/live/apply/README.md index 343f44e1af..a086dfd1ee 100644 --- a/site/reference/live/apply/README.md +++ b/site/reference/live/apply/README.md @@ -1,303 +1,77 @@ --- -title: "Apply" +title: "`apply`" linkTitle: "apply" type: docs description: > - Apply a package to the cluster (create, update, delete) + Apply a package to the cluster (create, update, prune). --- -{{< asciinema key="live-apply" rows="10" preload="1" >}} - -Apply creates, updates and deletes resources in the cluster to make the remote +`apply` creates, updates and deletes resources in the cluster to make the remote cluster resources match the local package configuration. -Kpt apply is and extended version of kubectl apply, with added support -for pruning and blocking on resource status. - -Kpt apply has a different usage pattern (args + flags) from kubectl to make -it consistent with other kpt commands. - -#### `kubectl apply` vs `kpt live apply` - -| | `kubectl apply` | `kpt live apply` | -|---------------------|----------------------------|---------------------------| -|Usage | kubectl apply -f /dir | kpt live apply /dir | -|Applied resource set | Not tracked | Tracked | -|Prune | Imperative and error prone | Declarative and reliable | -|Status | Not supported | Supported | - -##### Applied resource set - -This refers to the set of resources in the directory applied to cluster as a -group. `kpt live apply` tracks the state of your applied resource set and -related configuration. This helps `kpt` to reliably reconcile the real world -resources with your configuration changes. - -### Client-Side Apply versus Server-Side Apply - -kpt live apply defaults to client-side apply, so the updates are accomplished -by calculating and sending a patch from the client. Server-side apply -with the `--server-side` flag sends the entire resource to the server -for the update. The server-side flags and functionality are the same -as kubectl. - -### Prune - -kpt live apply will automatically delete resources which have been -previously applied, but which are no longer included. This clean-up -functionality is called pruning. For example, consider a package -which has been applied with the following three resources: - -``` -service-1 (Service) -deployment-1 (Deployment) -config-map-1 (ConfigMap) -``` - -Then imagine the package is updated to contain the following resources, -including a new ConfigMap named `config-map-2` (Notice that `config-map-1` -is not part of the updated package): - -``` -service-1 (Service) -deployment-1 (Deployment) -config-map-2 (ConfigMap) -``` - -When the updated package is applied, `config-map-1` is automatically -deleted (pruned) since it is omitted. - -In order to take advantage of this automatic clean-up, a package must contain -an **Inventory Template**, which is a ConfigMap with a special label. An example is: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: inventory-78889725 - namespace: default - labels: - cli-utils.sigs.k8s.io/inventory-id: b49dd93f-28db-4626-b42d-749dd4c5ba2f -``` - -And the special label is: - -``` -cli-utils.sigs.k8s.io/inventory-id: *b49dd93f-28db-4626-b42d-749dd4c5ba2f* -``` - -`kpt live apply` recognizes this template from the special label, and based -on this kpt will create new inventory object with the metadata of all applied -objects in the ConfigMap's data field. Subsequent `kpt live apply` commands can -then query the inventory object, and calculate the omitted objects, cleaning up -accordingly. On every subsequent apply operation, the inventory object is updated -to reflect the current set of resources. - -### Ordering - -`kpt live apply` will sort the resources before applying them. This makes sure -namespaces are applied before resources going into the namespace, configmaps -are applied before Deployments and StatefulSets, and other known dependencies -between the builtin kubernetes resource types. Kpt does not analyze the actual -dependencies between the resources, but sorts the resources based on the Kind -of resources. Custom ordering of resources is not supported. - -During pruning, the same rules are used, but resources will be deleted in -reverse order. Note that this does not wait for a resource to be deleted -before continuing to delete the remaining resources. - -The following resources will be applied first in this order: - -* Namespace -* ResourceQuota -* StorageClass -* CustomResourceDefinition -* MutatingWebhookConfiguration -* ServiceAccount -* PodSecurityPolicy -* Role -* ClusterRole -* RoleBinding -* ClusterRoleBinding -* ConfigMap -* Secret -* Service -* LimitRange -* PriorityClass -* Deployment -* StatefulSet -* CronJob -* PodDisruptionBudget - -Following this, any resources that are not mentioned will be applied. - -The following resources will be applied last in the following order: - -* ValidatingWebhookConfiguration - -### Status (reconcile-timeout=\) - -kpt live apply also has support for computing status for resources. This is -useful during apply for making sure that not only are the set of resources applied -into the cluster, but also that the desired state expressed in the resource are -fully reconciled in the cluster. An example of this could be applying a deployment. Without -looking at the status, the operation would be reported as successful as soon as the -deployment resource has been created in the apiserver. With status, kpt live apply will -wait until the desired number of pods have been created and become available. - -Status is computed through a set of rules for the built-in types, and -functionality for polling a set of resources and computing the aggregate status -for the set. For CRDs, the status computation make a set of assumptions about -the fields in the status object of the resource and the conditions that -are set by the custom controller. If CRDs follow the recommendations below, -kpt live apply will be able to correctly compute status - -#### Recommendations for CRDs - -The custom controller should use the following conditions to signal whether -a resource has been fully reconciled, and whether it has encountered any -problems: - -**Reconciling**: Indicates that the resource does not yet match its spec. i.e. -the desired state as expressed in the resource spec object has not been -fully realized in the cluster. A value of True means the controller -is in the process of reconciling the resource while a value of False means -there are no work left for the controller. - -**Stalled**: Indicates that the controller is not able to make the expected -progress towards reconciling the resource. The cause of this status can be -either that the controller observes an actual problem (like a pod not being -able to start), or that something is taking longer than expected (similar -to the `progressDeadlineSeconds` timeout on Deployments). If this condition -is True, it should be interpreted that something might be wrong. It does not -mean that the resource will never be reconciled. Most process in Kubernetes -retry forever, so this should not be considered a terminal state. - -These conditions adhere to the [Kubernetes design principles] -which include expressing conditions using abnormal-true polarity. There is -currently a [proposal] to change to guidance for conditions. If this is -accepted, the recommended conditions for kpt might also change, but we will -continue to support the current set of conditions. - -CRDs should also set the `observedGeneration` field in the status object, a -pattern already common in the built-in types. The controller should update -this field every time it sees a new generation of the resource. This allows -the kpt library to distinguish between resources that do not have any -conditions set because they are fully reconciled, from resources that have no -conditions set because they have just been created. - -An example of a resource where the latest change has been observed by -the controller which is currently in the process of reconciling would be: - -```yaml -apiVersion: example.com -kind: Foo -metadata: - generation: 12 - name: bar -spec: - replicas: 1 -status: - observedGeneration: 12 - conditions: - - lastTransitionTime: "2020-03-25T21:20:38Z" - lastUpdateTime: "2020-03-25T21:20:38Z" - message: Resource is reconciling - reason: Reconciling - status: "True" - type: Reconciling - - lastTransitionTime: "2020-03-25T21:20:27Z" - lastUpdateTime: "2020-03-25T21:20:39Z" - status: "False" - type: Stalled -``` - -The status for this resource state will be InProgress. So if the -`--reconcile-timeout` flag is set, kpt live apply will wait until -the `Reconciling` condition is `False` before pruning and exiting. - -### Examples - -{{% hide %}} - - -``` -# Set up workspace for the test. -TEST_HOME=$(mktemp -d) -cd $TEST_HOME -``` - - -```shell -export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git -kpt pkg get $SRC_REPO/package-examples/helloworld-set@next my-dir -``` - - -``` -kind delete cluster && kind create cluster -``` - - -``` -kpt live install-resource-group -``` - - -``` -kpt live init my-dir -``` - -{{% /hide %}} - - - -```shell -# apply resources and prune -kpt live apply my-dir/ -``` - - -```shell -# apply resources and wait for all the resources to be reconciled before pruning -kpt live apply --reconcile-timeout=15m my-dir/ -``` - - -```shell -# apply resources and specify how often to poll the cluster for resource status -kpt live apply --reconcile-timeout=15m --poll-period=5s my-dir/ -``` - - ### Synopsis ``` -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 @@ -305,33 +79,31 @@ DIR: 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". + Perform the apply operation server-side rather than client-side. + Default value is false (client-side). +``` + ---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". +### Examples ---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". +```shell +# apply resources in the current directory +kpt live apply ``` - -[Kubernetes design principles]: https://www.google.com/url?q=https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md%23typical-status-properties&sa=D&ust=1585160635349000&usg=AFQjCNE3ncANdus3xckLj3fkeupwFUoABw -[proposal]: https://github.com/kubernetes/community/pull/4521 -[kubectl server-side apply]: +```shell +# apply resources in the my-dir directory and wait for all the resources to be +# reconciled before pruning +kpt live apply --reconcile-timeout=15m my-dir +``` + +```shell +# apply resources and specify how often to poll the cluster for resource status +kpt live apply --reconcile-timeout=15m --poll-period=5s my-dir +``` diff --git a/site/reference/live/destroy/README.md b/site/reference/live/destroy/README.md index 2053374077..8903397905 100644 --- a/site/reference/live/destroy/README.md +++ b/site/reference/live/destroy/README.md @@ -1,5 +1,5 @@ --- -title: "Destroy" +title: "`destroy`" linkTitle: "destroy" type: docs description: > @@ -9,64 +9,56 @@ description: > Remove all previously applied resources in a package from the cluster --> -{{< asciinema key="live-destroy" rows="10" preload="1" >}} +`destroy` removes all files belonging to a package from the cluster. -The destroy command removes all files belonging to a package from the cluster. - -### Examples - -{{% hide %}} - - +### Synopsis + ``` -# Set up workspace for the test. -TEST_HOME=$(mktemp -d) -cd $TEST_HOME +kpt live destroy [PKG_PATH|-] ``` - -```shell -export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git -kpt pkg get $SRC_REPO/package-examples/helloworld-set@next my-dir -``` - - -``` -kind delete cluster && kind create cluster -``` +#### Args - ``` -kpt live install-resource-group +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. ``` - -``` -kpt live init my-dir -kpt live apply my-dir +#### 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`. -{{% /hide %}} +--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. - - -```shell -# remove all resources in a package from the cluster -kpt live destroy my-dir/ + The default value is ‘events’. ``` -### Synopsis - -``` -kpt live destroy DIR -``` - -#### Args +### Examples -``` -DIR: - Path to a package directory. The directory must contain exactly - one ConfigMap with the grouping object annotation. + +```shell +# remove all resources in the current package from the cluster. +kpt live destroy ``` diff --git a/site/reference/live/diff/README.md b/site/reference/live/diff/README.md index 5d8bb2f31f..a05de94d4a 100644 --- a/site/reference/live/diff/README.md +++ b/site/reference/live/diff/README.md @@ -1,53 +1,59 @@ --- -title: "Diff" +title: "`diff`" linkTitle: "diff" type: docs description: > - Diff the local package config against the live cluster resources + Display the diff between the local package and the live cluster resources. --- -The diff command compares the live cluster state of each pacakge -resource against the local package config. - -### Examples - -```shell -# 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/ -``` - +`diff` compares the live cluster state of each package resource against the +local package config. ### Synopsis ``` -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 +``` +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 ``` -DIR: - Path to a package directory. The directory must contain exactly one ConfigMap with the inventory annotation. +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 Status +#### Exit statuses +``` +The following exit values are returned: + * 0: No differences were found. + * 1: Differences were found. + * >1 kpt live or diff failed with an error. ``` -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. +### Examples + +```shell +# diff the config in the current directory against the live cluster resources. +kpt live diff -Note: KUBECTL_EXTERNAL_DIFF, if used, is expected to follow that convention. +# specify the local diff program to use. +export KUBECTL_EXTERNAL_DIFF=meld; kpt live diff my-dir ``` diff --git a/site/reference/live/fetch-k8s-schema/README.md b/site/reference/live/fetch-k8s-schema/README.md deleted file mode 100644 index 992cc14729..0000000000 --- a/site/reference/live/fetch-k8s-schema/README.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Fetch-k8s-schema" -linkTitle: "fetch-k8s-schema" -type: docs -description: > - Fetch the OpenAPI schema from the cluster ---- - - -The fetch-k8s-schema command downloads the OpenAPI schema from the cluster -given by the context. It prints the result to stdout. - -### Examples - -```shell -# print the schema for the cluster given by the current context -kpt live fetch-k8s-schema - -# print the schema after formatting using a named context -kpt live fetch-k8s-schema --context=myContext --pretty-print -``` - - -### Synopsis - -``` -kpt live fetch-k8s-schema [flags] -``` - -#### Flags - -``` ---pretty-print - Format the output before printing -``` - diff --git a/site/reference/live/init/README.md b/site/reference/live/init/README.md index dea1b06a28..c044471530 100644 --- a/site/reference/live/init/README.md +++ b/site/reference/live/init/README.md @@ -1,99 +1,63 @@ --- -title: "Init" +title: "`init`" linkTitle: "init" type: docs description: > - Initialize a package with a object to track previously applied resources + Initialize a package with the information needed for inventory tracking. --- -{{< asciinema key="live-init" rows="10" preload="1" >}} +`init` initializes the package with the name, namespace and id of the resource +that will keep track of the package inventory. -The init command initializes a package with a template resource which will -be used to track previously applied resources so that they can be pruned -when they are deleted. - -The template resource is required by other live commands -such as apply, preview and destroy. - -### Examples - -{{% hide %}} - - -``` -# Set up workspace for the test. -TEST_HOME=$(mktemp -d) -cd $TEST_HOME +### Synopsis + ``` - - -```shell -export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git -kpt pkg get $SRC_REPO/package-examples/helloworld-set@next my-dir +kpt live init [PKG_PATH] [flags] ``` - +#### Args ``` -kind delete cluster && kind create cluster +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. ``` - -``` -kpt live install-resource-group +#### Flags ``` +--force: + Forces the inventory values to be updated, even if they are already set. + Defaults to false. -{{% /hide %}} +--inventory-id: + 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. - -```shell -# initialize a package -kpt live init my-dir/ +--namespace: + 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. ``` + -{{% hide %}} +### Examples + - ```shell -rm -r my-dir -kpt pkg get $SRC_REPO/package-examples/helloworld-set@next my-dir +# initialize a package in the current directory. +kpt live init ``` -{{% /hide %}} - - ```shell -# initialize a package with a specific name for the group of resources -kpt live init --namespace=test my-dir/ -``` - - -### Synopsis - -``` -kpt live init DIRECTORY [flags] -``` - -#### Args - -``` -DIR: - Path to a package directory. The directory must contain exactly - one ConfigMap with the grouping object annotation. -``` - -#### Flags - -``` ---inventory-id: - Identifier for group of applied resources. Must be composed of valid label characters. ---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. +# initialize a package with a specific name for the group of resources. +kpt live init --namespace=test my-dir ``` diff --git a/site/reference/live/preview/README.md b/site/reference/live/preview/README.md index 9097373bc2..3615f4a5f9 100644 --- a/site/reference/live/preview/README.md +++ b/site/reference/live/preview/README.md @@ -1,106 +1,91 @@ --- -title: "Preview" +title: "`preview`" linkTitle: "preview" type: docs description: > - Preview prints the changes apply would make to the cluster + Preview the changes apply would make to the cluster --- -{{< asciinema key="live-preview" rows="10" preload="1" >}} - -The preview command will run through the same steps as apply, but -it will only print what would happen when running apply against the current -live cluster state. With the `--server-side` flag, the dry-run will -be performed on resources sent to the server (but not actually applied), -instead of less thorough dry-run calculations on the client. - -### Examples - -{{% hide %}} - - -``` -# Set up workspace for the test. -TEST_HOME=$(mktemp -d) -cd $TEST_HOME -``` - - -```shell -export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git -kpt pkg get $SRC_REPO/package-examples/helloworld-set@next my-dir -``` - - -``` -kind delete cluster && kind create cluster -``` - - -``` -kpt live install-resource-group -``` - - -``` -kpt live init my-dir -``` - -{{% /hide %}} - - - -```shell -# preview apply for a package -kpt live preview my-dir/ -``` - - -```shell -# preview destroy for a package -kpt live preview --destroy my-dir/ -``` - +`preview` shows the operations that will be done when running `apply` or +`destroy` against a cluster. ### Synopsis ``` -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). +``` + + +### Examples + + +```shell +# preview apply for the package in the current directory. +kpt live preview +``` + +```shell +# preview destroy for a package in the my-dir directory. +kpt live preview --destroy my-dir ``` diff --git a/site/reference/live/status/README.md b/site/reference/live/status/README.md index 4861a954b4..6a19e16922 100644 --- a/site/reference/live/status/README.md +++ b/site/reference/live/status/README.md @@ -1,112 +1,82 @@ --- -title: "Status" +title: "`status`" linkTitle: "status" type: docs description: > - Status shows the status for the resources in the cluster +Display the status for the resources in the cluster --- -The status command will print the status for all resources in the live state -that belong to the current inventory. It will use the [Inventory Template] to -look up the set of resources in the inventory in the live state and poll all -those resources for their status until either an exit criteria has been met -or the process is cancelled. - -### Examples - -{{% hide %}} - - -``` -# Set up workspace for the test. -TEST_HOME=$(mktemp -d) -cd $TEST_HOME -``` - - -```shell -export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git -kpt pkg get $SRC_REPO/package-examples/helloworld-set@next my-app -``` - - -``` -kind delete cluster && kind create cluster -``` - - -``` -kpt live install-resource-group -``` - - -``` -kpt live init my-app -kpt live apply my-app -``` - -{{% /hide %}} - - - -```shell -# Monitor status for a set of resources based on manifests. Wait until all -# resources have reconciled. -kpt live status my-app/ -``` - -```shell -# Monitor status for a set of resources based on manifests. Output in table format: -kpt live status my-app/ --poll-until=forever --output=table -``` - +`status` shows the resource status for resources belonging to the package. ### Synopsis ``` -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. ``` -[Inventory Template]: /reference/live/apply/#prune +### Examples + + +```shell +# Monitor status for the resources belonging to the package in the current +# directory. Wait until all resources have reconciled. +kpt live status +``` + +```shell +# 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 +``` + + +[Inventory Template]: /reference/live/apply/#prune \ No newline at end of file