Add doc for DeletionPolicy and Finalizers #14719

xing-yang · 2019-06-04T14:44:57Z

This PR adds doc for snapshot DeletionPolicy
and Finalizers added in Kubernetes v1.13.

Fixes: kubernetes-csi/external-snapshotter#124

This PR adds doc for snapshot DeletionPolicy and Finalizers added in Kubernetes v1.13.

netlify · 2019-06-04T14:54:45Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 1c560a1

https://deploy-preview-14719--kubernetes-io-master-staging.netlify.com

jingxu97 · 2019-06-04T17:18:48Z

content/en/docs/concepts/storage/volume-snapshot-classes.md

+`VolumeSnapshotClass` object is created, it will default to `Delete`.
+
+Volume snapshots that are created manually and managed via a volume snapshot class will have
+whatever deletion policy they were assigned at creation.


I think if user does not specify the policy for manually created volume snapshot and content without a snapshot class will have default value of retain? but need to double check.

never mind, I see your explanation below

jingxu97 · 2019-06-04T17:22:35Z

/lgtm

tengqm · 2019-06-06T01:32:50Z

content/en/docs/concepts/storage/volume-snapshots.md

+The following example demonstrates how to check the deletion policy of a dynamically provisioned `VolumeSnapshotContent`.
+
+```
+$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml


where is the yaml file?

To follow the style guide, don't include the command prompt.

@tengqm Good catch. I need to add the example yaml file here. Should I create a new folder called "storage" under website/content/en/examples and put the yaml file there?

tengqm · 2019-06-06T01:36:26Z

content/en/docs/concepts/storage/volume-snapshots.md

+
+With PV/PVC pairs, when a user is done with a volume, they can delete the PVC. And the reclaim policy on the PV determines what happens to the PV (whether it is also deleted or retained).
+
+In the initial alpha release, snapshots did not support the ability to specify a reclaim policy. Instead when a snapshot object was deleted it always resulted in the snapshot being deleted. In Kubernetes v1.13, a snapshot content `DeletionPolicy` was added. It enables an admin to configure what happens to a `VolumeSnapshotContent` after the `VolumeSnapshot` object it is bound to is deleted. The `DeletionPolicy` of a volume snapshot can either be `Retain` or `Delete`. If the value is not specified, the default depends on whether the `VolumeSnapshotContent` object was created via static binding or dynamic provisioning.


Break the lines at a reasonable column would make the review a bit easier.

"snapshots did not support the ability to specify a reclaim policy." This sounds a wordy sentence though I'm not a native speaker. You could simply say "snapshots did not support reclaim policies".

"Instead when a snapshot object was deleted it always resulted in the snapshot being deleted."

=>

"When a snapshot resource is deleted, the snapshot is deleted as well".

I agree with your suggestion, with just a slight update to the tense, so from:

"In the initial alpha release, snapshots did not support the ability to specify a reclaim policy. Instead when a snapshot object was deleted it always resulted in the snapshot being deleted."

to:

"In the initial alpha release, snapshots did not support reclaim policies. When a snapshot resource was deleted, the snapshot was deleted as well."

tengqm · 2019-06-06T01:38:58Z

/hold
Asking some native speakers for help here.

sftim

Here are some suggestions. One of them is quite a big change: I suggest using a Task page to explain checking and changing the deletion policy for a VolumeSnapshotContent.

sftim · 2019-06-07T11:31:14Z

content/en/docs/concepts/storage/volume-snapshots.md


-Deletion removes both the `VolumeSnapshotContent` object from the Kubernetes API, as well as the associated storage asset in the external infrastructure.
+The purpose of the Snapshot Object in Use Protection feature is to ensure that in-use snapshot API objects are not removed from the system (as this may result in data loss). There are two cases that require “in-use” protection:


Suggested change

The purpose of the Snapshot Object in Use Protection feature is to ensure that in-use snapshot API objects are not removed from the system (as this may result in data loss). There are two cases that require “in-use” protection:

The _Snapshot Object in Use Protection_ feature lets you ensure that in-use snapshot API objects are not removed from the system (as this may result in data loss). There are two cases that require “in-use” protection:

sftim · 2019-06-07T11:32:27Z

content/en/docs/concepts/storage/volume-snapshots.md

-Deletion removes both the `VolumeSnapshotContent` object from the Kubernetes API, as well as the associated storage asset in the external infrastructure.
+The purpose of the Snapshot Object in Use Protection feature is to ensure that in-use snapshot API objects are not removed from the system (as this may result in data loss). There are two cases that require “in-use” protection:
+
+* If a volume snapshot is in active use by a persistent volume claim as a source to create a volume.


Suggested change

* If a volume snapshot is in active use by a persistent volume claim as a source to create a volume.

* If a volume snapshot is in active use by a {{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}} (PVC) as a source to create a Volume.

sftim · 2019-06-07T11:33:50Z

content/en/docs/concepts/storage/volume-snapshots.md

+* If a volume snapshot is in active use by a persistent volume claim as a source to create a volume.
+* If a `VolumeSnapshotContent` API object is bound to a `VolumeSnapshot` API object, the content object is considered in use.
+
+If a user deletes a `VolumeSnapshot` API object in active use by a PVC, the `VolumeSnapshot` object is not removed immediately. Instead, removal of the `VolumeSnapshot` object is postponed until the `VolumeSnapshot` is no longer actively used by any PVCs. Similarly, if an admin deletes a `VolumeSnapshotContent` that is bound to a `VolumeSnapshot`, the `VolumeSnapshotContent` is not removed immediately. Instead, the `VolumeSnapshotContent` removal is postponed until the `VolumeSnapshotContent` is not bound to the `VolumeSnapshot` object.


Suggested change

If a user deletes a `VolumeSnapshot` API object in active use by a PVC, the `VolumeSnapshot` object is not removed immediately. Instead, removal of the `VolumeSnapshot` object is postponed until the `VolumeSnapshot` is no longer actively used by any PVCs. Similarly, if an admin deletes a `VolumeSnapshotContent` that is bound to a `VolumeSnapshot`, the `VolumeSnapshotContent` is not removed immediately. Instead, the `VolumeSnapshotContent` removal is postponed until the `VolumeSnapshotContent` is not bound to the `VolumeSnapshot` object.

If you delete a `VolumeSnapshot` API object that a PVC is actively using, the `VolumeSnapshot` object is not removed immediately. Instead, removal of the `VolumeSnapshot` object is postponed until the `VolumeSnapshot` is no longer actively used by any PVCs. Similarly, if an admin deletes a `VolumeSnapshotContent` that is bound to a `VolumeSnapshot`, the `VolumeSnapshotContent` is not removed immediately. Instead, the `VolumeSnapshotContent` removal is postponed until the `VolumeSnapshotContent` is not bound to the `VolumeSnapshot` object.

sftim · 2019-06-07T11:34:39Z

content/en/docs/concepts/storage/volume-snapshots.md

+
+### VolumeSnapshotContent Deletion/Retain Policy
+
+The Kubernetes snapshot APIs are similar to the PV/PVC APIs: just like a volume is represented by a bound PVC and PV pair, a snapshot is represented by a bound `VolumeSnapshot` and `VolumeSnapshotContent` pair.


Suggested change

The Kubernetes snapshot APIs are similar to the PV/PVC APIs: just like a volume is represented by a bound PVC and PV pair, a snapshot is represented by a bound `VolumeSnapshot` and `VolumeSnapshotContent` pair.

The Kubernetes snapshot APIs are similar to the PV/PVC APIs: just like a volume is represented by a bound PVC and PV pair, a snapshot is represented by a bound VolumeSnapshot and VolumeSnapshotContent pair.

sftim · 2019-06-07T11:36:52Z

content/en/docs/concepts/storage/volume-snapshots.md

+The following example demonstrates how to check the deletion policy of a dynamically provisioned `VolumeSnapshotContent`.
+
+```
+$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml


