livedocs

Documentation

Overview

Code generated by "mdtogo"; DO NOT EDIT.

Index

• Variables

Variables

var ApplyLong = `
    kpt live apply DIRECTORY [flags]

The apply command creates, updates or deletes any resources in the cluster to
make the state of resources in the cluster match the desired state as specified
through the set of manifests. This command is similar to the apply command
available in kubectl, but also has support for pruning and waiting until all
resources has been fully reconciled.

Args:
  DIRECTORY:
    One directory that contain k8s manifests. The directory
    must contain exactly one ConfigMap with the grouping object annotation.
    
Flags:
  wait-for-reconcile:
    If true, after all resources have been applied, the cluster will
    be polled until either all resources have been fully reconciled
    or the timeout is reached.
    
  wait-polling-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.
    
  wait-timeout:
    The threshold for how long to wait for all resources to reconcile before
    giving up. The default value is 1 minute.
    

#### ` + "`" + `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  |
|wait-for-reconcile   | Not supported              | Supported                 |

Usage:
  In terms of usage, both ` + "`" + `kubectl apply` + "`" + ` and ` + "`" + `kpt live apply` + "`" + ` follow similar pattern.
  The user experience remains unchanged.

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.

Prune:
  ` + "`" + `kpt live apply` + "`" + ` can declaratively delete the resources which are not part of your
  applied resource set anymore. ` + "`" + `kubectl apply` + "`" + ` also has a similar functionality with --prune
  flag. However, it heavily depends on labels provided by user, which is imperative and
  error prone. On the other hand, prune is default option for ` + "`" + `kpt live apply` + "`" + ` and app
  state is completely managed and tracked by kpt. The only additional step users should
  perform in order to enjoy the benefits of prune is to add the grouping object ConfigMap
  to your package with UNIQUE label.

wait-for-reconcile:
  ` + "`" + `kubectl apply` + "`" + ` will simply apply the resources. Users must write their own logic
  to poll using ` + "`" + `kubectl get` + "`" + ` to check if the applied resources were fully reconciled.
  ` + "`" + `kpt live apply` + "`" + ` can wait till the resources are fully reconciled with continuous status
  updates.`

var ApplyShort = `apply a package to the cluster`

var DestroyLong = `` /* 275-byte string literal not displayed */

var DestroyShort = `remove a package from the cluster`

var InitLong = `` /* 670-byte string literal not displayed */

var InitShort = `initialize a package by creating a local file`

var PreviewLong = `` /* 431-byte string literal not displayed */

var PreviewShort = `preview shows the changes apply will make against the live state of the cluster`

var READMELong = `
Tool to safely apply and delete kubernetes package resources from clusters.

| Command   | Description                                       |
|-----------|---------------------------------------------------|
| [init]    | initialize a package creating a local file        |
| [apply]   | apply a package to the cluster                    |
| [preview] | preview the operations that apply will perform    |
| [destroy] | remove the package from the cluster               |

**Data Flow**: local configuration or stdin -> kpt live -> apiserver (Kubernetes cluster)

| Configuration Read From | Configuration Written To |
|-------------------------|--------------------------|
| local files             | apiserver                |
| apiserver               | stdout                   |

#### Pruning
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
a **grouping object template**, which is a ConfigMap with a special label. An example is:

	apiVersion: v1
	kind: ConfigMap
	metadata:
	  name: test-grouping-object
	  labels:
	    cli-utils.sigs.k8s.io/inventory-id: test-group

And the special label is:

	cli-utils.sigs.k8s.io/inventory-id: *group-name*

` + "`" + `kpt live apply` + "`" + ` recognizes this template from the special label, and based
on this kpt will create new grouping object with the metadata of all applied
objects in the ConfigMap's data field. Subsequent ` + "`" + `kpt live apply` + "`" + ` commands can
then query the grouping object, and calculate the omitted objects, cleaning up
accordingly. When a grouping object is created in the cluster, a hash suffix
is added to the name. Example:

	test-grouping-object-17b4dba8

#### Status
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 specific types, and
functionality for polling a set of resources and computing the aggregate status
for the set. For CRDs, there is a set of recommendations that if followed, will allow
kpt live apply to correctly compute status.

###

[tutorial-script]: ../gifs/live.sh
[init]: init.md
[apply]: apply.md
[preview]: preview.md
[destroy]: destroy.md`

var READMEShort = `Reconcile configuration files with the live state`