Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update reference docs and book for kpt live #2645

Merged
merged 2 commits into from
Jan 13, 2022
Merged

Update reference docs and book for kpt live #2645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
00946a8
Update reference docs and book for kpt live
mortent Jan 12, 2022
ce5a47b
Address comments
mortent Jan 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 18 additions & 6 deletions internal/docs/generated/livedocs/docs.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

54 changes: 40 additions & 14 deletions site/book/06-deploying-packages/02-applying-a-package.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,19 @@ deployment.apps/wordpress-mysql created
persistentvolumeclaim/mysql-pv-claim created
persistentvolumeclaim/wp-pv-claim created
6 resource(s) applied. 6 created, 0 unchanged, 0 configured, 0 failed
0 resource(s) pruned, 0 skipped, 0 failed
service/wordpress reconcile pending
service/wordpress-mysql reconcile pending
deployment.apps/wordpress reconcile pending
deployment.apps/wordpress-mysql reconcile pending
persistentvolumeclaim/mysql-pv-claim reconcile pending
persistentvolumeclaim/wp-pv-claim reconcile pending
service/wordpress reconciled
service/wordpress-mysql reconciled
persistentvolumeclaim/mysql-pv-claim reconciled
persistentvolumeclaim/wp-pv-claim reconciled
deployment.apps/wordpress-mysql reconciled
deployment.apps/wordpress reconciled
6 resource(s) reconciled, 0 skipped, 0 failed to reconcile, 0 timed out
```

?> Refer to the [apply command reference][apply-doc] for usage.
Expand Down Expand Up @@ -58,14 +70,15 @@ would see that 6 resources would be created:

```shell
$ kpt live apply wordpress --dry-run
service/wordpress created (dry-run)
service/wordpress-mysql created (dry-run)
deployment.apps/wordpress created (dry-run)
deployment.apps/wordpress-mysql created (dry-run)
persistentvolumeclaim/mysql-pv-claim created (dry-run)
persistentvolumeclaim/wp-pv-claim created (dry-run)
6 resource(s) applied. 6 created, 0 unchanged, 0 configured, 0 failed (dry-run)
0 resource(s) pruned, 0 skipped, 0 failed (dry-run)
Dry-run strategy: client
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am thinking if there is a good way to indicate the steps are running in dry-run mode. I could imagine myself mid-way freaking out if I actually applied or it's dry-run and I will have to scroll back to look at the command args.