To follow the style guide, don't include the command prompt.

sftim · 2019-06-07T11:37:22Z

content/en/docs/concepts/storage/volume-snapshots.md

+
+A `Delete` policy enables automatic deletion of the bound `VolumeSnapshotContent` object from Kubernetes and the associated storage asset in the external infrastructure (such as an AWS EBS snapshot or GCE PD snapshot, etc.). Snapshots that are dynamically provisioned inherit the deletion policy of their `VolumeSnapshotClass`, which defaults to `Delete`. The administrator should configure the `VolumeSnapshotClass` with the desired retention policy. The policy may be changed for individual `VolumeSnapshotContent` after it is created by patching the object.
+
+The following example demonstrates how to check the deletion policy of a dynamically provisioned `VolumeSnapshotContent`.


Would this work better as a Task page?

I'm not sure. Does the Task page have a link to the Concept page?

@xing-yang When you create a new task page, you can certainly link to the relevant concept page(s).

tengqm · 2019-06-11T01:17:29Z

@xing-yang We need your help on polishing this one. Thanks!

xing-yang · 2019-06-11T14:28:24Z

@tengqm Sure, I'll update soon. Thanks.

k8s-ci-robot · 2019-06-12T02:24:11Z

New changes are detected. LGTM label has been removed.

k8s-ci-robot · 2019-06-12T02:24:20Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign zacharysarah
You can assign the PR to them by writing /assign @zacharysarah in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

