-
Notifications
You must be signed in to change notification settings - Fork 226
/
docs.go
213 lines (168 loc) · 8.87 KB
/
docs.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
// Copyright 2019 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Code generated by "mdtogo"; DO NOT EDIT.
package livedocs
var READMEShort = `Reconcile configuration files with the live state`
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 ApplyShort = `apply a package to the cluster`
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 DestroyShort = `remove a package from the cluster`
var DestroyLong = `
kpt live destroy DIRECTORY [flags]
The destroy command removes all files belonging to a package from
the cluster.
Args:
DIRECTORY:
One directory that contain k8s manifests. The directory
must contain exactly one ConfigMap with the grouping object annotation.`
var InitShort = `initialize a package by creating a local file`
var InitLong = `
kpt live init DIRECTORY [flags]
The init command initializes the package by locally creating a template
file. When applied, this template file is used to store the state of all
applied objects in a package. This file is necessary for other live
commands (apply/preview/destroy) to work correctly.
Args:
DIRECTORY:
One directory that contain k8s manifests. The directory
must contain exactly one ConfigMap with the grouping object annotation.
Flags:
group-name:
String name to group applied resources. Must be composed of valid
label value characters. If not specified, the default group name
is generated from the package directory name.`
var PreviewShort = `preview shows the changes apply will make against the live state of the cluster`
var PreviewLong = `
kpt live preview DIRECTORY [flags]
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.
Args:
DIRECTORY:
One directory that contain k8s manifests. The directory
must contain exactly one ConfigMap with the grouping object annotation.
Flags:
destroy:
If true, dry-run deletion of all resources.`