The previous layout with (dry-run suffix wasn't terrible. What's the reasoning behind this change ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There have been some discussions around this. The previous output format is just very verbose, as the output on every line is identical, and in fact only prints the value of the flag provided through the flag. This also aligns the different output formats, as only the events output format had the dry-run suffix.

service/wordpress created
service/wordpress-mysql created
deployment.apps/wordpress created
deployment.apps/wordpress-mysql created
persistentvolumeclaim/mysql-pv-claim created
persistentvolumeclaim/wp-pv-claim created
6 resource(s) applied. 6 created, 0 unchanged, 0 configured, 0 failed
0 resource(s) pruned, 0 skipped, 0 failed
```

When combined with server-side apply, the resources in the package pass through
Expand All @@ -77,12 +90,12 @@ After you have deployed the package, you can get its current status at any time:

```shell
$ kpt live status wordpress
deployment.apps/wordpress is InProgress: Available: 0/1
persistentvolumeclaim/wp-pv-claim is InProgress: PVC is not Bound. phase: Pending
service/wordpress is Current: Service is ready
service/wordpress-mysql is Current: Service is ready
deployment.apps/wordpress is Current: Deployment is available. Replicas: 1
deployment.apps/wordpress-mysql is Current: Deployment is available. Replicas: 1
persistentvolumeclaim/mysql-pv-claim is Current: PVC is Bound
deployment.apps/wordpress-mysql is InProgress: Available: 0/1
service/wordpress is Current: Service is ready
persistentvolumeclaim/wp-pv-claim is Current: PVC is Bound
```

?> Refer to the [status command reference][status-doc] for usage.
Expand All @@ -100,7 +113,20 @@ deployment.apps/wordpress-mysql deleted
deployment.apps/wordpress deleted
service/wordpress-mysql deleted
service/wordpress deleted
6 resource(s) deleted, 0 skipped
6 resource(s) deleted, 0 skipped, 0 failed to delete
persistentvolumeclaim/wp-pv-claim reconcile pending
persistentvolumeclaim/mysql-pv-claim reconcile pending
deployment.apps/wordpress-mysql reconcile pending
deployment.apps/wordpress reconcile pending
service/wordpress-mysql reconcile pending
service/wordpress reconcile pending
deployment.apps/wordpress-mysql reconciled
deployment.apps/wordpress reconciled
service/wordpress-mysql reconciled
service/wordpress reconciled
persistentvolumeclaim/mysql-pv-claim reconciled
persistentvolumeclaim/wp-pv-claim reconciled
6 resource(s) reconciled, 0 skipped, 0 failed to reconcile, 0 timed out
```

?> Refer to the [destroy command reference][destroy-doc] for usage.
Expand Down
35 changes: 19 additions & 16 deletions site/book/06-deploying-packages/03-handling-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,21 +51,18 @@ and `Service` are created and reconciled before the Wordpress `Deployment` and `
$ kpt live apply wordpress-with-dependencies --reconcile-timeout=2m
service/wordpress-mysql created
statefulset.apps/wordpress-mysql created
2 resource(s) applied. 2 created, 0 unchanged, 0 configured, 0 failed
statefulset.apps/wordpress-mysql is NotFound: Resource not found
service/wordpress-mysql is NotFound: Resource not found
service/wordpress-mysql is Current: Service is ready
statefulset.apps/wordpress-mysql is InProgress: Ready: 0/1
statefulset.apps/wordpress-mysql is InProgress: Ready: 0/1
statefulset.apps/wordpress-mysql is Current: Partition rollout complete. updated: 1
deployment.apps/wordpress created
service/wordpress-mysql reconcile pending
statefulset.apps/wordpress-mysql reconcile pending
service/wordpress-mysql reconciled
statefulset.apps/wordpress-mysql reconciled
service/wordpress created
2 resource(s) applied. 2 created, 0 unchanged, 0 configured, 0 failed
deployment.apps/wordpress is NotFound: Resource not found
service/wordpress is NotFound: Resource not found
service/wordpress is Current: Service is ready
deployment.apps/wordpress is InProgress: Available: 0/1
deployment.apps/wordpress is Current: Deployment is available. Replicas: 1
deployment.apps/wordpress created
4 resource(s) applied. 4 created, 0 unchanged, 0 configured, 0 failed
service/wordpress reconcile pending
deployment.apps/wordpress reconcile pending
service/wordpress reconciled
deployment.apps/wordpress reconciled
4 resource(s) reconciled, 0 skipped, 0 failed to reconcile, 0 timed out
```

When you delete the package from the cluster, you can see that
Expand All @@ -74,10 +71,16 @@ resources are deleted in reverse order:
$ kpt live destroy wordpress-with-dependencies
deployment.apps/wordpress deleted
service/wordpress deleted
2 resource(s) deleted, 0 skipped
deployment.apps/wordpress reconciled
service/wordpress reconciled
statefulset.apps/wordpress-mysql deleted
service/wordpress-mysql deleted
2 resource(s) deleted, 0 skipped
4 resource(s) deleted, 0 skipped, 0 failed to delete
statefulset.apps/wordpress-mysql reconcile pending
service/wordpress-mysql reconcile pending
statefulset.apps/wordpress-mysql reconciled
service/wordpress-mysql reconciled
4 resource(s) reconciled, 0 skipped, 0 failed to reconcile, 0 timed out
```

See [depends-on] for more information.
Expand Down
18 changes: 12 additions & 6 deletions site/reference/cli/live/apply/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,18 +88,24 @@ PKG_PATH | -:

--prune-timeout:
The threshold for how long to wait for all pruned resources to be
deleted before giving up. If this flag is not set, kpt live apply will not
wait. In most cases, it would also make sense to set the
deleted before giving up. If this flag is not set, kpt live apply will wait
until interrupted. In most cases, it would also make sense to set the
--prune-propagation-policy to Foreground when this flag is set.

--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.
giving up. If this flag is not set, kpt live apply will wait until
interrupted.

--server-side:
Perform the apply operation server-side rather than client-side.
Default value is false (client-side).

--show-status-events:
The output will include the details on the reconciliation status
for all resources. Default is `false`.

Does not apply for the `table` output format.
```

<!--mdtogo-->
Expand All @@ -114,8 +120,8 @@ $ kpt live apply
```

```shell
# apply resources in the my-dir directory and wait for all the resources to be
# reconciled before pruning
# apply resources in the my-dir directory and wait up until 15 minutes
# for all the resources to be reconciled before pruning
$ kpt live apply --reconcile-timeout=15m my-dir
```

Expand Down
6 changes: 6 additions & 0 deletions site/reference/cli/live/destroy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,12 @@ PKG_PATH | -:
as the status of resources become available.

The default value is ‘events’.

--show-status-events:
The output will include the details on the reconciliation status
for all resources. Default is `false`.

Does not apply for the `table` output format.
```

<!--mdtogo-->
Expand Down
4 changes: 0 additions & 4 deletions site/sidebar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,6 @@
- [FunctionResultList](reference/schema/function-result-list/)
- [ResourceList](reference/schema/resource-list/)
- [CRD Status Convention](reference/schema/crd-status-convention/)
- [Annotations Reference](reference/annotations/)
- [apply-time-mutation](reference/annotations/apply-time-mutation/)
- [depends-on](reference/annotations/depends-on/)
- [local-config](reference/annotations/local-config/)
- [Functions Catalog](https://catalog.kpt.dev/ ":target=_self")
- [Curated](https://catalog.kpt.dev/ ":target=_self")
- [Contrib](https://catalog.kpt.dev/contrib/ ":target=_self")
Expand Down