content/en/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

xing-yang · 2019-06-12T02:25:29Z

Addressed comments except for the one about Task page. Thanks.

k8s-ci-robot · 2019-06-25T20:34:53Z

@xing-yang: PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

zacharysarah · 2019-08-06T22:52:57Z

@xing-yang 👋 Thanks for this PR. There's good content here, and I agree with other reviewers that it really belongs as a separate task page. The contribution guidelines can help with creating a new page using a task template.

Please feel free to /reopen when you're ready to continue.

/close

k8s-ci-robot · 2019-08-06T22:52:59Z

@zacharysarah: Closed this PR.

In response to this:

@xing-yang 👋 Thanks for this PR. There's good content here, and I agree with other reviewers that it really belongs as a separate task page. The contribution guidelines can help with creating a new page using a task template.

Please feel free to /reopen when you're ready to continue.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

Add doc for DeletionPolicy and Finalizers

b0306d9

This PR adds doc for snapshot DeletionPolicy and Finalizers added in Kubernetes v1.13.

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Jun 4, 2019

k8s-ci-robot requested review from saad-ali and thockin June 4, 2019 14:45

xing-yang mentioned this pull request Jun 4, 2019

Update deletion policy in snapshot doc kubernetes-csi/external-snapshotter#124

Open

jingxu97 reviewed Jun 4, 2019

View reviewed changes

k8s-ci-robot assigned jingxu97 Jun 4, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 4, 2019

tengqm reviewed Jun 6, 2019

View reviewed changes

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jun 6, 2019

sftim reviewed Jun 7, 2019

View reviewed changes

Address review comments

1c560a1

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 12, 2019

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jun 12, 2019

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 25, 2019

k8s-ci-robot closed this Aug 6, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add doc for DeletionPolicy and Finalizers #14719

Add doc for DeletionPolicy and Finalizers #14719

xing-yang commented Jun 4, 2019

netlify bot commented Jun 4, 2019 •

edited

jingxu97 Jun 4, 2019

jingxu97 Jun 4, 2019

jingxu97 commented Jun 4, 2019

tengqm Jun 6, 2019

sftim Jun 7, 2019

xing-yang Jun 12, 2019

xing-yang Jun 12, 2019

tengqm Jun 6, 2019

tengqm Jun 6, 2019

siforster Jun 6, 2019

xing-yang Jun 12, 2019

tengqm commented Jun 6, 2019

sftim left a comment

sftim Jun 7, 2019

xing-yang Jun 12, 2019

sftim Jun 7, 2019

xing-yang Jun 12, 2019

sftim Jun 7, 2019

xing-yang Jun 12, 2019

sftim Jun 7, 2019

xing-yang Jun 12, 2019

sftim Jun 7, 2019

sftim Jun 7, 2019

xing-yang Jun 12, 2019

zacharysarah Aug 6, 2019

tengqm commented Jun 11, 2019

xing-yang commented Jun 11, 2019

k8s-ci-robot commented Jun 12, 2019

k8s-ci-robot commented Jun 12, 2019

xing-yang commented Jun 12, 2019

k8s-ci-robot commented Jun 25, 2019

zacharysarah commented Aug 6, 2019

k8s-ci-robot commented Aug 6, 2019


		With PV/PVC pairs, when a user is done with a volume, they can delete the PVC. And the reclaim policy on the PV determines what happens to the PV (whether it is also deleted or retained).

		In the initial alpha release, snapshots did not support the ability to specify a reclaim policy. Instead when a snapshot object was deleted it always resulted in the snapshot being deleted. In Kubernetes v1.13, a snapshot content `DeletionPolicy` was added. It enables an admin to configure what happens to a `VolumeSnapshotContent` after the `VolumeSnapshot` object it is bound to is deleted. The `DeletionPolicy` of a volume snapshot can either be `Retain` or `Delete`. If the value is not specified, the default depends on whether the `VolumeSnapshotContent` object was created via static binding or dynamic provisioning.


		Deletion removes both the `VolumeSnapshotContent` object from the Kubernetes API, as well as the associated storage asset in the external infrastructure.
		The purpose of the Snapshot Object in Use Protection feature is to ensure that in-use snapshot API objects are not removed from the system (as this may result in data loss). There are two cases that require “in-use” protection:

	The purpose of the Snapshot Object in Use Protection feature is to ensure that in-use snapshot API objects are not removed from the system (as this may result in data loss). There are two cases that require “in-use” protection:
	The _Snapshot Object in Use Protection_ feature lets you ensure that in-use snapshot API objects are not removed from the system (as this may result in data loss). There are two cases that require “in-use” protection:

	* If a volume snapshot is in active use by a persistent volume claim as a source to create a volume.
	* If a volume snapshot is in active use by a {{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}} (PVC) as a source to create a Volume.


		### VolumeSnapshotContent Deletion/Retain Policy

		The Kubernetes snapshot APIs are similar to the PV/PVC APIs: just like a volume is represented by a bound PVC and PV pair, a snapshot is represented by a bound `VolumeSnapshot` and `VolumeSnapshotContent` pair.


		A `Delete` policy enables automatic deletion of the bound `VolumeSnapshotContent` object from Kubernetes and the associated storage asset in the external infrastructure (such as an AWS EBS snapshot or GCE PD snapshot, etc.). Snapshots that are dynamically provisioned inherit the deletion policy of their `VolumeSnapshotClass`, which defaults to `Delete`. The administrator should configure the `VolumeSnapshotClass` with the desired retention policy. The policy may be changed for individual `VolumeSnapshotContent` after it is created by patching the object.

		The following example demonstrates how to check the deletion policy of a dynamically provisioned `VolumeSnapshotContent`.

Add doc for DeletionPolicy and Finalizers #14719

Add doc for DeletionPolicy and Finalizers #14719

Conversation

xing-yang commented Jun 4, 2019

netlify bot commented Jun 4, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jingxu97 commented Jun 4, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tengqm commented Jun 6, 2019

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tengqm commented Jun 11, 2019

xing-yang commented Jun 11, 2019

k8s-ci-robot commented Jun 12, 2019

k8s-ci-robot commented Jun 12, 2019

xing-yang commented Jun 12, 2019

k8s-ci-robot commented Jun 25, 2019

zacharysarah commented Aug 6, 2019

k8s-ci-robot commented Aug 6, 2019

netlify bot commented Jun 4, 2019 •

edited